Pagination

Der Envelope

Jede Listen-Antwort hat genau zwei Schlüssel. data enthält die Datensätze, pageInfo alles, was für die nächste Seite gebraucht wird.

{
  "data": [
    { "id": "doc_01JQ8ZK9YV3X2M4N5P6Q7R8S9T", "name": "Mietvertrag", "…": "…" }
  ],
  "pageInfo": {
    "limit": 25,
    "order": "desc",
    "hasMore": true,
    "nextCursor": "eyJpZCI6ImRvY18wMUpROFpLOVlWM1gyTTRONVA2UTdSOFM5VCIsInRzIjoxNzg0MDAwMDAwMDAwfQ"
  }
}

limit

1 bis 100, Standard 25. Ein Wert außerhalb wird abgelehnt, nicht gekappt.

order

"asc" oder "desc", Standard "desc" — neueste zuerst.

cursor

Der Wert aus pageInfo.nextCursor der vorherigen Antwort, unverändert weitergegeben.

pageInfo.hasMore

True, solange eine weitere Seite existiert.

pageInfo.nextCursor

Der Cursor für die nächste Seite; null auf der letzten.

Warum kein Offset

Weil er bei einer wachsenden Tabelle falsche Ergebnisse liefert, ohne dass es auffällt. Wird zwischen dem Abruf von Seite 1 und Seite 2 ein Datensatz angelegt, verschiebt sich alles um eine Position: OFFSET 25 überspringt dann einen Datensatz oder liefert einen doppelt. Bei einem Nachweisverlauf, der pro Minute Einträge bekommt, ist das kein Randfall. Ein Cursor zeigt auf eine Zeile und nicht auf eine Position, also kann er nicht verrutschen.

Der zweite Grund ist Laufzeit: OFFSET 50000 zwingt die Datenbank, 50 000 Zeilen zu lesen und wegzuwerfen. Der Cursor ist ein Index-Zugriff, unabhängig davon, wie weit die Iteration schon gelaufen ist.

Alles durchlaufen

Die Schleife ist vier Zeilen lang und zwei davon sind leicht falsch: wer nicht bei nextCursor === null aufhört, hat eine Endlosschleife, und wer denselben Cursor erneut sendet, hat eine Endlosschleife, die wie Fortschritt aussieht. Das SDK schreibt sie deshalb selbst.

import { Signido } from '@signido/sdk';

const signido = new Signido({ apiKey: process.env.SIGNIDO_API_KEY });

// Kein Cursor im Blickfeld: das SDK holt Seite für Seite nach,
// und zwar erst dann, wenn die Schleife über das Ende der
// aktuellen Seite hinausläuft.
for await (const document of signido.documents.listAll({ status: 'COMPLETED' })) {
  console.log(document.id, document.name);
}

// Wer die Seiten selbst braucht — etwa für eine Tabelle mit Blätter-Navigation:
const first = await signido.documents.list({ limit: 50 });
console.log(first.pageInfo.nextCursor);