ProductConnection
A connection to a list of Product items, designed to support efficient cursor-based pagination. This connection provides access to the products through edges and nodes, along with pagination metadata and total count information.
Connection Structure
{
edges: [ProductEdge]
nodes: [Product]
pageInfo: PageInfo
totalCount: Int
}
Pagination Arguments
The ProductConnection
supports cursor-based pagination using the following arguments:
Argument | Type | Description |
---|---|---|
first | Int | Returns the first n elements from the list. |
last | Int | Returns the last n elements from the list. |
before | String | Returns elements before the specified cursor. |
after | String | Returns elements after the specified cursor. |
Constraints:
first
andlast
cannot be used simultaneously.before
andafter
are used to define the cursor position for backward and forward pagination respectively.- Reasonable page sizes (e.g., 10-50) are recommended to optimize performance.
PageInfo Structure
The pageInfo
field provides metadata about the current page of results:
{
hasNextPage: Boolean
hasPreviousPage: Boolean
startCursor: String
endCursor: String
}
hasNextPage
: Indicates if there are more items when paginating forward.hasPreviousPage
: Indicates if there are more items when paginating backward.startCursor
: The cursor corresponding to the first item in the current page.endCursor
: The cursor corresponding to the last item in the current page.
Usage Examples
Basic Pagination
Fetch the first 10 products with pagination info:
{
products(first: 10) {
edges {
cursor
node {
id
title
price
}
}
pageInfo {
hasNextPage
endCursor
}
totalCount
}
}
Forward Pagination
Fetch the next 10 products after a specific cursor:
{
products(first: 10, after: "YXJyYXljb25uZWN0aW9uOjEw") {
edges {
cursor
node {
id
title
price
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
Backward Pagination
Fetch the previous 5 products before a specific cursor:
{
products(last: 5, before: "YXJyYXljb25uZWN0aW9uOjIw") {
edges {
cursor
node {
id
title
price
}
}
pageInfo {
hasPreviousPage
startCursor
}
}
}
Cursor-based Navigation
Navigate through pages using cursors to fetch subsequent pages:
# Initial request to get first 10 products and the endCursor
{
products(first: 10) {
edges {
cursor
node {
id
title
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
# Use the endCursor from above to fetch the next page
{
products(first: 10, after: "YXJyYXljb25uZWN0aW9uOjEw") {
edges {
cursor
node {
id
title
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
Combined with Filtering
Fetch the first 15 products sorted by price ascending and filtered by a category ID (assuming filtering and sorting are supported by the products
query):
{
products(first: 15, filter: {categoryId: 123}, sortBy: {field: PRICE, direction: ASC}) {
edges {
cursor
node {
id
title
price
category {
id
name
}
}
}
pageInfo {
hasNextPage
endCursor
}
totalCount
}
}
Edge Type
The ProductConnection
contains a list of ProductEdge
objects. Each edge represents a single product node and includes a cursor for pagination.
{
cursor: String
node: Product
}
cursor
: An opaque string used to paginate through the list.node
: The actualProduct
object containing product details.
Edges enable precise navigation through the product list by providing cursors that mark positions in the connection.
Pagination Best Practices
- Use cursor-based pagination (
first
/after
orlast
/before
) instead of offset-based pagination for consistent and performant results. - Always check
pageInfo.hasNextPage
andpageInfo.hasPreviousPage
to determine if more pages are available. - Limit the number of items requested per page to avoid large payloads and slow responses.
- Use cursors returned in edges to navigate forward or backward efficiently.
- Combine pagination with filtering and sorting to reduce the dataset size and improve response times.
Performance Considerations
- Avoid requesting very large page sizes; typical page sizes between 10 and 50 items balance performance and usability.
- Use filtering and sorting arguments to narrow down results before paginating.
- Cache cursors and results when possible to reduce repeated queries.
- Monitor query execution times and optimize queries if pagination becomes slow.
- Pagination queries are read-heavy; consider rate limiting to protect API stability.
Related Types
ProductEdge
: Represents an edge in the product connection with a cursor and node.Product
: The product object containing detailed product information.PageInfo
: Contains pagination metadata such as cursors and page availability.
Notes
- The API currently requires no authentication for accessing product connections, but this may change in future versions.
- Handle edge cases such as empty results gracefully by checking if
edges
ornodes
arrays are empty. - When a single page contains all results,
pageInfo.hasNextPage
andpageInfo.hasPreviousPage
will both befalse
. - Always implement error handling for pagination queries to manage invalid cursors or argument misuse.
- Rate limiting may apply to paginated queries to ensure fair usage and API stability.