Cursor-Pagination statt Offsets: Seiten, die bei Änderungen stabil bleiben

Worum es geht

Offset-Pagination heisst: ORDER BY erstellt DESC LIMIT 20 OFFSET 400. Die PostgreSQL-Dokumentation hält dazu fest, dass die durch OFFSET übersprungenen Zeilen trotzdem im Server berechnet werden müssen, weshalb ein grosses OFFSET ineffizient sein kann – und dass LIMIT ohne eine ORDER-BY-Klausel, die eine eindeutige Reihenfolge erzwingt, eine unvorhersehbare Teilmenge liefert. Cursor-Pagination (auch Keyset- oder Seek-Methode) merkt sich stattdessen den letzten Eintrag der vorherigen Seite und fragt nur die darauffolgenden ab, wie Markus Winand in der zitierten deutschen Fassung von «SQL Performance Explained» beschreibt: WHERE (erstellt, id) < (?, ?) ORDER BY erstellt DESC, id DESC FETCH FIRST 20 ROWS ONLY. Der Vergleich mit Row Values (Zeilenwert-Syntax) macht das Paar zu einer Einheit, auf die ein zusammengesetzter Index direkt springen kann.

Warum es wichtig ist

Zwischen zwei Offset-Anfragen verschiebt jede eingefügte oder gelöschte Zeile alle späteren Seiten: Ein Client sieht Einträge doppelt oder verpasst sie – für einen Menschen ärgerlich, für einen Agenten, der einen Bestand vollständig abarbeiten soll, ein Korrektheitsfehler. Zudem wachsen die Kosten je Seite mit der Tiefe, sodass die letzten Seiten einer grossen Liste die teuersten Anfragen der API sind. Ein Cursor, der an einem stabilen Sortierschlüssel hängt, liefert jeden Eintrag genau einmal und kostet auf Seite 5000 dasselbe wie auf Seite 1.

So wird es angewendet

• Nach einem eindeutigen, indexierten Schlüssel sortieren oder nach einer Kombination, die mit einem eindeutigen Feld endet (erstellt, id); der Index muss dieselben Spalten in derselben Reihenfolge und Richtung tragen.
• Dem Client einen opaken next_cursor zurückgeben, der die Schlüsselwerte der letzten Zeile kodiert (Base64 eines JSON-Tupels genügt); signieren oder verschlüsseln, wenn Clients keine eigenen Cursor bauen dürfen.
• Filter und Sortierung im Cursor mitführen oder bei abweichenden Parametern ablehnen; ein Cursor gilt für genau eine Abfrage.
• Seitengrösse mit Vorgabe und Obergrenze begrenzen; das Ende der Liste durch fehlenden next_cursor anzeigen, nicht durch eine leere Seite.
• Für Rückwärtsblättern einen prev_cursor mit umgekehrter Vergleichsrichtung anbieten oder darauf verzichten und das dokumentieren.

Stolpersteine

Sortierung nach einer nicht eindeutigen Spalte ohne Tiebreaker verliert oder wiederholt Zeilen an den Seitengrenzen. Cursor können nicht «auf Seite 37» springen; braucht die Oberfläche Seitenzahlen, bleibt Offset mit begrenzter Maximaltiefe die ehrlichere Wahl. Zeitstempel mit Sekundenauflösung erzeugen Gleichstände – daher der Schlüssel als zweites Feld. Ein Cursor, der interne IDs im Klartext trägt, verrät Wachstumsraten und lädt zum Basteln ein.