Paginación con cursores

Cómo recorrer una lista completa con first, after y pageInfo, de 100 en 100.

Las listas del API, como ordersConnection, se entregan por páginas. Cada página trae los elementos y la información para pedir la siguiente. No hay números de página: avanzas con cursores.

Una página

Pide los elementos en nodes y, junto con ellos, pageInfo:

query Ordenes($cursor: String) {
  ordersConnection(first: 100, after: $cursor) {
    nodes { id folio total }
    pageInfo { hasNextPage endCursor }
  }
}

• first: cuántos elementos quieres. Sin first llegan 20; si pides más de 100, recibes 100.
• after: el cursor desde el que sigues; en la primera página va null.
• pageInfo.hasNextPage: true si hay más elementos.
• pageInfo.endCursor: el cursor que pasas en after para la siguiente página.

La lista completa

Repite la misma consulta, con los mismos filtros, pasando endCursor en after mientras hasNextPage sea true:

import os, requests

URL = "https://mi-empresa.advantacloud.com/graphql"
HEADERS = {"Authorization": f"Bearer {os.environ['ADVANTA_API_KEY']}"}
QUERY = open("ordenes.graphql").read()

cursor, ordenes = None, []
while True:
    r = requests.post(URL, headers=HEADERS, timeout=30,
                      json={"query": QUERY, "variables": {"cursor": cursor}})
    r.raise_for_status()
    pagina = r.json()["data"]["ordersConnection"]
    ordenes += pagina["nodes"]
    if not pagina["pageInfo"]["hasNextPage"]:
        break
    cursor = pagina["pageInfo"]["endCursor"]

El orden de cada lista es estable: entre una página y la siguiente no se saltan los elementos que ya estaban en la lista. Pero un recorrido no es una foto fija de la lista:

• En las órdenes de venta, que van de la más reciente a la más antigua, las que se capturan mientras recorres no llegan; llegarán en el siguiente recorrido.
• Las listas que van de la modificación más antigua a la más reciente (clientes, artículos, estructuras de precios, facturas y cobros) traen al final lo nuevo y lo que cambia mientras recorres: un registro puede llegar dos veces, la segunda con sus datos nuevos. Guarda por id.

Reglas de los cursores

• Son opacos. No los armes ni los interpretes; sólo pásalos de regreso.
• Valen para la misma consulta. Si cambias un filtro o el orden, empieza de nuevo sin after.
• nodes o edges. nodes es la forma corta. edges trae los mismos elementos con el cursor de cada uno, por si necesitas reanudar desde un elemento intermedio.
• Sólo hacia adelante. Las listas se recorren con first y after, de la primera página a la última. Para volver al inicio, repite la consulta sin after.

Listas dentro de un elemento

Una lista anidada, como las partidas de una orden (lines), es otra conexión con su propio límite de 100. Para una orden con más partidas, pide el resto con su propio cursor:

query Partidas($id: ID!, $cursor: String) {
  order(id: $id) {
    lines(first: 100, after: $cursor) {
      nodes { lineNumber product { idpart } quantity total }
      pageInfo { hasNextPage endCursor }
    }
  }
}

Pide en una sola consulta sólo lo que vas a usar: una página de 100 órdenes con sus partidas es mucha información.