GraphQL Pagination: Cursors, Connections and the Relay Pattern
Why offset/limit produces duplicates and gaps in changing lists, and how cursor-based pagination with the connections pattern stays stable – including the schema, a resolver sketch and the pitfalls from real projects.
If you page through a list by position, you silently rely on nobody writing in the meantime. In production, this assumption rarely holds. A position is not an anchor in the data; it is a count – and counts shift as soon as a record is added or removed at the front. The follow-up request then no longer asks the question the client meant to ask.
That’s why pagination is one of the places where it shows whether an API is robust or only works in the demo case. As long as the list stands still, offset/limit does its job flawlessly. As soon as it changes under the paging client – and that is the normal case, not the exception – errors arise that are hard to reproduce and even harder to explain. For exactly this, the GraphQL community established a convention of its own: the connections pattern. That’s what this post is about.
Why offset/limit fails with changing lists#
Let’s make the problem concrete. I have a list sorted by creation date in descending order and page through it two at a time. The client requests the first page: offset: 0, limit: 2. It gets the entries at positions 0 and 1. For the next page it asks for offset: 2, limit: 2.
The insidious part: offset is a pure position count. It says “skip the first two elements” – but it has no idea which two elements those were on the first call. If a new entry is inserted at the front between the two requests, the whole list slides back by one position. The element that was just at position 1 is now at position 2 – and is delivered to the client a second time at offset: 2. A duplicate.
The reverse case is just as annoying: if an entry at the front is deleted, everything moves forward by one position. The element that was at position 2 jumps to position 1 – and is skipped at offset: 2. A gap. The user never sees an entry, even though it exists.
flowchart TB
subgraph stabil["Stable: cursor-based"]
direction LR
a1["Request 1<br/>first: 2"] --> a2["returns A, B<br/>endCursor = B"]
a2 --> a3["Request 2<br/>after: cursor of B"]
a3 --> a4["returns C, D<br/>no duplicate"]
end
subgraph kaputt["Shifted: offset/limit"]
direction LR
b1["Request 1<br/>offset 0, limit 2"] --> b2["returns A, B"]
b2 --> b3["new entry X<br/>inserted at the front"]
b3 --> b4["Request 2<br/>offset 2, limit 2"]
b4 --> b5["returns B, C<br/>B duplicated"]
endThe core is always the same: offset counts positions, and positions are not a stable anchor as soon as the front of the list changes. Offset is like the train announcement “get off at the third stop” – wonderful, as long as nobody adds an extra stop.
The cursor-based way out#
The solution is to change the question. Instead of “give me the elements from position N”, the client asks “give me the elements after this specific element”. This “specific element” is represented by a cursor – an opaque pointer that the server hands out and the client passes back unchanged.
The crucial difference: a cursor is bound to an element or its sort value, not to a position. When the client says “continue after the element with cursor X”, this statement stays correct no matter how many entries are inserted or deleted before it. The window doesn’t shift, because it doesn’t depend on a count but on an anchor in the data.
A point that regularly comes up in code reviews: the cursor is opaque. The client must not assume any structure and must not do any arithmetic with it. It may only hand it back. This is deliberate – the server alone decides what a cursor means. Today it may contain an ID, tomorrow a combination of sort field and ID, the day after something completely different. As long as the client only passes the cursor through, the server can change its cursor implementation without breaking a single client. Base64 encoding is common – but that’s convention, not a rule, and only serves to keep anyone from being tempted to interpret the content.
The connections pattern: edges, node, pageInfo#
This brings us to the actual topic. Around cursor-based pagination, the GraphQL community formalized a convention: the Relay Cursor Connections Specification. You don’t have to use Relay as a framework to benefit from the pattern – it has established itself as a de facto standard because it cleanly solves an important question: where do I actually put the cursor?
The naive answer would be to stick the cursor directly onto the record. But the cursor is not a property of the user or the article – it is a property of this position in this list. That’s why the pattern introduces an intermediate layer, the edge. An edge connects the actual record (node) with its cursor. The node stays clean, and the list-specific information sits on the edge.
Above it sits the connection. It bundles the list of edges and an object called pageInfo, which carries the metadata for paging further.
What exactly do the individual building blocks provide?
edgesis the list of edges. Each edge containsnode(the plain record, without a list wrapper) andcursor(the opaque pointer to exactly this edge).pageInfo.hasNextPagesays whether there are more elements after the current page. This is the authoritative stop condition for paging.pageInfo.hasPreviousPageis the counterpart for the backward direction.pageInfo.endCursoris the cursor of the last element of the current page – exactly the value the client puts into the follow-up request asafter.pageInfo.startCursoris its counterpart at the start of the page, relevant for paging backward withbefore.
On naming conventions: the connection type ends in Connection, the edge type in Edge. pageInfo is non-null, and so are the two booleans in PageInfo. The two cursor fields startCursor and endCursor, by contrast, are nullable – on an empty page there simply is no cursor.
A commonly seen field is totalCount, the total number of hits. It is handy, but it has a catch: totalCount is not part of the connections specification. It is a widespread optional extension, and depending on the data source, an exact COUNT can be expensive. If you include it, do so deliberately and not under the assumption that it belongs to the standard.
An example schema#
Enough prose, let’s look at SDL. A query that returns users with pagination looks like this in the connections pattern:
type Query {
users(first: Int, after: String): UserConnection!
}
type UserConnection {
edges: [UserEdge!]!
pageInfo: PageInfo!
totalCount: Int
}
type UserEdge {
node: User!
cursor: String!
}
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
type User {
id: ID!
name: String!
createdAt: String!
}
The arguments follow the specification. For forward pagination there is first: Int (the desired page size, non-negative) and after: String (the cursor after which to continue). For the backward direction, there are last: Int and before: String accordingly. Sending first and last at the same time is explicitly discouraged by the specification – the result would be ambiguous.
A query from the client then reads like this:
query FirstPage {
users(first: 2) {
edges {
cursor
node {
id
name
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
And the follow-up request takes the endCursor from the previous response as after:
query NextPage {
users(first: 2, after: "dXNlcjpjdXJzb3I6NDI=") {
edges {
cursor
node {
id
name
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
Many introductory examples – including my own fundamentals material – show simplified variants, such as skip/take or an after: 99 where the cursor looks suspiciously like an ID or an offset. That’s fine for explaining, but it isn’t the real Relay pattern. A production cursor is opaque and does not look like a readable number. This distinction is worth the extra sentence; otherwise someone will later start calculating with the cursor on the client.
The resolver sketch#
On the server side, the resolver has to do three things: decode the incoming cursor, load the matching set of data and build edges plus pageInfo from it. The most interesting trick lies in determining hasNextPage.
A common beginner’s mistake is to derive hasNextPage from whether the result is smaller than first. That’s unreliable: if exactly first elements happen to be left, you wouldn’t know whether anything comes after them. The clean way is to load one element more than requested – first + 1. If this extra element exists, there is a next page. Afterwards, you trim the result back to first.
function encodeCursor(id) {
return Buffer.from(`cursor:${id}`).toString("base64");
}
function decodeCursor(cursor) {
const decoded = Buffer.from(cursor, "base64").toString("utf8");
return Number(decoded.split(":")[1]);
}
async function usersResolver(_parent, args, context) {
const { first = 20, after } = args;
const limit = Math.min(first, 100); // enforce an upper bound
const afterId = after ? decodeCursor(after) : 0;
// load one extra row to detect a following page
const rows = await context.db.query(
`SELECT id, name, created_at
FROM users
WHERE id > $1
ORDER BY id ASC
LIMIT $2`,
[afterId, limit + 1]
);
const hasNextPage = rows.length > limit;
const pageRows = hasNextPage ? rows.slice(0, limit) : rows;
const edges = pageRows.map((row) => ({
node: row,
cursor: encodeCursor(row.id),
}));
return {
edges,
pageInfo: {
hasNextPage,
hasPreviousPage: Boolean(after),
startCursor: edges.length ? edges[0].cursor : null,
endCursor: edges.length ? edges[edges.length - 1].cursor : null,
},
};
}
Two details are worth a second look. First, the upper bound: without a Math.min, a client could send first: 1000000 and bring the database to its knees. An enforced upper bound is mandatory, not optional. Second, the cursor helpers encodeCursor/decodeCursor – they demonstrate that the opaque string here simply contains an ID, but that the client doesn’t need to know that.
As a dialog between client and server, the flow across several pages looks like this:
sequenceDiagram participant C as Client participant S as Server C->>S: users(first: 2) S-->>C: edges A, B<br/>pageInfo endCursor=B, hasNextPage=true C->>S: users(first: 2, after: Cursor B) S-->>C: edges C, D<br/>pageInfo endCursor=D, hasNextPage=true C->>S: users(first: 2, after: Cursor D) S-->>C: edges E<br/>pageInfo endCursor=E, hasNextPage=false Note over C,S: Loop ends as soon as hasNextPage=false
So the client pages in a simple loop: as long as hasNextPage is true, it sends the next request with the most recently received endCursor as after. No counting positions, no recalculating.
The price of sorting – and a database bonus#
One place where cursor-based pagination silently fails is ambiguous sorting. The cursor needs a deterministic, unique order. If I sort only by created_at, for example, and two records carry the same timestamp, then it is undefined at this tie which one comes first – and exactly there, duplicates or omissions appear again. The solution is a tie-breaker: you additionally sort by a guaranteed unique column, usually the ID. ORDER BY created_at becomes ORDER BY created_at, id.
This yields a nice side effect. Cursor pagination can be expressed in SQL as so-called keyset pagination, and it scales much better than large offsets:
SELECT id, created_at, name
FROM users
WHERE (created_at, id) > (:cursor_created_at, :cursor_id)
ORDER BY created_at, id
LIMIT :page_size;
The reason: a large OFFSET n forces the database to read and discard n rows before it even starts returning anything – on deep pages, this becomes noticeably slow. The keyset variant with WHERE (sort_key, id) > (...), by contrast, can jump straight to the right place via the index. So cursor pagination is not only more correct for changing lists, it is often faster for deep paging too.
When offset is still fine#
Cursor pagination is not an end in itself. There are cases in which offset is perfectly sufficient:
- The list is essentially stable, such as a historical archive or a closed report into which nothing gets inserted anymore.
- The user should be able to jump straight to page 7 – numbered pages can’t easily be represented with pure cursors, because you don’t know an absolute position.
- The data volumes are small and the pages shallow, so that neither consistency nor performance problems occur.
So this is not about dogma but about a deliberate choice. As soon as a list can change under the user and they potentially page deep into it – feeds, timelines, activity streams – cursor-based pagination with the connections pattern is the right answer. For a stable, manageable reference work, offset can happily stay.
Conclusion#
Pagination seems trivial until you look at it in motion. Offset counts positions, and positions shift – the result is duplicates and gaps that never show up in the quiet demo and are hard to pin down in production. The cursor-based approach replaces the question “from which position” with “after which element” and thereby becomes robust against changes to the list.
The connections pattern pours this idea into a clean structure: edges carry the list-specific cursor, nodes remain plain records, and pageInfo with hasNextPage and endCursor provides exactly the two pieces of information a client needs to page on correctly. Then come the details that make the difference between demo and production – an extra element for hasNextPage, a tie-breaker in the sorting, an upper bound for the page size and the discipline to treat the cursor as truly opaque. If you take these four things to heart, you have pagination that is still correct when the list moves under the user’s fingers.
Further reading#
- Grounding repository: introduction-graphql (
introduction-graphql/paging.md) - GraphQL Pagination – official learning resource
- GraphQL Cursor Connections Specification
Revised and translated from German with the help of AI.