> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Paginação no MySQL: Keyset vs OFFSET

> Por que a paginação com OFFSET fica lenta em páginas profundas, e como a paginação keyset (por cursor) mantém a página 10.000 tão rápida quanto a página 1.

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> 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:

```sql theme={null}
SELECT id, title, created_at
FROM articles
ORDER BY id
LIMIT 20 OFFSET 40;   -- page 3
```

Isso é bom para paginação rasa: telas administrativas, conjuntos de resultados que um humano nunca vai rolar além da página 20. Os problemas aparecem na profundidade:

* **O custo cresce com o número da página.** `OFFSET 200000` varre 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:

```sql theme={null}
-- First page
SELECT id, title, created_at
FROM articles
ORDER BY id
LIMIT 20;

-- Next page: the client sends back the last id it received (say, 20)
SELECT id, title, created_at
FROM articles
WHERE id > 20
ORDER BY id
LIMIT 20;
```

A cláusula `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 por `id`. 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:

```sql theme={null}
-- Sorted by created_at, with id as the tiebreaker
SELECT id, title, created_at
FROM articles
WHERE created_at > '2026-08-01 12:00:00'
   OR (created_at = '2026-08-01 12:00:00' AND id > 143)
ORDER BY created_at, id
LIMIT 20;
```

O SQL também tem uma grafia mais curta com construtor de linha, `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:

```sql theme={null}
CREATE INDEX idx_articles_created_id ON articles (created_at, id);
```

Verifique o plano com `EXPLAIN`: você quer `type: range` nesse índice e nenhum filesort. Consulte [Lendo o EXPLAIN](https://villagesql.com/docs/pt-BR/guides/reading-explain.md) 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

| Situação | Use |
| - | - |
| Tabela administrativa, centenas de linhas | OFFSET, é mais simples |
| Links de página numerados entre os quais o usuário pode saltar | OFFSET, keyset não consegue saltar |
| Paginação de resultados de API | Keyset, retorne um cursor opaco |
| Rolagem infinita | Keyset |
| Qualquer listagem que possa crescer além de \~100 mil linhas | Keyset |

## Veja também

* [Índices do MySQL](https://villagesql.com/docs/pt-BR/guides/mysql-indexes.md) — o design de índice do qual a paginação keyset depende
* [Lendo o EXPLAIN](https://villagesql.com/docs/pt-BR/guides/reading-explain.md) — confirmando a busca em vez de uma varredura
* [Estratégias de chave primária](https://villagesql.com/docs/pt-BR/guides/primary-key-strategies.md) — chaves ordenáveis (como UUIDv7) são bons cursores
* [MySQL LIMIT](https://villagesql.com/docs/pt-BR/tutorial/limit.md) — a lição do tutorial sobre LIMIT e OFFSET
* [MySQL ORDER BY](https://villagesql.com/docs/pt-BR/tutorial/order-by.md) — a ordenação da qual a paginação depende


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.