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',
  },
})

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,
    },
  },
})