Relay-style Connections and Pagination

The Offset Bug You Ship Without Noticing

Offset pagination is skip/limit, and it corrupts a live feed the moment someone posts while a reader is scrolling:

Table:   A  B  C  D  E  F  G  H
Page 1:  skip 0 limit 3        →  A B C     reader finishes A, B
New post X inserted at the top
Page 2:  skip 3 limit 3        →  C D E     C repeats; the row the reader
                                             expected (D) arrives one slot early

Two failure modes fall out of counting positions instead of referencing rows: duplicates when rows are inserted ahead of the offset, and skips when rows are deleted ahead of it. Neither appears in a test suite that runs against a frozen table, which is exactly why they survive to production.

Offset also gets slower as it grows — LIMIT 10 OFFSET 100000 makes the database produce 100,010 rows and discard 100,000 of them.

Cursor pagination replaces counting with a pointer. The server hands back an opaque token for the last row seen, and the next request resumes from that position:

-- offset:  counts rows it must throw away
SELECT * FROM posts ORDER BY created_at DESC LIMIT 10 OFFSET 100000;
-- keyset:   seeks straight to the resume point
SELECT * FROM posts WHERE (created_at, id) < ('2026-01-01', 821)
  ORDER BY created_at DESC, id DESC LIMIT 10;

Relay is the GraphQL convention that wraps this idea in a shape every client can code against.

The cost asymmetry matters as much as the correctness one: an offset query does more work the deeper a reader scrolls, while a keyset query seeks to the boundary row and reads only the page it returns. Page 5,000 of an offset feed is a full scan in disguise — the database produces 50,000 rows to hand back ten. That is why the first decision for a GraphQL list field is not "how many per page" but "what identifies a row's position in the order".

The Connection Shape: Edges, Nodes, PageInfo

Relay wraps a list in three layers, each with one job:

type PostEdge {
  cursor: String!      # opaque pointer to this row within the sort order
  node: Post!          # the record itself
}

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

type PostConnection {
  edges: [PostEdge!]!
  nodes: [Post!]!      # convenience: edges.map(e => e.node)
  pageInfo: PageInfo!
}

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

The document a client writes:

query FirstPage {
  posts(first: 2, after: "Y3Vyc29yOjE=") {
    pageInfo { hasNextPage endCursor }
    edges {
      cursor
      node { id title }
    }
  }
}

{
  "data": { "posts": {
    "pageInfo": { "hasNextPage": true, "endCursor": "Y3Vyc29yOjM=" },
    "edges": [
      { "cursor": "Y3Vyc29yOjI=", "node": { "id": "2", "title": "…" } },
      { "cursor": "Y3Vyc29yOjM=", "node": { "id": "3", "title": "…" } }
    ]
  }}
}

Connections nest like any other field, which is what makes them the right answer for lists inside lists — posts { comments(first: 10) { … } } — and each nested connection is one more resolver with its own parent to read an id from.

Two details worth internalising: startCursor exists so a list can render a "previous" control without the client keeping its own history of every page it has seen, and edges is what makes per-row cursors possible at all — nodes alone cannot tell you where the page ended, which is why a connection exposes both.

Opaque Cursors, Backwards Pages, and the totalCount Bill

A cursor is a database resume token, not an index. Encode the sort key rather than a position:

const encodeCursor = (row) =>
  Buffer.from(`${row.created_at}|${row.id}`).toString('base64');
// decode → WHERE (created_at, id) < ('2026-01-01 00:00:00', 821)

Three rules make cursors stable:

• Sort deterministically. A tie-breaker column (id) is mandatory. Rows sharing created_at otherwise shuffle between pages, and every page boundary becomes a coin flip.
• Filter on the key, not the position. Keyset comparison is unaffected by inserts above the cursor, so page 2 after a new post still starts where page 1 ended.
• Fetch first + 1 rows. Ask for one extra row so hasNextPage is a fact rather than a guess:

const rows = await db.post.findMany({ take: first + 1, cursor, skip: 1, orderBy });
const hasNextPage = rows.length > first;
const edges = rows.slice(0, first).map((node) => ({ cursor: encodeCursor(node), node }));

(skip: 1 starts after the row the cursor points at; without it the cursor row reappears on every page.)

totalCount is optional and expensive. It forces a COUNT(*) over the whole filtered set on every page — on a large table that can cost more than the page itself, and it cannot be cached independently of writes. Return it where the UI genuinely displays "1,204 results" (search headers, admin tables); omit it from infinite-scroll feeds where nothing renders it.

The client payoff: endCursor from page 1 is the entire input to page 2, so the UI stores one opaque string and no offset that can drift. Nested connections bring back the per-level resolver cost — if a feed of 20 posts each opens a 10-comment connection, that is 21 queries unless the comment lookups are batched. See the N+1 pattern.

Interview framing: state why offsets drift under writes, describe the keyset comparison in SQL, then explain first + 1 as the honest way to compute hasNextPage.