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 connectionsAnchor 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
For example, the
orders connection finds all the
Order nodes connected to the query root.
The pageInfo fieldAnchor 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 the
endCursor(String) - The cursor of the last node in the
Forward paginationAnchor 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 page
after(String) - The cursor to retrieve nodes after in the connection. You should generally pass the
endCursorof the previous page as
You can include the
pageInfo fields in your queries to paginate your results. The following example includes
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.
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:
The response indicates there is no next page. This is the last page of the connection.
Backward paginationAnchor 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 page
before(String) - The cursor to retrieve nodes before in the connection. You should generally pass the
startCursorof the previous page as
Similar to forward-pagination, we can start at the end of the list of nodes to the beginning:
The startCursor can be used in the subsequent request as the input
before to get the previous page:
Connection EdgesAnchor 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
pageInfo is preferred to querying
edges. However, if you would like the
edges can be queried instead of
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 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.