Skip to Content

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:

ArgumentTypeDescription
firstIntReturns the first n elements from the list.
lastIntReturns the last n elements from the list.
beforeStringReturns elements before the specified cursor.
afterStringReturns elements after the specified cursor.

Constraints:

  • first and last cannot be used simultaneously.
  • before and after 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 actual Product 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 or last/before) instead of offset-based pagination for consistent and performant results.
  • Always check pageInfo.hasNextPage and pageInfo.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.
  • 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 or nodes arrays are empty.
  • When a single page contains all results, pageInfo.hasNextPage and pageInfo.hasPreviousPage will both be false.
  • 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.
Last updated on