ProductConnection
The ProductConnection
type represents a paginated list of products using cursor-based pagination. It provides a standardized way to navigate through large sets of product data efficiently by dividing the results into manageable pages.
Connection Structure
{
edges: [ProductEdge]
pageInfo: PageInfo
}
edges
: A list ofProductEdge
objects, each containing anode
(the product) and acursor
for pagination.pageInfo
: Contains metadata about the current page of results, such as whether there are more pages available.
Pagination Arguments
The ProductConnection
supports the following pagination arguments to control the size and direction of the paginated results:
Argument | Type | Description |
---|---|---|
first | Int | Returns the first n elements from the list. Must be a positive integer. |
last | Int | Returns the last n elements from the list. Must be a positive integer. |
before | String | Returns elements before the specified cursor. Used for backward pagination. |
after | String | Returns elements after the specified cursor. Used for forward pagination. |
Constraints:
- You cannot use
first
andlast
together in the same query. - When using
first
orafter
, the results paginate forward. - When using
last
orbefore
, the results paginate backward.
PageInfo Structure
{
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
hasNextPage
: Indicates if there are more pages after the current page.hasPreviousPage
: Indicates if there are pages before the current page.startCursor
: The cursor corresponding to the first item in the current page.endCursor
: The cursor corresponding to the last item in the current page.
These fields help clients determine whether to fetch more data and how to construct subsequent pagination queries.
Usage Examples
Basic Pagination
Fetch the first 5 products:
{
products(first: 5) {
edges {
node {
id
title
price
}
cursor
}
pageInfo {
hasNextPage
endCursor
}
}
}
Forward Pagination
Fetch the next 5 products after a given cursor:
{
products(first: 5, after: "YXJyYXljb25uZWN0aW9uOjQ=") {
edges {
node {
id
title
price
}
cursor
}
pageInfo {
hasNextPage
endCursor
}
}
}
Backward Pagination
Fetch the previous 5 products before a given cursor:
{
products(last: 5, before: "YXJyYXljb25uZWN0aW9uOjEw") {
edges {
node {
id
title
price
}
cursor
}
pageInfo {
hasPreviousPage
startCursor
}
}
}
Cursor-based Navigation
Navigate through pages using cursors:
{
products(first: 3) {
edges {
node {
id
title
}
cursor
}
pageInfo {
hasNextPage
endCursor
}
}
}
Use the endCursor
from the response to fetch the next page:
{
products(first: 3, after: "YXJyYXljb25uZWN0aW9uOjM=") {
edges {
node {
id
title
}
cursor
}
pageInfo {
hasNextPage
endCursor
}
}
}
Combined with Filtering
Combine pagination with filtering by product title (assuming the API supports a query
argument for filtering):
{
products(first: 5, query: "title:'Sneakers'") {
edges {
node {
id
title
price
}
cursor
}
pageInfo {
hasNextPage
endCursor
}
}
}
Edge Type
type ProductEdge {
node: Product
cursor: String
}
node
: The product item at the end of the edge. This field may benull
if the product is unavailable.cursor
: An opaque string used to paginate through the product list.
The ProductEdge
acts as a wrapper around each product node, providing the cursor necessary for pagination.
Pagination Best Practices
- Use reasonable page sizes (e.g., 5-50 items) to balance performance and user experience.
- Always check
pageInfo.hasNextPage
andpageInfo.hasPreviousPage
before attempting to fetch more data. - Use cursors returned by the API (
startCursor
andendCursor
) for reliable navigation instead of relying on offsets or IDs. - Handle cases where
edges
may be empty gracefully, indicating no results or end of data. - Avoid requesting very large pages to reduce response time and server load.
Performance Considerations
- Cursor-based pagination is efficient for large datasets because it avoids skipping records.
- Avoid deep pagination (very large offsets) as it can degrade performance.
- Use filtering and sorting arguments where available to reduce the dataset before paginating.
- Cache cursors and pageInfo data on the client side to minimize repeated requests.
Related Types
- Product: Represents the product entity returned in the
node
field ofProductEdge
. - PageInfo: Provides pagination metadata for the connection.
Notes
- The API currently requires no authentication for accessing product data, but this may change in future versions.
- Always implement error handling for scenarios such as invalid cursors or exceeding rate limits.
- Rate limiting may apply to paginated queries; consider implementing retry logic with exponential backoff.
- Empty results may occur when filtering yields no matches or when paginating beyond available data. Handle these cases gracefully in your UI.