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.
> Note:
> You can retrieve up to a maximum of 250 resources. If you need to paginate larger volumes of data, then you can [perform a bulk query operation](/docs/api/usage/bulk-operations/queries) using the GraphQL Admin API.
## How it works
Connections retrieve a list of nodes. A node is an object that has a [global ID](/docs/api/usage/gids) 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 `nodes` field is similar to a for-loop because it retrieves the selected fields from each node in the connection.
To optimize performance and user experience, you can request only a certain number of nodes at a time. The batch of nodes that is returned is known as a page. The position of each node in the array is indicated by its cursor.
To retrieve the next page of nodes, you need to indicate the position of the node the page should start from. You can do so by providing a cursor. You can retrieve cursor information about the current page using [the `PageInfo` object](#the-pageinfo-object), and use that cursor value in a subsequent query by passing it in a [`after`](#forward-pagination) or [`before`](#backward-pagination) argument.
> Tip:
> You can also retrieve a list of nodes using [edges](#connection-edges).
### The `PageInfo` object
In the GraphQL Admin API, each connection returns a [`PageInfo`](/docs/api/admin-graphql/latest/objects/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. |
> Note:
> The `PageInfo` object in the GraphQL Partner API is only composed of the `hasNextPage` and `hasPreviousPage` fields.
## 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`. |
### Examples
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
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`. |
### Examples
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
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.
### Example
The following query is equivalent to the [forward pagination query](/docs/api/usage/pagination-graphql#forward-pagination). However, it requests a cursor for every edge instead of only the `endCursor`:
## Search performance considerations
Paginating resources using a [range search](/docs/api/usage/search-syntax#search-query-syntax) might timeout or return an error if the collection of resources is sufficiently large, and the search field is different from the specified (or default) sort key for the connection you are querying. If your query is slow or returns an error, then try specifying a sort key that matches the field used in the search. For example: