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
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
Ordertype. Nodes are said to be connected by edges.
For example, the
orders connection finds all the edges that connect the query root to a Order node, and then returns the requested data from each node. You can even nest connections within other connections, such as using the
lineItems connection to retrieve the line items for each order in the
To paginate the list of orders, you need to return data that isn't included on the Order type. This data includes whether there are more results in the connection, and which orders are included in the current results. To let you select fields that aren't on the node object, Shopify includes the
node layers in every connection:
- edges — Used to select the fields that you want to retrieve from each edge in the connection. The
edgesfield is similar to a for-loop because it retrieves the selected fields from each edge in the connection.
- node — Used to select the fields that you want to retrieve from the node at each edge.
Specifying fields at the connection, edge, and node levels lets you include fields that are used for pagination:
The pageInfo field
Each connection can return a PageInfo object, which has two fields:
hasNextPage(Boolean!) — Whether there are results in the connection after the current segment.
hasPreviousPage(Boolean!) — Whether there are results in the connection before the current segment.
You retrieve page information once per query rather than at each edge, so include
pageInfo at the connection level beside the
The cursor field
Each edge in a connection can return a cursor, which is a reference to the edge's position in the connection. The cursor is a property of the edge rather than the node, so include the
cursor field at the edge level beside the
You can use an edge's cursor as the starting point to retrieve the nodes before or after it in a connection.
You can include the
cursor fields in your queries to paginate your results. The following example includes both fields, and uses query variables to pass their values as arguments. The
$orderNum 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 missing, the
after argument is ignored.
The query returns three results from the beginning of the connection, and they include a cursor for each edge.
In the next example, the cursor from
The Blouse is used as the starting point for the connection results. The example retrieves the next three results after that point in the connection: