How to page through the result set from a GraphQL API query

Modified on Tue, 3 Mar at 12:08 PM

Paging through results

The GraphQL API uses two parameters to control paging through the result set: 'take' and 'skip'.

take specifies how many results to return. This defaults to 10.

skip specifies how many results to skip. This defaults to 0.

Both 'take' and 'skip' are optional but if specified should be included in brackets with the object being retrieved.

Here is an example of a query returning all GOLD rated companies:

query example {
  companies(where:{generated_rfa_rating:{eq:GOLD}}){
    items{
      company_number
      company_name
      generated_rfa_rating
    }
  }
}

This will only return the first 10 companies found since take has not been specified and the default value for 'take' is 10.

We can specify a 'take' value of 100 to get the first 100 results:

query example {
  companies(take:100 where:{generated_rfa_rating:{eq:GOLD}}){
    items{
      company_number
      company_name
      generated_rfa_rating
    }
  }
}

If we want to get the second page we can use 'skip' to skip past the first 100 results and use 'take' to get the next set of 100 results.

query example {
  companies(take:100 skip: 100 where:{generated_rfa_rating:{eq:GOLD}}){
    items{
      company_number
      company_name
      generated_rfa_rating
    }
  }
}

Notes:

The values of 'take' and 'skip' will probably be best passed as parameters to the query to avoid having to rebuild the query string each time. See Using Variables in GraphQL for more information.
There is a hard limit of 10,000 records that can be retrieved in any one operation. If you attempt to use 'take' or 'skip' to exceed 10,000 records you will get an error message.
It may be advisable to specify a 'sort order' when using paging to ensure consistency of results. See Ordering the Result for more information.

If you have any further questions, please reach out to our Support Team via Contact Us.