Paginate query results
There are multiple ways to obtain this behavior, let's take a look at a couple of them.
Cursor based pagination
Cursors are used to traverse across entities of an entity set. They work by returning a pointer to a specific entity which can then be used to fetch the next batch of entities. For cursor-based pagination, OpenReader follows the Relay Cursor Connections spec.
In the case of cursor based pagination, for every entity in the input schema, the query name follows the naming convention {entityName}sConnection
pattern.
Example: this query fetches a list of videos where isExplicit
is true and get their count. Thanks to the videosConnection
, we can limit the number of videos to return.
query {
videosConnection(where: { isExplicit_eq: true }) {
totalCount
edges {
node {
id
title
}
}
}
}
Operators first
last
The first
operator is used to fetch specified number of entities from the beginning and last
is vice versa.
Example: Fetch first 5 videos and last 5 videos:
query Query1 {
videosConnection(first: 5) {
edges {
node {
id
title
}
}
}
}
query Query1 {
videosConnection(last: 5) {
edges {
node {
id
title
}
}
}
}
PageInfo object
PageInfo
returns the cursor, page information and object has following fields:
pageInfo {
startCursor
endCursor
hasNextPage
hasPreviousPage
}
Operators before
and after
Example: Fetch a first 10 channels, ordered by createdAt
. Then, in a second query, fetch the next 10 channels:
query FirstBatchQ {
channelsConnection(first: 10, orderBy: createdAt_ASC) {
pageInfo {
endCursor
hasNextPage
}
edges {
node {
id
handle
createdAt
}
}
}
}
query SecondBatchQ {
channelsConnection(after: <endCursor>, orderBy: createdAt_ASC) {
pageInfo {
endCursor
hasNextPage
}
edges {
node {
id
handle
createdAt
}
}
}
}
Example: Fetch the last 10 channels, ordered by createdAt
. Then, in a second query, fetch the previous 10 channels:
query FirstBatchQ {
channelsConnection(last: 10, orderBy: createdAt_ASC) {
pageInfo {
endCursor
hasNextPage
}
edges {
node {
id
handle
createdAt
}
}
}
}
query SecondBatchQ {
channelsConnection(before: <endCursor>, orderBy: createdAt_ASC) {
pageInfo {
endCursor
hasNextPage
}
edges {
node {
id
handle
createdAt
}
}
}
}
Important Note on orderBy
When using orderBy
in a query, the field chosen to order by, needs to be present in the query itself:
query QueryName {
<entity>Connection(before: <endCursor>, orderBy: <fieldNameToOrderBy>_ASC) {
pageInfo {
endCursor
hasNextPage
}
edges {
node {
<anyOtherField>
<fieldNameToOrderBy>
}
}
}
}
Otherwise, the returned result wouldn't be ordered correctly.
Arguments limit
and offset
The operators limit and offset are used for pagination.
limit
specifies the number of entities to retain from the result set and offset
determines which slice to retain from the results.
Note: Default value for limit
is 50
and offset
is 0
.
Limit results
Example: Fetch the first 5 channels:
query {
channels(limit: 5) {
id
handle
}
}
Limit results from an offset
Example: Fetch 5 channels from the list of all channels, starting with the 6th one:
query {
channels(limit: 5, offset: 5) {
id
handle
}
}