Passa al contenuto principale

Paginazione GraphQL

Le query GraphQL di Riseact che restituiscono liste utilizzano la paginazione cursor-based. Questo approccio è stabile rispetto all'inserimento o rimozione di elementi durante la navigazione, al contrario della paginazione offset.

Struttura della risposta​

Ogni query paginata restituisce una Connection:

type Connection {
  pageInfo: PageInfo!
  edges: [Edge!]!
}

type Edge {
  cursor: String!
  node: <TipoEntità>!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
  total: Int!
}

Il campo total contiene sempre il numero complessivo di risultati (ignorando la paginazione), utile per calcolare il numero di pagine.

Input di paginazione​

input PaginationInput {
  first: Int   # quanti elementi prendere dalla testa
  last:  Int   # quanti elementi prendere dalla coda
  after: String  # cursore: prendi gli elementi dopo questo
  before: String # cursore: prendi gli elementi prima di questo
}

Dimensione di default: 25 elementi, se first e last sono entrambi omessi.

caution

Non è possibile usare first e last nella stessa richiesta.

Per scorrere i risultati dalla prima all'ultima pagina, usa first + after.

Prima pagina:

query {
  donations(pagination: { first: 20 }) {
    pageInfo {
      hasNextPage
      endCursor
      total
    }
    edges {
      cursor
      node {
        id
        state
        amount
      }
    }
  }
}

Pagina successiva (usando endCursor dalla risposta precedente):

query {
  donations(pagination: { first: 20, after: "Y3Vyc29yOnYxOjIwMjMtMDgtMTd8MTIz" }) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        id
        state
        amount
      }
    }
  }
}

Per scorrere dalla fine verso l'inizio, usa last + before.

query {
  donations(pagination: { last: 20, before: "Y3Vyc29yOnYxOjIwMjMtMDgtMTd8MTIz" }) {
    pageInfo {
      hasPreviousPage
      startCursor
    }
    edges {
      node {
        id
        state
        amount
      }
    }
  }
}

Come funzionano i cursori​

I cursori sono stringhe opache codificate in Base64. Codificano i valori dei campi di ordinamento dell'elemento (es. payment_date|id). Non devono essere interpretati o costruiti manualmente: usa sempre i cursori restituiti da startCursor / endCursor / edges[*].cursor.

Recuperare tutti gli elementi​

Per scaricare tutti i risultati senza pagine, itera usando hasNextPage e endCursor:

async function fetchAll(client) {
  let after = null;
  const results = [];

  do {
    const { data } = await client.query({
      query: DONATIONS_QUERY,
      variables: { pagination: { first: 100, after } },
    });

    results.push(...data.donations.edges.map(e => e.node));
    after = data.donations.pageInfo.hasNextPage
      ? data.donations.pageInfo.endCursor
      : null;
  } while (after);

  return results;
}

Query che supportano la paginazione​

Le seguenti query accettano pagination: PaginationInput:

  • donations
  • payments
  • supporters
  • campaigns
  • checkouts
  • activities