Skip to Content

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 of ProductEdge objects, each containing a node (the product) and a cursor 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:

ArgumentTypeDescription
firstIntReturns the first n elements from the list. Must be a positive integer.
lastIntReturns the last n elements from the list. Must be a positive integer.
beforeStringReturns elements before the specified cursor. Used for backward pagination.
afterStringReturns elements after the specified cursor. Used for forward pagination.

Constraints:

  • You cannot use first and last together in the same query.
  • When using first or after, the results paginate forward.
  • When using last or before, 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 be null 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 and pageInfo.hasPreviousPage before attempting to fetch more data.
  • Use cursors returned by the API (startCursor and endCursor) 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.
  • Product: Represents the product entity returned in the node field of ProductEdge.
  • 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.
Last updated on