Pagination

Pagination is essential for managing large datasets in GraphQL. This section explains how to implement and use cursor-based pagination effectively in Knowledge Graph.

Cursor-based pagination

Knowledge Graph supports only cursor-based pagination. This method is more efficient and reliable for navigating large or frequently changing datasets.

How cursor-based pagination works

• Cursors are opaque strings that represent a specific position in a result set.

• Clients request a subset of results after a given cursor using the continuationToken and limit arguments.

• The response includes a new continuationToken for fetching the next page of results.

Example query

query {

entities(

input: {

filter: {

where: { /* filter options */ },

orderBy: { /* sort options */ },

}

}

limit: 5,

continuationToken: "<tokenFromPreviousResponse>"

) {

continuationToken

items {

id

name

description

}

}

}

Best practices

• Always use the continuationToken: Use the returned continuationToken to request the next page of results.

• Do not rely on predictable cursor values: Treat tokens as opaque; do not attempt to parse or construct them manually.

• Paginate consistently: Always use the same filtering and ordering criteria when paginating to avoid missing or duplicating results.

• Request only the data you need: Limit the number of items per page (limit argument) to optimize performance and reduce response size.

Operational guidance

• Use deterministic sorting when paging: Include orderBy so result ordering stays stable across pages.

• Do not change query shape mid-pagination: Keep selected fields, filters, and sort criteria consistent while consuming a token sequence.

• Persist continuation tokens in clients: Store the latest token in app state so users can reliably continue from their current page.

• Tune page size by use case:

  • Interactive UI: Start with limit between 20 and 100.

  • Batch export/integration: Use larger limit values only after latency testing.

• Handle end-of-results explicitly: Stop paginating when no continuationToken is returned.

Common pitfalls

• Combining pagination with an unstable query can lead to duplicate or skipped records.

• Reusing old tokens after changing filters or sorting can produce confusing results.

• Requesting too many nested fields per page can make pagination appear slow even with small limits.