Pagination in GraphQL: Cursor vs. Offset sauber umsetzen

1. Warum Pagination in GraphQL kein trivialer Parameter ist

Pagination gehört zu den Themen, die in GraphQL-APIs schnell unterschätzt werden. Ein einfaches limit und offset als Argument reicht für den ersten Prototyp – aber sobald Datenmengen wachsen, mehrere Benutzer gleichzeitig schreiben oder Frontend-Teams stabile Seitennavigation benötigen, zeigen sich die Grenzen dieses Ansatzes deutlich. Die GraphQL-Community hat darauf reagiert und mit der Relay-Spezifikation ein ausgereiftes Muster für Cursor-basierte Pagination definiert, das heute von den meisten großen GraphQL-Implementierungen unterstützt wird.

Der Unterschied liegt nicht nur in der technischen Umsetzung, sondern im konzeptionellen Ansatz: Offset-Pagination denkt in absoluten Positionen, Cursor-Pagination in stabilen Zeigern auf Datensätze. Das klingt abstrakt, macht sich aber sehr konkret bemerkbar, wenn zwischen zwei Anfragen neue Datensätze eingefügt werden und sich damit alle Positionen verschieben. Wer das falsche Modell für seinen Anwendungsfall wählt, baut sich ein Stabilitätsproblem in die API, das schwer rückgängig zu machen ist.

2. Offset-Pagination: Einfach, verständlich, limitiert

Offset-Pagination arbeitet mit zwei Parametern: limit (wie viele Einträge zurückgegeben werden) und offset (wie viele Einträge übersprungen werden). Das Modell ist intuitiv und direkt auf SQL-Ebene abbildbar: SELECT * FROM products LIMIT 20 OFFSET 40. Für einfache Listen mit stabilen Daten — zum Beispiel Einstellungsseiten in einem Admin-Panel — ist Offset-Pagination vollkommen ausreichend. Der Implementierungsaufwand ist gering, die mentale Komplexität überschaubar.

Die Probleme beginnen, wenn die Datenbasis nicht stabil ist. Wird zwischen zwei Requests ein Produkt eingefügt, verschiebt sich die gesamte Liste um eine Position, und der Client bekommt beim nächsten Request einen Datensatz doppelt oder überspringt einen. Bei großen Offsets entstehen außerdem Performance-Probleme auf Datenbankebene: Die Datenbank muss alle Datensätze bis zum Offset materialisieren, auch wenn sie nie zurückgegeben werden. Ab etwa 10.000 Datensätzen Offset macht sich das messbar. Offset-Pagination ist daher gut für stabile, überschaubare Datensätze, aber ungeeignet für Feeds, Produktlisten und andere häufig veränderte Collections.

# Offset-based pagination — simple but limited for live data
query ProductsWithOffset {
  products(
    search: "jacket"
    pageSize: 20
    currentPage: 3
  ) {
    total_count
    page_info {
      current_page
      page_size
      total_pages
    }
    items {
      sku
      name
      price_range {
        minimum_price {
          final_price { value currency }
        }
      }
    }
  }
}

3. Cursor-Pagination und die Relay-Spezifikation

Die Relay-Spezifikation beschreibt eine standardisierte Art, Cursor-Pagination in GraphQL umzusetzen. Statt limit und offset verwendet man die Argumente first, after, last und before. Der Cursor ist ein opaker String — typischerweise eine Base64-kodierte Darstellung eines eindeutigen Wertes wie einer ID oder eines Timestamps —, den der Server an jeden Eintrag anhängt. Der Client sendet diesen Cursor zurück, um die nächste Seite anzufragen. Das Ergebnis enthält immer ein pageInfo-Objekt mit hasNextPage, hasPreviousPage, startCursor und endCursor.

Der zentrale Vorteil: Der Server muss keine absolute Position mehr kennen, sondern nur den letzten gesehenen Datensatz. Das macht die Abfrage stabil gegenüber Einfügeoperationen und erlaubt auf Datenbankebene eine effiziente Implementierung mit WHERE id > cursor_id ORDER BY id LIMIT n. Cursor sind außerdem flexibler: Sie können zusammengesetzte Sortierschlüssel kodieren und damit auch komplexe Sortierungen stabil paginieren — etwas, das mit reinen Offsets nicht möglich ist.

# Relay-style cursor pagination — stable and efficient
query ProductsWithCursor($after: String) {
  productConnection(first: 20, after: $after) {
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    edges {
      cursor
      node {
        id
        sku
        name
        price_range {
          minimum_price {
            final_price { value currency }
          }
        }
      }
    }
    totalCount
  }
}

4. Schema-Design: Connection-Typen korrekt aufbauen

Das Relay-Muster führt eine eigene Typstruktur ein, die auf den ersten Blick umständlich wirkt, aber Wiederverwendbarkeit und Konsistenz über alle paginierten Listen garantiert. Der zentrale Typ ist die Connection: sie enthält edges (eine Liste von Edge-Objekten) und pageInfo. Jede Edge enthält cursor und node (den eigentlichen Datensatz). Diese Verschachtelung erlaubt es, den Cursor an jedem einzelnen Element zu transportieren und nicht nur an der Gesamtliste. Für unterschiedliche Entitäten definiert man unterschiedliche Connection- und Edge-Typen, die alle dasselbe PageInfo-Interface teilen.

In der Schema-Definition ist wichtig, dass das PageInfo`-Objekt als eigener Typ definiert wird und nicht inline eingebettet ist. Das macht ihn wiederverwendbar über alle Connections hinweg. Die Argumente first: Int, after: String, last: Int, before: String sind Teil des Relay-Standards und sollten konsistent benannt werden. Eigene Argumente wie filters oder sort können parallel zu den Pagination-Argumenten stehen, ohne die Struktur zu brechen.

# Schema definition following Relay Connection specification
type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

type ProductEdge {
  cursor: String!
  node: ProductNode!
}

type ProductConnection {
  edges: [ProductEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type ProductNode {
  id: ID!
  sku: String!
  name: String!
  price: Float
}

type Query {
  # Relay-compatible connection field alongside optional filters
  productConnection(
    first: Int
    after: String
    last: Int
    before: String
    search: String
    sort: ProductSortInput
  ): ProductConnection!
}