Here, we assume that you are generally familiar with GraphQL. This section explains the ROQ approach of using GraphQL.

ROQ provides two types of queries: queries that return a single item and queries that return multiple items. The structure of these queries is slightly different. The following examples use the user object, however the approach is the same for all other types of objects.

Simple queries

Show a single user by ID

{
  user(id: "151e58ec-...74a2") {
    id
    email
  }
}
GRAPHQL

The query above returns the user's ID and email address. There are more fields available, which you can see in the client's auto-completion like this:

Show a single user by ID and the user's accepted invite

GraphQL enables you to define the result that you need on the client side. The following query includes the invite object of the user (if any).

{
  user(id: "151e58ec-...74a2") {
    id
    acceptedUserInvite {
      id
      email
    }
  }
}
GRAPHQL

Show all users

{
  users {
    data {
      id
      email
    }
  }
}
GRAPHQL

Show total number of users

{
  users {
    data {
      id
      email
    }
  }
}
GRAPHQL

Using 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

  • order - JSON object that contains order (either ASC or DESC) and the ordered field.

{
  users(limit: 10, offset: 0, order: {order: ASC, sort: CREATED_AT}) {
    data {
      id
      createdAt
    }
  }
}
GRAPHQL

Using filters

The filter object enables you to apply advanced filters. This is typically used for data-tables, and the filter argument is a JSON object. The values depend on the type of the data.

Example:

show active users only

{
  users(filter: {active: {equalTo: true}}) {
    data {
      id
      active
    }
  }
}
GRAPHQL

Example:

show all users that opted-in since 2022

{
  users(filter: {optedInAt: {moreThan: "2022"}}) {
    data {
      id
      optedInAt
    }
  }
}
GRAPHQL

Using search

The search parameter enables you to perform simple searches. The example below shows all users that have an email which contains the term "roq".

{
  users(search: {key: EMAIL, value: "roq"}) {
    data {
      id
      email
    }
  }
}
GRAPHQL