Pular para o conteúdo

Paginação por cursor vs offset: qual usar e quando

A página 1 da lista carrega rápido, a página 500 demora segundos e às vezes repete itens. Entenda a diferença entre paginação por offset e por cursor.

Por Roger C. Ribeiro, fundador da Wecodex3 min de leitura

A página 1 da lista carrega rápido, a página 500 demora segundos e às vezes repete itens. Entenda a diferença entre paginação por offset e por cursor.

A forma mais comum de paginar é por offset: "pule 40 itens e traga 20". É simples e permite ir direto para a página 7. Mas, conforme a tabela cresce, ela cobra seu preço.

O problema do offset

  • Lentidão nas páginas finais: para "pular 100 mil itens", o banco precisa percorrê-los. A página 5.000 pode levar segundos.
  • Itens duplicados ou perdidos: se um item novo entra enquanto o usuário navega, tudo se desloca e ele vê o mesmo item duas vezes — ou nunca vê outro.

Paginação por cursor

Em vez de "pule N", você diz "traga 20 depois deste item":

sql
SELECT * FROM pedidos
WHERE criado_em < $1
ORDER BY criado_em DESC
LIMIT 20

O cursor é o valor do último item recebido. Com um índice na coluna de ordenação (Índices no banco de dados: a otimização mais barata que você ainda não fez), a consulta é igualmente rápida na primeira e na milésima página, e não duplica itens.

Quando usar cada um

  • Offset: listas pequenas, painéis administrativos e quando o usuário precisa saltar para uma página específica.
  • Cursor: feeds, rolagem infinita, apps e APIs públicas com muito volume.

Detalhes que fazem diferença

  • Ordene por uma coluna única (ou combine com o id) para evitar empates.
  • Devolva o próximo cursor na resposta, pronto para o cliente usar.
  • Limite o tamanho máximo da página.

Paginação é uma das convenções básicas de API REST: boas práticas de nomes, status codes e paginação, e listas infinitas no app dependem dela (Listas lentas no React Native: FlatList, FlashList e memo).

A Wecodex constrói APIs que aguentam crescimento em sistemas web. Fale com a gente.

  • Paginação
  • APIs
  • Banco de dados
  • Performance
CompartilharWhatsAppLinkedIn

Escrito por

Roger C. Ribeiro

Fundador da Wecodex. Escreve sobre engenharia de software, performance, APIs, segurança e IA aplicada a empresas.

Serviços relacionados

Resolver de vez, com quem faz isso todo dia

Precisa de uma API ou integração que não caia quando o negócio crescer?

Este artigo mostra o caminho. A implementação sob medida, o detalhe que muda o resultado no seu caso, é o trabalho da Wecodex, empresa de engenharia do grupo Wocom.