Recursos · 86

Paginación de API: exportaciones sin pérdidas ni duplicados

Definir orden, tokens, permisos y recuperación cuando la colección cambia durante la lectura.

Actualizado · 8 min

Mapa mundial de redes en una sala de inteligencia vacía Ilustración editorial generada con IA

Lo que esta guía ayuda a lograr

  • Definir orden y alcance
  • Tratar el token como continuación
  • Detectar el final según el contrato
  • Recuperar tras un fallo
  • Conciliar el resultado

Comprobación rápida

  • ¿Una página vacía indica el final?
  • ¿Puede el cursor dar autorización?
  • ¿Deduplicar evita pérdidas?

Método paso a paso

  1. 1

    Definir orden y alcance

    Documente filtros, orden y clave de desempate. Una fecha sola puede no bastar si varios objetos la comparten. Decida si la colección sigue viva o si la exportación usa una instantánea. No prometa una vista congelada cuando el proveedor no ofrece esa garantía.

    Entregable: contrato de orden y coherencia.

  2. 2

    Tratar el token como continuación

    AIP-158 prevé tokens opacos y separa paginación y autorización: el token no concede acceso. Compruebe identidad y permisos en cada petición. Mantenga los parámetros de lectura conforme al contrato y trate caducidad o invalidación explícitamente.

    Entregable: casos de token válido, caducado y no autorizado.

  3. 3

    Detectar el final según el contrato

    No suponga que una página corta es la última. Una API puede devolver menos elementos y proporcionar continuación. En AIP-158, un next_page_token vacío indica el final; adapte el cliente al contrato del proveedor real. Detecte también tokens repetidos sin avance.

    Entregable: pruebas de finalización y bucles.

  4. 4

    Recuperar tras un fallo

    Guarde la continuación después de almacenar duraderamente el lote. Elimine duplicados mediante identificadores estables y separe recuperación de totales mostrados. Si caduca una instantánea, reinicie o concilie según una regla explícita; no concatene silenciosamente estados distintos.

    Entregable: punto de recuperación y escenario de fallo.

  5. 5

    Conciliar el resultado

    Compare identificadores únicos, exclusiones, estados y total de referencia para el mismo corte. Pruebe creación, modificación y eliminación durante la lectura. Un número correcto no demuestra que sean los objetos correctos. Proteja archivos y trazas según sus datos.

    Entregable: manifiesto de exportación y diferencias documentadas.

Una lectura paginada que puede recuperarse

En un contrato de tipo AIP-158, la continuación determina el siguiente paso. Una página corta no demuestra el final.

  1. Definir la lectura

    Conservar filtro, orden, parámetros e identidad autorizada.

  2. Guardar el lote

    Almacenar duraderamente objetos e identificadores.

  3. Seguir la continuación

    Un token presente lleva a otra petición con parámetros vinculados.

  4. Conciliar al finalizar

    Con token final vacío, comprobar exclusiones, referencia y cobertura.

Ejemplo ficticio: la conexión falla después de guardar un lote. La recuperación usa el punto guardado y comprueba identificadores ya tratados.

Caso de aceptación reproducible

Ejemplo ficticio: estos datos no describen clientes ni resultados observados.

Ver datos del caso
{
    "page_1_ids": [
        "A",
        "B"
    ],
    "page_2_ids": [
        "B",
        "C"
    ],
    "next_cursor": "c2",
    "empty_page_has_next_cursor": true
}

Decisión esperada

B se repite. Compruebe identidades y siga el cursor incluso después de una página vacía.

Procedimiento de verificación

  1. Fije filtros, orden estable e identidad.
  2. Pruebe duplicado y página vacía con cursor.
  3. Conserve identificadores y condición real de fin. Compare objetos recibidos e identificadores únicos; señale cursores repetidos sin tratar una página vacía con continuación como fin de la recopilación.

Google AIP-158 — Pagination

Hoja de cálculo reutilizable

Complete con sus observaciones autorizadas. Estos campos son una plantilla de trabajo, no resultados observados.

CampoInformación a registrar
ColecciónFiltros, orden, desempate y garantías
ContinuaciónToken, parámetros vinculados, caducidad y final
RecuperaciónLote duradero, identificadores únicos y punto guardado
ResultadoManifiesto, exclusiones, corte y diferencias

Ejemplo trabajado ficticio

Situación ilustrativa

Ejemplo ficticio: se añaden productos durante una exportación por offset y una fila cambia de página.

Decisión y pruebas esperadas

La prueba encuentra un duplicado y un producto ausente; el equipo usa una instantánea disponible o documenta lectura viva con conciliación.

Distinguir los mecanismos

MecanismoPropósitoVerificación o limitación
OffsetAcceder a una posición numéricaLas inserciones pueden desplazar posiciones
CursorContinuar desde un marcadorNo garantiza una instantánea por sí solo
InstantáneaFijar un estado de referenciaComprobar duración y coste

Indicadores de gestión

IndicadorQué midePrimera acción
Identificadores únicosObjetos distintos conservadosComparar con una referencia equivalente
AvanceTokens y lotes que progresanDetener bucles e investigar
Cobertura verificadaObjetos conciliados con la referenciaNo confundir volumen con exhaustividad

Errores comunes

  • Las inserciones pueden desplazar posiciones
  • No garantiza una instantánea por sí solo
  • Comprobar duración y coste

Preguntas frecuentes

¿Una página vacía indica el final?

Consulte contrato y token de continuación. El tamaño de página por sí solo no debe decidirlo.

¿Puede el cursor dar autorización?

No. El servidor comprueba derechos independientemente del token de paginación.

¿Deduplicar evita pérdidas?

No. Elimina repeticiones pero no recupera objetos nunca leídos. Pruebe estabilidad del orden y cambios de colección.

Paginación: coherencia y recuperación

Las notas detalladas de esta edición están disponibles en inglés.

Reaching every page does not prove a coherent collection

A paginated collection needs an object order, continuation rules and a reconciliation reference. An advancing cursor can miss a row whose key changes; a correct unique-ID count can mix revisions. This exercise makes those differences checkable on five fictional objects.

Offline simulation: no API request, database or export file is created. Objects A–E, TRAIN tokens and snapshot S1 are teaching fixtures. Results describe this model and guarantee neither provider behavior nor coverage of a real collection.

Initial data: three objects share one timestamp

Initial data: three objects share one timestamp
Identifierupdated_at in UTCRevision
A2026-10-22T10:00:00Z1
B2026-10-22T10:00:00Z1
C2026-10-22T10:00:00Z1
D2026-10-22T10:01:00Z1
E2026-10-22T10:02:00Z1

Ascending (updated_at, id), maximum page size 2, unique A–E IDs and non-null sort fields. Dates use equal precision. Production contracts also need types, collation and NULL handling; the word “cursor” supplies none of those assumptions.

Five computed reads and their references

These five runs model query-boundary reads: a query returning no rows ends each local run. A remote API’s completion rule is a separate contract; the continuation chain below does not stop at an empty page.

P1 · Timestamp alone leaves C behind

After A and B, updated_at > 10:00 skips C because it shares their timestamp. The ordering includes an ID tie-breaker, but the continuation condition omits it.

Reconciliation reference: Unchanged initial dataset

P1 · Timestamp alone leaves C behind
Page and collection readReceived objectsPost-page boundary
1 · Live collection at this readA/r1 · 2026-10-22T10:00:00Z ; B/r1 · 2026-10-22T10:00:00Z2026-10-22T10:00:00Z
2 · Live collection at this readD/r1 · 2026-10-22T10:01:00Z ; E/r1 · 2026-10-22T10:02:00Z2026-10-22T10:02:00Z
3 · Live collection at this readNoneEnd observed in the model
Received rows
4
Unique identifiers
4
Identifiers missing from the reference
C
Repeated identifiers
None
Identifiers received under multiple revisions
None

Four rows arrive and C is missing. A correct batch size does not repair an incomplete boundary.

P2 · Timestamp/ID pair on a stable collection

The boundary retains the last object’s timestamp and ID. After (10:00, B), C remains greater in this order. All five objects are read once in this stable dataset.

Reconciliation reference: Unchanged initial dataset

P2 · Timestamp/ID pair on a stable collection
Page and collection readReceived objectsPost-page boundary
1 · Live collection at this readA/r1 · 2026-10-22T10:00:00Z ; B/r1 · 2026-10-22T10:00:00Z2026-10-22T10:00:00Z / B
2 · Live collection at this readC/r1 · 2026-10-22T10:00:00Z ; D/r1 · 2026-10-22T10:01:00Z2026-10-22T10:01:00Z / D
3 · Live collection at this readE/r1 · 2026-10-22T10:02:00Z2026-10-22T10:02:00Z / E
4 · Live collection at this readNoneEnd observed in the model
Received rows
5
Unique identifiers
5
Identifiers missing from the reference
None
Repeated identifiers
None
Identifiers received under multiple revisions
None

This result depends on an unchanged collection and total order. It promises no frozen view for a live API.

P3 · A moves forward and returns with a new revision

After page one, A changes from 10:00/r1 to 10:03/r2. The pair cursor advances but encounters A again.

Reconciliation reference: Final live collection

P3 · A moves forward and returns with a new revision
Page and collection readReceived objectsPost-page boundary
1 · Live collection at this readA/r1 · 2026-10-22T10:00:00Z ; B/r1 · 2026-10-22T10:00:00Z2026-10-22T10:00:00Z / B
2 · Live collection at this readC/r1 · 2026-10-22T10:00:00Z ; D/r1 · 2026-10-22T10:01:00Z2026-10-22T10:01:00Z / D
3 · Live collection at this readE/r1 · 2026-10-22T10:02:00Z ; A/r2 · 2026-10-22T10:03:00Z2026-10-22T10:03:00Z / A
4 · Live collection at this readNoneEnd observed in the model
Received rows
6
Unique identifiers
5
Identifiers missing from the reference
None
Repeated identifiers
A
Identifiers received under multiple revisions
A

Six rows and five unique IDs arrive. A occurs as revisions 1 and 2. ID deduplication alone does not establish temporal consistency of values; revision handling needs an explicit policy.

P4 · C moves behind the cursor

After page one, C changes from 10:00/r1 to 09:59/r2. Its new key falls below the boundary already passed.

Reconciliation reference: Final live collection

P4 · C moves behind the cursor
Page and collection readReceived objectsPost-page boundary
1 · Live collection at this readA/r1 · 2026-10-22T10:00:00Z ; B/r1 · 2026-10-22T10:00:00Z2026-10-22T10:00:00Z / B
2 · Live collection at this readD/r1 · 2026-10-22T10:01:00Z ; E/r1 · 2026-10-22T10:02:00Z2026-10-22T10:02:00Z / E
3 · Live collection at this readNoneEnd observed in the model
Received rows
4
Unique identifiers
4
Identifiers missing from the reference
C
Repeated identifiers
None
Identifiers received under multiple revisions
None

C is missing despite the complete sorting pair. A mutable sort key needs a consistency strategy beyond a unique tie-breaker.

P5 · Reading S1 retains S1 identities and values

A moves forward and C backward in the live collection, but every page in this run reads the exercise’s immutable S1 copy.

Reconciliation reference: Fictional snapshot S1

P5 · Reading S1 retains S1 identities and values
Page and collection readReceived objectsPost-page boundary
1 · Fictional snapshot S1A/r1 · 2026-10-22T10:00:00Z ; B/r1 · 2026-10-22T10:00:00Z2026-10-22T10:00:00Z / B
2 · Fictional snapshot S1C/r1 · 2026-10-22T10:00:00Z ; D/r1 · 2026-10-22T10:01:00Z2026-10-22T10:01:00Z / D
3 · Fictional snapshot S1E/r1 · 2026-10-22T10:02:00Z2026-10-22T10:02:00Z / E
4 · Fictional snapshot S1NoneEnd observed in the model
Received rows
5
Unique identifiers
5
Identifiers missing from the reference
None
Repeated identifiers
None
Identifiers received under multiple revisions
None

All five revision-1 objects arrive once. S1 is the reconciliation reference; the final live state can differ. An opaque token alone does not establish that a provider implements this snapshot.

A snapshot needs a contract separate from the cursor

A sorting pair defines a boundary; a snapshot defines the objects and values visible during reading. PostgreSQL 18 distinguishes per-command Read Committed views from a Repeatable Read transaction view. An API spanning requests needs to explain its own mechanism and availability period. This exercise opens no transaction and does not recommend indefinitely retaining a production transaction.

An empty page can still have a next page

Under AIP-158, a response can return fewer objects than requested, including zero, without being final. An empty next_page_token signals completion. The TRAIN labels below are public teaching fixtures; clients must not infer a numeric position from them.

An empty page can still have a next page
ResponseSent tokenObjectsReturned continuation
L1StartA, BTRAIN-CONT-1
L2TRAIN-CONT-1NoneTRAIN-CONT-2
L3TRAIN-CONT-2CTRAIN-CONT-3
L4TRAIN-CONT-3D, EEnd observed in the model

Stop a repeated token without claiming completion

Stop a repeated token without claiming completion
ResponseSent tokenObjectsReturned continuation
X1StartA, BTRAIN-LOOP
X2TRAIN-LOOPNoneTRAIN-LOOP

Stop: repeated continuation

The second X response repeats the token already used. The teaching client stops this lack of progress. A real API client also needs bounds on calls, time, memory and retries: a changed token alone does not establish useful progress.

Nine continuation requests: context and permissions

The model binds a token to parent, filter, order and S1. Page size can change under AIP-158’s explicit exception. server_authorized and snapshot_available are server-side facts supplied by the fixture, not authoritative client parameters. Fictional expiry is 22 October 2026 at 13:00 UTC, an exclusive boundary.

C01 · Same context and current permission
{
    "token": "TRAIN-CONT-1",
    "parent": "training/catalogue-a",
    "filter": "state=active",
    "order": "updated_at,id",
    "page_size": 2,
    "now": "2026-10-22T12:00:00Z",
    "server_authorized": true,
    "snapshot_available": true
}

Continuation admissible in the profile

Continuation is admissible in this profile; permission checks still apply to returned objects.

C02 · Only page size changes
{
    "token": "TRAIN-CONT-1",
    "parent": "training/catalogue-a",
    "filter": "state=active",
    "order": "updated_at,id",
    "page_size": 1,
    "now": "2026-10-22T12:00:00Z",
    "server_authorized": true,
    "snapshot_available": true
}

Continuation admissible in the profile

Changing 2 to 1 does not by itself break this pagination context. Do not assume a provider with another contract follows the same rule.

C03 · Different parent
{
    "token": "TRAIN-CONT-1",
    "parent": "training/catalogue-b",
    "filter": "state=active",
    "order": "updated_at,id",
    "page_size": 2,
    "now": "2026-10-22T12:00:00Z",
    "server_authorized": true,
    "snapshot_available": true
}

Reject: different read context

A token must not become a bridge into a different collection parent.

C04 · Different filter
{
    "token": "TRAIN-CONT-1",
    "parent": "training/catalogue-a",
    "filter": "state=archived",
    "order": "updated_at,id",
    "page_size": 2,
    "now": "2026-10-22T12:00:00Z",
    "server_authorized": true,
    "snapshot_available": true
}

Reject: different read context

Reusing a token after changing filters would mix two different reads.

C05 · Different order
{
    "token": "TRAIN-CONT-1",
    "parent": "training/catalogue-a",
    "filter": "state=active",
    "order": "id",
    "page_size": 2,
    "now": "2026-10-22T12:00:00Z",
    "server_authorized": true,
    "snapshot_available": true
}

Reject: different read context

A boundary created for one order must not silently acquire a different interpretation.

C06 · Permission revoked
{
    "token": "TRAIN-CONT-1",
    "parent": "training/catalogue-a",
    "filter": "state=active",
    "order": "updated_at,id",
    "page_size": 2,
    "now": "2026-10-22T12:00:00Z",
    "server_authorized": false,
    "snapshot_available": true
}

Reject: current permission absent

The token still exists but grants no permission. Earlier authorization does not authorize the current request.

C07 · Exact expiry instant
{
    "token": "TRAIN-CONT-1",
    "parent": "training/catalogue-a",
    "filter": "state=active",
    "order": "updated_at,id",
    "page_size": 2,
    "now": "2026-10-22T13:00:00Z",
    "server_authorized": true,
    "snapshot_available": true
}

Recover under policy: token expired

At 13:00:00Z the token is expired under this profile. Its lifetime is fictional and supplies no universal retention recommendation.

C08 · Snapshot unavailable
{
    "token": "TRAIN-CONT-1",
    "parent": "training/catalogue-a",
    "filter": "state=active",
    "order": "updated_at,id",
    "page_size": 2,
    "now": "2026-10-22T12:00:00Z",
    "server_authorized": true,
    "snapshot_available": false
}

Review: S1 reference unavailable

The profile refuses to silently concatenate S1 with a new view. Restart or reconcile under an explicit policy.

C09 · Unknown token
{
    "token": "TRAIN-UNKNOWN",
    "parent": "training/catalogue-a",
    "filter": "state=active",
    "order": "updated_at,id",
    "page_size": 2,
    "now": "2026-10-22T12:00:00Z",
    "server_authorized": true,
    "snapshot_available": true
}

Reject: unknown token

The model accepts only tokens in its fictional registry; it does not decode received text and invent continuation semantics.

Two crash recoveries: the checkpoint changes coverage

S1 batches are A/B, C/D and E. In this in-memory model, “durable” represents a batch already confirmed in fictional local storage. This is no real persistence test. Local processing is idempotent by S1 ID; that does not guarantee an exactly-once external effect.

Before or after the batch: two consequences
Before or after the batch: two consequences Advancing the checkpoint before a batch leaves A and B missing after a crash. Retaining the batch before checkpointing allows rereading and deduplication, recovering all five S1 IDs. Checkpoint before the batch Crash before retaining A/B A/B skipped on recovery Missing: A, B Batch before the checkpoint Crash before checkpointing A/B reread and deduplicated Missing: None
R1 · Checkpoint before retaining the batch

R1 records the next page before retaining A/B. A crash occurs between the operations; recovery skips A and B.

R1 · Checkpoint before retaining the batch
StepSimulated operationRetained objectsRecorded next page
1Record the next page · 2None2
2Crash; volatile memory lostNone2
3Resume at the recorded pageNone2
4Retain the batch idempotently · 2C, D2
5Record the next page · 3C, D3
6Retain the batch idempotently · 3C, D, E3
7Record the next page · 4C, D, EEnd observed in the model

Identifiers missing from the reference: A, B

R2 · Batch retained before checkpoint

R2 retains A/B, then crashes before checkpointing. Recovery rereads A/B; the idempotent sink retains them once, then finishes S1.

R2 · Batch retained before checkpoint
StepSimulated operationRetained objectsRecorded next page
1Retain the batch idempotently · 1A, B1
2Crash; volatile memory lostA, B1
3Resume at the recorded pageA, B1
4Retain the batch idempotently · 1A, B1
5Record the next page · 2A, B2
6Retain the batch idempotently · 2A, B, C, D2
7Record the next page · 3A, B, C, D3
8Retain the batch idempotently · 3A, B, C, D, E3
9Record the next page · 4A, B, C, D, EEnd observed in the model

Identifiers missing from the reference: None

When batch and checkpoint share a suitable local transaction, test their joint commit. Effects across systems need a recovery protocol and reconciliation; simply reordering two calls does not demonstrate distributed atomicity.

Six records for pagination acceptance checks

  • Scope, filter, total order and rules for nullable or mutable keys.
  • Consistency reference: live collection, identified snapshot or another documented contract.
  • Received batches, IDs and revisions, with reconciliation differences.
  • Handling of short/empty pages, repeated tokens and bounded resources.
  • Confirmed recovery checkpoint, local deduplication and completed external effects.
  • Current permission checks and handling of unavailable tokens or snapshots.

The five reads, nine requests and two recoveries are computed editorial counterexamples. AIP-158 applies only to the declared contract; actual guarantees must come from the provider. No client export, real completeness rate or database transaction is claimed.

Primary sources and scope

Sources reviewed on

Referencias oficiales

Las referencias respaldan el método. Adapte los controles a su contexto; no constituyen certificación. Los títulos de referencia originales y los documentos fuente pueden estar en otro idioma.

Referencias consultadas el .