Come Funziona la Paginazione

L'API GraphQL di Legalesign utilizza la paginazione basata su cursore seguendo la specifica di connessione Relay. Ogni elenco di elementi — documenti, modelli, contatti, fatture — utilizza questo stesso schema.

Il Modello di Connessione

La terminologia proviene dalla teoria dei grafi — i nodi sono punti, i bordo sono linee che li collegano. Nell'API, un bordo descrive la relazione tra due tipi e può riportare metadati aggiuntivi (come le autorizzazioni che un User ha in un Group).

Quando fai una query su una lista, non ottieni un array semplice. Ottieni un oggetto connection con tre parti:

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

Perché Non Solo un Array?

La paginazione basata su cursore è stabile. A differenza della paginazione con offset (page=2), i cursori non si rompono quando gli elementi vengono aggiunti o rimossi tra una richiesta e l'altra. Questo è importante quando i documenti vengono inviati e firmati in tempo reale.

Recuperare la Prima Pagina

Usa first per limitare i risultati. Quando effettui la paginazione su un insieme completo di risultati in ordine di creazione, passa "0" o "START" come argomento after nella prima chiamata per indicare che stai iniziando una sequenza paginata:

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

Recuperare la Pagina Successiva

Se hasNextPage è true, passa endCursor come argomento after:

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

Ripeti finché hasNextPage è false.

Argomenti di Paginazione

Tutte le connessioni accettano questi argomenti:

Argomento	Tipo	Descrizione
first	Int	Numero di elementi da restituire dall'inizio
after	ID	Cursore da cui iniziare dopo (per paginazione in avanti)
last	Int	Numero di elementi da restituire dalla fine
before	ID	Cursore da cui iniziare prima (per paginazione indietro)

La maggior parte delle connessioni accetta anche argomenti di filtro specifici per il tipo di dati. Ad esempio, documentConnection accetta from, to, status, search, sendType e sender.

La Scorciatoia degli Edges

Le connessioni forniscono sia edges (con cursore per ogni elemento) sia un elenco scorciatoia. Per la maggior parte dei casi d'uso la scorciatoia è più semplice:

# 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
  }
}

Usa la scorciatoia a meno che tu non abbia bisogno di cursori individuali (ad esempio per eliminare un elemento specifico e riprendere da quel punto).

nota

totalCount restituisce il conteggio per la pagina corrente, non il totale su tutte le pagine. Il costo computazionale per calcolare un totale globale su potenzialmente milioni di record rende impraticabile un totale vero e proprio.

Esempio Pratico

Ecco come l'app Console di Legalesign esegue la paginazione dei documenti usando lo scroll infinito con 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
    }
  }
}

L'app recupera la prima pagina, poi durante lo scroll usa endCursor come after per caricare il lotto successivo.

Quali Tipi Usano le Connessioni?

Ogni relazione di lista nell'API utilizza questo schema:

• 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