VillageSQL is a drop-in replacement for MySQL with extensions.
All examples on this page work on VillageSQL. Install Now →
LIMIT 20 OFFSET 200000 lê 200.020 linhas e descarta 200.000 delas. Isso não é um bug; é o que OFFSET significa. O servidor não tem como saltar para a linha 200.001 em uma ordenação arbitrária, então ele caminha até lá. A página 1 é rápida, a página 10.000 é lenta, e a lentidão cresce linearmente com a profundidade da página. A paginação keyset corrige isso lembrando onde a última página terminou, em vez de contar desde o início.
Paginação com OFFSET: Boa Até Deixar de Ser
O padrão conhecido:- O custo cresce com o número da página.
OFFSET 200000varre e descarta 200.000 entradas de índice antes de retornar qualquer coisa. - As linhas se deslocam entre requisições. Se uma linha é inserida enquanto um usuário pagina, os limites das páginas se movem, e o usuário vê uma duplicata ou perde uma linha.
Paginação Keyset: Lembre Onde Você Parou
Em vez de contar linhas, filtre pelo último valor que o cliente viu:WHERE id > 20 permite que o servidor busque diretamente no índice e leia exatamente 20 linhas, não importa quão profunda seja a página. A página 10.000 custa o mesmo que a página 1. Linhas inseridas não podem deslocar os limites das páginas, porque o limite é um valor, não uma posição.
O trade-off: a paginação keyset oferece próxima e anterior, não “ir para a página 47”. Para rolagem infinita e APIs, essa normalmente é a interface que você queria de qualquer forma.
Ordenando por Algo Diferente da Chave
Listagens reais raramente ordenam porid. Ordene por uma coluna não única e você precisa de um critério de desempate, ou linhas com valores iguais são puladas ou repetidas entre páginas. O cliente devolve os dois valores da última linha que viu, e a consulta compara os dois:
WHERE (created_at, id) > ('2026-08-01 12:00:00', 143). Ela retorna as mesmas linhas, mas o otimizador do MySQL não a converte em uma busca por intervalo no índice: EXPLAIN mostra uma varredura completa (type: ALL ou type: index, dependendo de a consulta ser coberta pelo índice) para o construtor de linha, e uma busca (type: range) para a forma expandida acima. Use a forma expandida.
De qualquer forma, o índice precisa corresponder ao ORDER BY:
EXPLAIN: você quer type: range nesse índice e nenhum filesort. Consulte Lendo o EXPLAIN para saber o que procurar.
Você Precisa de uma Contagem Total?
SELECT COUNT(*) sobre um conjunto filtrado grande pode custar mais que a própria consulta da página. Interfaces construídas sobre paginação keyset normalmente abandonam as contagens exatas em favor de um botão “carregar mais”. Se o produto realmente precisa de uma contagem, coloque-a em cache ou mantenha-a em uma tabela de resumo, em vez de contar a cada requisição.
Qual Usar
Veja também
- Índices do MySQL — o design de índice do qual a paginação keyset depende
- Lendo o EXPLAIN — confirmando a busca em vez de uma varredura
- Estratégias de chave primária — chaves ordenáveis (como UUIDv7) são bons cursores
- MySQL LIMIT — a lição do tutorial sobre LIMIT e OFFSET
- MySQL ORDER BY — a ordenação da qual a paginação depende