GraphQL basics
Introduction
GraphQL is simple to use and easy to learn. We recommend starting your journey at the official GraphQL documentation: Introduction to GraphQL (opens in a new tab). This page explains the basic concepts of fetching data using ROQ Platform.
Queries and mutations
In GraphQL terminology there are two main terms:
- Query - A query is way to load data from ROQ Platform
- Mutation - A mutation is way to change (~mutate) data
Fetch by ID
You can always fetch any record by the ID like this:
await client.asSuperAdmin().user({ id: '123' })
Adding relations
GraphQL empowers the client to define exactly how the data should be returned. In the example below, a user is fetched including the names of all the related user groups.
await client.asSuperAdmin().user({ id: '123', withUserGroups: true })
Counting
When you use a plural query (files
, users
, ...), then you can always ask for the total count.
const response = await client.asSuperAdmin().users();
const { totalCount } = response.users;
Order, Limit and Offset
If you'd like to show the data in a table, you can use the API's advanced functionality with these parameters: limit
,
offset
and sort
.
await client.asSuperAdmin().users({
limit: 10,
offset: 1,
order: {
order: 'ASC',
sort: 'email',
},
})
Parameter | Type | Description |
---|---|---|
limit | number | Limits the number of returned records |
offset | number | Skips records (useful for pagination) |
order | object | Defines order (either ASC or DESC) and the ordered field |
Filtering of data
The filter object enables you to apply advanced filters on all fields. For instance the following query returns only active users.
await client.asSuperAdmin().users({
filter: {
active: {
equalTo: true,
},
},
})