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 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
    }
  }
}

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.