Paginating results with GraphQL
When you use a connection to retrieve a list of resources, you use arguments to specify the number of results to retrieve. You can select which set of results to retrieve from a connection by using cursor-based pagination.
A review of connections
Anchor link to section titled "A review of connections"Connections retrieve a list of nodes. A node is an object that has a global ID and is of a type that's defined by the schema, such as the Order
type.
For example, the orders
connection finds all the Order
nodes connected to the query root.
The pageInfo field
Anchor link to section titled "The pageInfo field"Each connection returns a PageInfo
object that assists in cursor-based pagination.
hasPreviousPage
(Boolean!) - Whether there are results in the connection before the current page.hasNextPage
(Boolean!) - Whether there are results in the connection after the current page.startCursor
(String) - The cursor of the first node in thenodes
listendCursor
(String) - The cursor of the last node in thenodes
list
Forward pagination
Anchor link to section titled "Forward pagination"All connections in Shopify's APIs provide forward-pagination. This is achieved with the connection variables:
first
(Int!) - The requested number of nodes per pageafter
(String) - The cursor to retrieve nodes after in the connection. You should generally pass theendCursor
of the previous page asafter
.
You can include the pageInfo
fields in your queries to paginate your results. The following example includes hasNextPage
and endCursor
fields, and uses query variables to pass the endCursor
value as an argument. The $numProducts
variable is required and is used to specify the number of results to return. The $cursor
variable isn't required. When the $cursor
variable is omitted, the after
argument is ignored.
POST /admin/api/2022-07/graphql.json
Variables
JSON response
The response indicates there is a next page and provides the cursor to use as an after
input for the next page of nodes. By using the same query with different variables you can query for the next page:
Variables
JSON response
The response indicates there is no next page. This is the last page of the connection.
Backward pagination
Anchor link to section titled "Backward pagination"Some connections in Shopify's APIs also provide backward-pagination. This is achieved with the connection variables:
last
(Int!) - The requested number of nodes per pagebefore
(String) - The cursor to retrieve nodes before in the connection. You should generally pass thestartCursor
of the previous page asbefore
.
Similar to forward-pagination, we can start at the end of the list of nodes to the beginning:
Variables
JSON response
The startCursor can be used in the subsequent request as the input before
to get the previous page:
Variables
JSON response
Connection Edges
Anchor link to section titled "Connection Edges"In connections, an Edge
type describes the connection between the node and its parent. In almost all cases, querying nodes
and pageInfo
is preferred to querying edges
. However, if you would like the Edge
metadata, edges
can be queried instead of nodes
. Each Edge
contains a minimum of that edge's cursor and the node.
The following query is equilivant to the forward-pagination query. However, it requests a cursor for every edge instead of only the endCursor
.
POST /admin/api/2022-07/graphql.json
Variables
JSON response
The PageInfo endCursor
and the last edge's cursor
are the same. Also, the list of edges[].node
is the equilivent of the nodes
list in the forward-pagination query.