Wie die Paginierung funktioniert

Die Legalesign GraphQL API verwendet Cursor-basierte Paginierung gemäß der Relay Connection Spezifikation. Jede Liste von Elementen – Dokumente, Vorlagen, Kontakte, Rechnungen – verwendet dieses gleiche Muster.

Das Connection-Muster

Die Terminologie stammt aus der Graphentheorie – Knoten sind Punkte, Kanten sind Linien, die sie verbinden. In der API beschreibt eine Kante die Beziehung zwischen zwei Typen und kann zusätzliche Metadaten tragen (wie welche Berechtigungen ein User in einer Group hat).

Wenn Sie eine Liste abfragen, erhalten Sie kein einfaches Array. Sie erhalten ein Connection-Objekt mit drei Teilen:

documentConnection(first: 20) {
  documents { ... }     # the items (shortcut)
  totalCount            # total matching items
  pageInfo {            # pagination cursors
    startCursor
    endCursor
    hasNextPage
    hasPreviousPage
  }
}

Warum nicht einfach ein Array?

Cursor-basierte Paginierung ist stabil. Im Gegensatz zur Offset-Paginierung (page=2) brechen Cursor nicht, wenn zwischen den Anfragen Elemente hinzugefügt oder entfernt werden. Das ist wichtig, wenn Dokumente in Echtzeit versendet und unterschrieben werden.

Die erste Seite abfragen

Verwenden Sie first, um die Ergebnismenge zu begrenzen. Wenn Sie durch die vollständige Ergebnismenge in der Reihenfolge der Erstellung blättern, übergeben Sie bei Ihrem ersten Aufruf "0" oder "START" als after-Argument, um zu signalisieren, dass Sie eine paginierte Sequenz starten:

query {
  group(id: "grpYourGroupId") {
    documentConnection(first: 100, after: "0") {
      documents {
        id
        name
        status
        created
      }
      pageInfo {
        endCursor
        hasNextPage
      }
      totalCount
    }
  }
}

Die nächste Seite abfragen

Wenn hasNextPage true ist, übergeben Sie endCursor als after-Argument:

query {
  group(id: "grpYourGroupId") {
    documentConnection(first: 100, after: "eyJpZCI6ImRvYzEyMyJ9") {
      documents {
        id
        name
        status
        created
      }
      pageInfo {
        endCursor
        hasNextPage
      }
      totalCount
    }
  }
}

Wiederholen Sie dies, bis hasNextPage false ist.

Paginierungsargumente

Alle Connections akzeptieren diese Argumente:

Argument	Typ	Beschreibung
first	Int	Anzahl der zurückzugebenden Elemente vom Anfang
after	ID	Cursor, nach dem gestartet wird (für Vorwärtspaginierung)
last	Int	Anzahl der zurückzugebenden Elemente vom Ende
before	ID	Cursor, vor dem gestartet wird (für Rückwärtspaginierung)

Die meisten Connections akzeptieren außerdem Filterargumente, die spezifisch für den Datentyp sind. Beispielsweise akzeptiert documentConnection from, to, status, search, sendType und sender.

Die Edges-Abkürzung

Connections bieten sowohl edges (mit Cursor pro Element) als auch eine Abkürzungsliste. Für die meisten Anwendungsfälle ist die Abkürzung einfacher:

# Shortcut — simpler, no per-item cursor
documentConnection(first: 20) {
  documents {
    id
    name
  }
  pageInfo {
    endCursor
    hasNextPage
  }
}

# Full edges — needed if you want per-item cursors
documentConnection(first: 20) {
  edges {
    node {
      id
      name
    }
    cursor
  }
  pageInfo {
    endCursor
    hasNextPage
  }
}

Verwenden Sie die Abkürzung, es sei denn, Sie benötigen einzelne Cursor (z. B. um ein bestimmtes Element zu löschen und von diesem Punkt aus fortzufahren).

Hinweis

totalCount gibt die Anzahl für die aktuelle Seite zurück, nicht die Gesamtsumme über alle Seiten. Die Kosten für die Berechnung einer globalen Gesamtzahl über potenziell Millionen von Datensätzen machen eine echte Gesamtsumme unpraktisch.

Praxisbeispiel

So paginiert die Legalesign Console App Dokumente mithilfe von unendlichem Scrollen mit TanStack Query:

query queryInfiniteDocuments {
  group(id: "grpYourGroupId") {
    documentConnection(
      first: 100
      after: "eyJpZCI6ImRvYzEyMyJ9"
      sendType: SINGLE
      from: "2025-01-01T00:00:00Z"
      to: "2025-06-01T00:00:00Z"
    ) {
      documents {
        id
        name
        status
        senderName
        created
        recipients {
          id
          email
          status
          signedDateTime
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
      totalCount
    }
  }
}

Die App lädt die erste Seite und verwendet dann beim Scrollen endCursor als after, um die nächste Charge zu laden.

Welche Typen verwenden Connections?

Jede Listenbeziehung in der API verwendet dieses Muster:

• Group.documentConnection, templateConnection, batchConnection, contactConnection, experienceConnection, scheduleConnection, attachmentConnection, memberConnection, invitationConnection, standardMessageConnection, contactGroupConnection, draftConnection, activityConnection
• Organisation.groupConnection, dataStopConnection, dataDeletionConnection, retentionConnection, userConnection, invoiceConnection, dataSubjectConnection
• Batch.documentConnection
• Billing.invoiceConnection
• Invoice.lineItemConnection
• Template.elementConnection, userSignatureConnection
• Document.elementConnection
• Recipient.elementConnection
• User.memberConnection, organisationConnection, supportTicketConnection