rochasolutions
Back-end

Paginação de API: Cursor ou Offset, Qual Escolher?

Danilo Rocha6 min de leitura

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:

  1. Se a tabela tem até algumas dezenas de milhares de linhas e provavelmente vai continuar assim, offset resolve sem complicação adicional.
  2. 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.
  3. 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.
  4. 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.
  5. 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.

  1. Escolha uma coluna indexada e com valores únicos, ou uma combinação que garanta unicidade, como created_at mais id como critério de desempate.
  2. Ordene a consulta por essa coluna, sempre na mesma direção usada para gerar o cursor seguinte.
  3. Filtre pelo valor do cursor recebido, usando > ou < conforme a direção, na mesma coluna do ORDER BY.
  4. Na resposta, inclua o valor do último item da página como next_cursor, para o cliente usar na próxima chamada.
  5. 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.