Paginação de API: Cursor ou Offset, Qual Escolher?
O que é paginação de API
Paginação de API é a técnica de dividir um resultado grande em blocos menores, entregues um por vez a cada requisição. Em vez de devolver quarenta mil pedidos em uma única resposta, a API devolve cinquenta por vez, com alguma informação para o cliente pedir o próximo bloco.
Sem paginação, um endpoint de listagem cresce junto com a tabela. No primeiro mês, com duzentos registros, a resposta sai em milissegundos. Um ano depois, com duzentos mil, o mesmo endpoint serializa um JSON enorme, trava a memória do servidor e demora segundos para o cliente só renderizar a tela. Paginação de API existe para que o tamanho da resposta não dependa do tamanho da tabela.
Existem duas formas de fazer isso na prática: offset e cursor. Elas respondem à mesma pergunta, mas se comportam de modo bem diferente quando a tabela cresce.
Como funciona a paginação por offset
Paginação por offset é a forma que usa LIMIT e OFFSET na consulta: o cliente informa
o número da página, e o banco conta e descarta as linhas anteriores antes de montar a
página pedida.
SELECT * FROM pedidos ORDER BY created_at DESC LIMIT 50 OFFSET 100;
Essa consulta busca a página três, considerando cinquenta itens por página. É simples de implementar e simples de expor na interface: o usuário vê "página 1 de 400" e clica para ir direto na 250, sem passar pelas outras. Para tabelas pequenas, até algumas dezenas de milhares de linhas, o custo é imperceptível.
O problema aparece quando o offset cresce. Com OFFSET 100000, o banco ainda precisa
percorrer e descartar cem mil linhas antes de montar a resposta, mesmo que a página final
tenha só cinquenta itens. A página 1 responde rápido. A página mil, na mesma tabela, piora a cada incremento,
porque o custo da consulta escala com a posição da página, não com o tamanho dela.
Tem outro efeito menos falado: se alguém insere ou apaga uma linha entre uma requisição e a próxima, o offset desloca. O item que era o primeiro da página 4 pode reaparecer na página 5, ou um item pode nunca aparecer, dependendo de onde a inserção aconteceu. Numa lista que o usuário rola enquanto o sistema recebe gravações, isso é visível.
Como funciona a paginação por cursor
Paginação por cursor é a forma que usa o valor do último item da página anterior como ponto de partida da próxima, em vez de contar posições. O cliente não pede "a página três": pede "o que vem depois deste item".
SELECT * FROM pedidos
WHERE created_at < '2026-11-10T14:30:00'
ORDER BY created_at DESC
LIMIT 50;
Aqui o cursor é o created_at do último pedido devolvido na página anterior. O banco usa
o índice dessa coluna para ir direto ao ponto, sem contar nada que ficou atrás. O custo da
consulta fica praticamente constante, independente de estar buscando os primeiros
cinquenta registros ou os últimos. É o mesmo ganho que torna
um índice de banco de dados eficiente: a busca troca uma
varredura linear por uma travessia direta.
A paginação por cursor também resolve o problema de deslocamento do offset. Como o filtro usa um valor real de coluna, uma inserção nova não empurra os itens já vistos. O cliente sempre avança a partir de um ponto fixo, mesmo que a tabela mude embaixo dele.
A limitação é que o cliente perde a capacidade de pular direto para uma página arbitrária. Com cursor só é possível andar sequencialmente: próxima página, página anterior se a API guardar o cursor inverso. Para a maioria das listas de rolagem infinita, feed, histórico de pedidos, timeline, isso nunca é um requisito real.
Cursor ou offset: qual escolher
A escolha depende de dois fatores: o tamanho esperado da tabela e se a interface precisa pular para uma página específica. Os passos abaixo cobrem a maioria dos casos:
- Se a tabela tem até algumas dezenas de milhares de linhas e provavelmente vai continuar assim, offset resolve sem complicação adicional.
- Se a interface mostra números de página clicáveis, como "1, 2, 3... 40", e o usuário espera pular direto para a página 30, offset é a opção que sustenta esse comportamento.
- Se a lista cresce sem limite claro, pedidos, logs, eventos, mensagens, e a interface é de rolagem contínua, cursor evita a degradação que o offset traria em poucos meses.
- Se múltiplos clientes inserem ou apagam linhas enquanto outros usuários navegam pela lista, cursor evita o deslocamento de itens entre uma página e outra.
- Em caso de dúvida real entre os dois, cursor custa pouco mais para implementar e evita ter que migrar sob pressão quando a tabela passar de cem mil linhas.
Como implementar paginação por cursor na prática
Implementar paginação por cursor exige três decisões: qual coluna usar como cursor, como filtrar por ela e como devolver o próximo cursor na resposta.
- Escolha uma coluna indexada e com valores únicos, ou uma combinação que garanta
unicidade, como
created_atmaisidcomo critério de desempate. - Ordene a consulta por essa coluna, sempre na mesma direção usada para gerar o cursor seguinte.
- Filtre pelo valor do cursor recebido, usando
>ou<conforme a direção, na mesma coluna doORDER BY. - Na resposta, inclua o valor do último item da página como
next_cursor, para o cliente usar na próxima chamada. - Se o desempate for necessário, use uma tupla:
WHERE (created_at, id) < (cursor_data, cursor_id), para evitar perder ou duplicar registros com o mesmo timestamp.
Esse formato de resposta, com um campo de cursor explícito, também deixa a API mais fácil de consumir por bibliotecas de scroll infinito no front-end, que já esperam esse padrão.
Paginação de API não é um detalhe de implementação: é o que decide se um endpoint de listagem continua respondendo em milissegundos depois que a tabela sai de mil linhas para um milhão. Offset ainda é a opção certa para tabela pequena e interface com números de página. Cursor é a opção que escala, ao custo de abrir mão do pulo direto para uma página qualquer. Se sua API está lenta numa lista grande e você quer rever a arquitetura de dados por trás dela, fale com a gente.