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.
How it works
Anchor link to section titled "How it works"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
object
Anchor link to section titled "The PageInfo object"In the GraphQL Admin API, each connection returns a PageInfo
object that assists in cursor-based pagination. The PageInfo
object is composed of the following fields:
Field | Type | Description |
---|---|---|
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 nodes list. |
endCursor |
string | The cursor of the last node in the nodes list. |
Forward pagination
Anchor link to section titled "Forward pagination"All connections in Shopify's APIs provide forward pagination. This is achieved with the following connection variables:
Field | Type | Description |
---|---|---|
first |
integer | The requested number of nodes for each page. |
after |
string | The cursor to retrieve nodes after in the connection. Typically, you should pass the endCursor of the previous page as after . |
You can include the PageInfo
fields in your queries to paginate your results. The following example includes the hasNextPage
and endCursor
fields, and uses query variables to pass the endCursor
value as an argument:
By using the same query with different variables, you can query for the next page:
Backward pagination
Anchor link to section titled "Backward pagination"Some connections in Shopify's APIs also provide backward pagination. This is achieved with the following connection variables:
Field | Type | Description |
---|---|---|
last |
integer | The requested number of nodes for each page. |
before |
string | The cursor to retrieve nodes before in the connection. Typically, you should pass the startCursor of the previous page as before . |
Similar to forward pagination, you can start at the end of the list of nodes, and then query in reverse page order to the beginning. The following example includes the hasPreviousPage
and startCursor
fields, and uses query variables to pass the startCursor
value as an argument:
The startCursor
field can also be used in the subsequent request as the input before
to get the previous page:
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 want the Edge
metadata, then you can query edges
instead of nodes
. Each Edge
contains a minimum of that edge's cursor and the node.
The following query is equivalent to the forward pagination query. However, it requests a cursor for every edge instead of only the endCursor
: