Paginação em APIs pode repetir ou pular registros quando a lista muda entre duas requisições. Mesmo com uma ordenação correta, OFFSET conta posições na lista atual. Se alguém inserir ou excluir uma linha antes da próxima página, o mesmo deslocamento pode apontar para outro trecho.
Um cursor baseado em chaves pode continuar a busca depois do último registro recebido. Ele reduz esse problema de posição, mas não congela o conjunto de dados nem entrega, por si só, uma fotografia consistente de toda a consulta.
Neste artigo
Primeiro, defina uma ordem sem empates indefinidos
O manual de LIMIT e OFFSET do PostgreSQL alerta para a necessidade de uma ordenação previsível. Ordenar apenas por data pode deixar vários registros empatados. Um identificador único pode completar a ordem:
ORDER BY criado_em DESC, id DESC
O desempate precisa acompanhar todas as páginas. Trocar a ordem ou um filtro no meio da navegação muda a pergunta feita à API. Também é necessário definir como valores nulos e campos mutáveis serão tratados.
Uma lista pequena que muda entre as requisições
Executamos um exemplo em PostgreSQL 16.15, num banco descartável sem rede externa. A tabela tem seis linhas com o mesmo timestamp, de modo que o identificador determina o desempate:
CREATE TABLE eventos_demo (
id integer PRIMARY KEY,
criado_em timestamptz NOT NULL
);
INSERT INTO eventos_demo
SELECT i, '2026-11-17T12:00:00Z'::timestamptz
FROM generate_series(101, 106) AS i;
A primeira consulta, com limite de três, entrega 106, 105, 104:
SELECT id, criado_em
FROM eventos_demo
ORDER BY criado_em DESC, id DESC
LIMIT 3;
São dados sintéticos. O horário faz parte da construção do exemplo e não representa registros de uma aplicação real.
Uma inserção faz OFFSET repetir uma linha
Depois de entregar a primeira página, inserimos 107 com o mesmo timestamp. A lista passa a começar por 107, 106, 105, 104. A segunda consulta com OFFSET 3 pula os três primeiros registros da lista nova e devolve 104, 103, 102.
O registro 104 reaparece, embora cada consulta tenha usado a ordenação definida. O problema não foi uma linha duplicada no banco: foi a mudança da posição entre as duas leituras.
Em um segundo cenário, restauramos a lista inicial e removemos 105 depois da primeira página. Agora OFFSET 3 entrega 102, 101, deixando 103 fora da continuação. Ele continua no banco, mas sua posição recuou.
| Cenário após a primeira página | Segunda página por OFFSET | Continuação após a chave de 104 |
|---|---|---|
| Inserção de 107 no início | 104, 103, 102 |
103, 102, 101 |
| Exclusão de 105 na lista original | 102, 101 |
103, 102, 101 |
Esses resultados foram observados no ensaio local. Não são uma medição de tráfego concorrente ou de desempenho do servidor.
O cursor precisa preservar a chave completa
Para continuar depois de 104, usamos a data e o identificador que encerraram a primeira página:
SELECT id, criado_em
FROM eventos_demo
WHERE (criado_em, id) <
('2026-11-17T12:00:00Z'::timestamptz, 104)
ORDER BY criado_em DESC, id DESC
LIMIT 3;
A comparação de linhas do PostgreSQL permite comparar essa tupla. Para a ordem descendente do exemplo, procuramos valores menores que a chave anterior. Outra ordenação exige a condição correspondente.
Se o cursor guardasse apenas a data, não distinguiria os seis registros empatados. Se guardasse apenas o identificador numa lista ordenada prioritariamente por outra coluna, poderia continuar no lugar errado.
Na API, o cursor pode ser opaco para o consumidor. Ainda assim, o servidor precisa associá-lo à ordenação, aos filtros e ao contexto autorizado. Codificar um valor em Base64 não o transforma em autorização nem impede alterações por um cliente.
Cursor não é sinônimo de snapshot
Uma linha que muda sua própria chave de ordenação pode atravessar o ponto do cursor. Novos registros inseridos depois desse ponto podem aparecer durante a navegação. A técnica não garante que todas as páginas representem um único instante.
O manual de isolamento de transações explica quando leituras observam snapshots. Requisições HTTP independentes não passam a compartilhar uma transação consistente só porque a API usa cursor.
Se o produto precisa exportar exatamente um conjunto fechado, defina um mecanismo próprio de consistência: por exemplo, materializar o resultado ou delimitar uma versão e suas regras de leitura. A escolha depende do contrato e da operação; manter uma transação aberta indefinidamente enquanto alguém navega não é uma consequência obrigatória da paginação.
Qual comportamento o consumidor deve esperar
Uma lista de atividade recente e uma exportação financeira têm necessidades diferentes. Defina se a navegação admite mudanças, por quanto tempo um cursor vale e o que acontece quando filtros ou permissões mudam.
Também considere a experiência de uso: chegar diretamente à “página 400” combina naturalmente com deslocamentos, enquanto continuar uma sequência combina com chaves. O custo de offsets grandes e o índice adequado para a ordenação precisam de avaliação no banco real.
Antes de liberar a API, teste empate de datas, inserção e exclusão entre páginas, alteração da chave e cursor usado com outro filtro. Confira os identificadores entregues, e não apenas a quantidade de linhas. Registre no contrato da API se o resultado é uma lista em movimento ou um conjunto estabilizado.