Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 37 ยท Schema Design

Pagination: Offset, Cursor and Connections

Paginate GraphQL lists the robust way: see why offsets drift, then build cursor pagination with edges, nodes, pageInfo and opaque base64 cursors.

Almost every real list is too long to send at once: posts, orders, search results, comments. A GraphQL API needs a way for clients to ask for "the next ten". The obvious answer is limit and offset, and it works until the data changes under your feet. The robust answer is cursor pagination, and GraphQL has a widely used convention for it, usually called the connection pattern or the Relay specification.

Reminder: no real GraphQL server or database runs on this site. The schema and queries are read-only text, and the runnable examples are stand-ins written in plain JavaScript.

Offset pagination and where it breaks

Offset pagination takes two numbers: how many items to return and how many to skip.

GRAPHQL
type Query {
  posts(limit: Int = 10, offset: Int = 0): [Post!]!
}

It is simple, and it allows jumping straight to page 7. It has two well-known problems.

  1. Drift. Between the request for page 1 and the request for page 2, someone adds or deletes an item. Everything shifts by one: an item is shown twice or never shown at all.
  2. Cost. To skip 100,000 rows a database usually still walks past them. OFFSET 100000 gets slower as the offset grows.

The stand-in below makes the first problem visible. A feed is sorted newest first. A reader loads page 1 (three items), a new post arrives, then the reader loads page 2.

JS Offset pagination drifts when data changes

Press Run (or Ctrl + Enter) to see the console output here.

No output.

"post 3" appears on both pages, because the new post pushed everything down by one place. On a feed that changes constantly this is an everyday bug.

Cursor pagination

A cursor is a marker that says this item, not position 3. The client asks for "the next three items after this cursor". New items inserted before the marker do not move it, so nothing repeats.

GRAPHQL
type Query {
  posts(first: Int = 10, after: String): [Post!]!
}

How the cursor is built is the server's business. Often it encodes the sort key of the last item (a timestamp plus an id, or just the id). The query for the next page then becomes a condition rather than a skip:

SQL
SELECT * FROM posts
WHERE (created_at, id) < (:cursorCreatedAt, :cursorId)
ORDER BY created_at DESC, id DESC
LIMIT 11;

(Read-only. The tuple comparison syntax varies between databases.) The database can use an index and jump directly to the place, so the page costs about the same however deep it is. Selecting LIMIT 11 for a page of 10 is a common trick: if an eleventh row exists there is a next page.

The price: no random access. A client cannot jump to "page 7" without walking there. For infinite scroll, "load more" and feeds, that is fine. For a table with numbered pages, offset (or a hybrid) may still be the better fit.

The connection pattern

Returning just a list leaves nowhere to put the cursor or the "is there more?" flag. The Relay connection convention fixes this with a small set of types:

GRAPHQL
type Query {
  posts(first: Int, after: String, last: Int, before: String): PostConnection!
}

type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
  totalCount: Int
}

type PostEdge {
  node: Post!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

The connection shape

Connection The whole page result.
Edge One item plus its cursor.
Node The item itself.
PageInfo Is there more? Where to continue?

Ask for first and after to go forward; last and before to go back.

1 / 2
  • edges is the list of results. Each edge wraps one node (the actual Post) and that node's cursor.
  • pageInfo answers "is there another page?" (hasNextPage) and gives the cursors to continue (endCursor for going forward).
  • first/after page forward; last/before page backward. Most APIs support only the forward pair.
  • totalCount is optional. Counting is expensive on big tables, so many APIs omit it or make it a separate field that is computed only when asked.

A client query looks like this, and the next one passes the endCursor it just received as after:

GRAPHQL
query Posts($after: String) {
  posts(first: 10, after: $after) {
    edges {
      cursor
      node { id title }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Why the extra level of edges? An edge is a place to hang information about the relationship between the list and the item, not about the item itself (for example "when was this person added to the team"). That is the design reason; in return, queries are a little more verbose than a flat list.

Opaque cursors

Cursors are usually base64-encoded strings. Encoding is not about secrecy. It tells clients: "do not look inside, do not build your own, just send it back". If clients start parsing cursors (cursor.split(":")), you can never change how they are made. Because they are opaque, you may later add a second sort key or change the format, and no client breaks.

JavaScript
const cursor = btoa("id:42");   // "aWQ6NDI="
const decoded = atob(cursor);   // "id:42"

Validate cursors on the server like any other input: a malformed one should produce a clear user-facing error, not a crash or a wrong page. And never put anything sensitive in one.

A stand-in connection builder

The code below keeps the posts in a plain array sorted by id, and implements posts(first, after) returning a connection. It is the logic a real resolver would hand to a database. Follow how it walks through all pages, including one that is shorter than requested, and how an invalid cursor is handled.

JS Building a Relay-style connection

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Three pages of 3, 3 and 1 items: the last page has hasNextPage: false, which tells the client to stop. The unusual cursor not-a-cursor! is rejected instead of being guessed at.

In a real server the filtering line becomes a database condition on an indexed column, and the extra-row trick becomes LIMIT first + 1. The shape of the returned object is the part that stays the same. Libraries for most languages already provide helpers for the connection types, so you rarely write them by hand in production.

Choosing a style

Offset Cursor / connection
Jump to page N Yes No
Stable while data changes No Yes
Deep pages Slower and slower Constant cost
Schema size One argument pair Three extra types
Good for Small, static, admin tables Feeds, infinite scroll, public APIs

Whichever you pick, always put an upper limit on first (say, 100) and a sensible default. An unbounded page size is a denial-of-service waiting to happen; see Query Depth, Complexity and Other Attacks.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What problem does cursor pagination solve that offset pagination has?

    A cursor points at an item rather than a position, so inserting or deleting earlier items does not shift the next page.
  2. 2. In the connection pattern, what does an edge contain?

    An edge wraps one node (the item) together with that node's cursor, and is a place to attach data about the relationship.
  3. 3. Why are cursors encoded as opaque strings?

    Encoding is not security. It discourages clients from parsing or constructing cursors, leaving the server free to change how they are built.
  4. 4. How can a resolver cheaply find out whether there is a next page?

    Requesting first + 1 rows reveals whether more exist without a count query. The extra row is dropped before returning.

Summary

  • Offset pagination is simple but drifts when data changes and slows down for deep pages.
  • Cursors mark an item, not a position, so pages stay consistent and deep pages stay cheap, at the cost of random access.
  • The connection pattern returns edges (each with node and cursor) and a pageInfo with hasNextPage and endCursor.
  • Treat cursors as opaque, validate them, and cap the page size.

Next: Modeling Errors.