Cursor-based Pagination with GraphQL Relay Connections

Overview

Offset pagination breaks on live data: insert a row at the top of a feed and every subsequent page shifts, so clients see duplicates or miss items entirely. The Relay Connection spec solves this by giving each item a stable cursor — an opaque token the client hands back to ask for “what comes after this.” It’s the standard pagination shape for GraphQL APIs, expected by Relay and supported by every major client.

This recipe covers the full spec: Connection/Edge/PageInfo types, base64 cursor encoding, a resolver that paginates forward and backward, and the variant that matters in production — composite cursors for non-unique sort columns.

When to Use This

• Collections that grow over time and need stable pagination
• Clients that support infinite scroll or “load more” patterns
• APIs consumed by Relay, Apollo, or any client expecting cursor-based navigation

For a plain offset-paginated REST endpoint, see cursor pagination in PostgreSQL — same technique, different transport. Don’t use connections for tiny static lists (a dropdown of countries): the ceremony isn’t worth it there.

Prerequisites

• A GraphQL server (Apollo Server, GraphQL Yoga, or similar)
• A data source with a sortable, unique column (ID, timestamp, or cursor)

Solution

1. Define the Connection Types

// schema.ts
import gql from 'graphql-tag';

export const typeDefs = gql`
  type PageInfo {
    hasNextPage: Boolean!
    hasPreviousPage: Boolean!
    startCursor: String
    endCursor: String
  }

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

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

  type Post {
    id: ID!
    title: String!
    content: String!
    createdAt: String!
  }

  input PaginationInput {
    first: Int
    after: String
    last: Int
    before: String
  }

  type Query {
    posts(pagination: PaginationInput): PostConnection!
  }
`;

2. Implement Cursor Encoding

// cursor.ts
export function encodeCursor(value: string | number): string {
  return Buffer.from(String(value)).toString('base64');
}

export function decodeCursor(cursor: string): string {
  return Buffer.from(cursor, 'base64').toString('utf8');
}

3. Build the Resolver

// resolvers.ts
import { encodeCursor, decodeCursor } from './cursor';

interface Post {
  id: string;
  title: string;
  content: string;
  createdAt: string;
}

export const postResolvers = {
  Query: {
    posts: async (
      _: unknown,
      { pagination }: { pagination: { first?: number; after?: string; last?: number; before?: string } },
      context: { db: { posts: { findMany: (opts: any) => Promise<Post[]>; count: () => Promise<number> } } }
    ) => {
      const { first, after, last, before } = pagination;
      const limit = first ?? last ?? 10;
      const maxLimit = 50;

      const take = Math.min(limit, maxLimit);

      let cursor: string | undefined;
      let skip = 0;
      let order: 'asc' | 'desc' = 'desc';

      if (after) {
        cursor = decodeCursor(after);
        skip = 1;
      } else if (before) {
        cursor = decodeCursor(before);
        skip = 1;
        order = 'asc';
      }

      const posts = await context.db.posts.findMany({
        take: take + 1,
        skip,
        cursor: cursor ? { id: cursor } : undefined,
        orderBy: { id: order },
      });

      const hasMore = posts.length > take;
      const trimmed = hasMore ? posts.slice(0, take) : posts;
      const reversed = last ? trimmed.reverse() : trimmed;

      const edges = reversed.map((post) => ({
        cursor: encodeCursor(post.id),
        node: post,
      }));

      const totalCount = await context.db.posts.count();

      // hasMore means "more rows exist in the direction you queried":
      // forward (first/after) → hasNextPage; backward (last/before) → hasPreviousPage
      return {
        edges,
        totalCount,
        pageInfo: {
          hasNextPage: before ? true : Boolean(first && hasMore),
          hasPreviousPage: after ? true : Boolean(last && hasMore),
          startCursor: edges[0]?.cursor ?? null,
          endCursor: edges[edges.length - 1]?.cursor ?? null,
        },
      };
    },
  },
};

4. Query the Connection

query GetPosts($first: Int, $after: String) {
  posts(pagination: { first: $first, after: $after }) {
    edges {
      cursor
      node {
        id
        title
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Pass the endCursor from the previous response as after in the next request to load the next page.

How It Works

1. Cursors are opaque tokens encoding the last-seen position (typically the row ID). Clients treat them as black boxes.
2. Edges pair each node with its cursor, so clients can navigate from any point without tracking offsets.
3. first + after fetches forward; last + before fetches backward. The resolver reverses results when paginating backward.
4. take + 1 is a trick to check for a next page without a separate count query — if you get more rows than requested, hasNextPage is true.

Variants

Offset-Based Fallback

For data sources without cursor support (Elasticsearch aggregations, legacy APIs), fall back to offset pagination but still return the connection shape for client compatibility:

const offset = after ? parseInt(decodeCursor(after), 10) + 1 : 0;
const posts = await db.posts.findMany({ skip: offset, take });

Keyset Pagination with Composite Cursors

For ordered columns that aren’t unique (like createdAt), use a composite cursor (createdAt, id) to avoid skipping rows with identical timestamps:

export function encodeCompositeCursor(createdAt: string, id: string): string {
  return Buffer.from(`${createdAt}|${id}`).toString('base64');
}

Advanced: Pagination with Sort Order

When paginating by a non-id column (e.g., createdAt), encode the sort value in the cursor:

export function encodeSortCursor(value: string, id: string): string {
  return Buffer.from(`${value}|${id}`).toString('base64');
}

export function decodeSortCursor(cursor: string): { value: string; id: string } {
  const [value, id] = Buffer.from(cursor, 'base64').toString().split('|');
  return { value, id };
}

The resolver uses a compound WHERE clause to skip rows seen in the previous page:

const { value, id } = after ? decodeSortCursor(after) : { value: null, id: null };

const posts = await db.posts.findMany({
  where: value
    ? {
        OR: [
          { createdAt: { lt: new Date(value) } },
          { createdAt: new Date(value), id: { lt: id } },
        ],
      }
    : undefined,
  orderBy: [{ createdAt: 'desc' }, { id: 'desc' }],
  take: take + 1,
});

Two posts created in the same second won’t disappear between pages.

Best Practices

• Cap first and last at a reasonable maximum (50–100) to prevent expensive queries.
• Always sort by a stable column — sorting by non-unique fields without a tiebreaker causes skipped rows.
• Keep cursors opaque — if clients can’t parse them, they can’t couple to your internals.
• Include totalCount only when the client needs it; it can be expensive on large tables.
• Index the sort column — without it, every page request re-scans the table.

Common Mistakes

• Using offset as cursor — this defeats the purpose of cursor pagination and reintroduces skip/duplicate issues.
• Forgetting skip: 1 after a cursor — without it, the first item of each page repeats the last item of the previous page.
• Not handling empty results — return an empty edges array with hasNextPage: false instead of throwing.
• Wrong pageInfo flags on last/before — when paginating backward, hasPreviousPage comes from hasMore and hasNextPage is true because you arrived from a later page.

Troubleshooting

• First item of each page duplicates the last of the previous page: you forgot skip: 1 (or the equivalent > filter) after the cursor — the query is re-fetching the cursor row itself.
• Every page shows hasNextPage: false: you’re fetching take rows instead of take + 1, so there’s never a spillover row to detect more pages with.
• Rows skipped when sorting by createdAt: two rows share the same timestamp and the cursor only encodes that column. Switch to a composite (createdAt, id) cursor.
• after cursor throws or returns page 1: the client sent a malformed or stale cursor (base64 that decodes to garbage, or an ID that no longer exists). Decode defensively and treat an undecodable cursor as “no cursor” or a 400 — your pick, just don’t crash the resolver.
• Client passed both first and last: the spec says pick one. Reject the combination or give first precedence — silent surprises here produce confusing pages.

See Also

• GraphQL Connection Pagination Pattern — the architectural pattern behind this recipe.
• Cursor Pagination in PostgreSQL — the same keyset technique applied to a REST endpoint.
• Relay Connection spec — the normative reference for the shape implemented here.

Companion code: runnable Relay pagination server: the schema, cursor helpers, and resolver from this recipe wired to an Apollo Server with seeded data.