1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
---
stage: Manage
group: Authentication and Authorization
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Query users with GraphQL **(FREE)**
This page describes how you can use the GraphiQL explorer to query users.
You can run the same query directly via a HTTP endpoint, using `cURL`. For more information, see our
guidance on getting started from the [command line](getting_started.md#command-line).
The [example users query](#set-up-the-graphiql-explorer) looks for a subset of users in
o
a GitLab instance either by username or
[Global ID](../../development/api_graphql_styleguide.md#global-ids).
The query includes:
- [`pageInfo`](#pageinfo)
- [`nodes`](#nodes)
## `pageInfo`
This contains the data needed to implement pagination. GitLab uses cursor-based
[pagination](getting_started.md#pagination). For more information, see
[Pagination](https://graphql.org/learn/pagination/) in the GraphQL documentation.
## `nodes`
In a GraphQL query, `nodes` is used to represent a collection of [`nodes` on a graph](https://en.wikipedia.org/wiki/Vertex_(graph_theory)).
In this case, the collection of nodes is a collection of `User` objects. For each one,
we output:
- Their user's `id`.
- The `membership` fragment, which represents a Project or Group membership belonging
to that user. Outputting a fragment is denoted with the `...memberships` notation.
The GitLab GraphQL API is extensive and a large amount of data for a wide variety of entities can be output.
See the official [reference documentation](reference/index.md) for the most up-to-date information.
## Set up the GraphiQL explorer
This procedure presents a substantive example that you can copy and paste into GraphiQL
explorer. GraphiQL explorer is available for:
- GitLab.com users at [https://gitlab.com/-/graphql-explorer](https://gitlab.com/-/graphql-explorer).
- Self-managed users at `https://gitlab.example.com/-/graphql-explorer`.
1. Copy the following code excerpt:
```graphql
{
users(usernames: ["user1", "user3", "user4"]) {
pageInfo {
endCursor
startCursor
hasNextPage
}
nodes {
id
username,
publicEmail
location
webUrl
userPermissions {
createSnippet
}
}
}
}
```
1. Open the [GraphiQL explorer tool](https://gitlab.com/-/graphql-explorer).
1. Paste the `query` listed above into the left window of your GraphiQL explorer tool.
1. Select **Play** to get the result shown here:
NOTE:
[The GraphQL API returns a GlobalID, rather than a standard ID.](getting_started.md#queries-and-mutations) It also expects a GlobalID as an input rather than
a single integer.
This GraphQL query returns the specified information for the three users with the listed username. Since the GraphiQL explorer uses the session token to authorize access to resources,
the output is limited to the projects and groups accessible to the currently signed-in user.
If you've signed in as an instance administrator, you would have access to all records, regardless of ownership.
If you are signed in as an administrator, you can show just the matching administrators on the instance by adding the `admins: true` parameter to the query changing the second line to:
```graphql
users(usernames: ["user1", "user3", "user4"], admins: true) {
...
}
```
Or you can just get all of the administrators:
```graphql
users(admins: true) {
...
}
```
For more information on:
- GraphQL specific entities, such as Fragments and Interfaces, see the official
[GraphQL documentation](https://graphql.org/learn/).
- Individual attributes, see the [GraphQL API Resources](reference/index.md).
|
