Skip to main content

Tipos de Paginação | Arquitetura

  • Tipos de Paginação | Arquitetura

Vídeo explicativo sobre cursor e offset: Wilson Neto - Youtube

1. Paginação por Página (Page-based Pagination)​

  • Como funciona: O cliente (front-end) informa o número da página que deseja, e o servidor retorna aquele “lote” de registros. Exemplo: /items?page=2&limit=20 → retorna os itens da página 2, com 20 itens por página.

  • Vantagens:

    • Fácil de implementar e entender.
    • Boa para casos simples (listas pequenas ou médias).

  • Desvantagens:

    • Pouco eficiente em bases muito grandes (pois o servidor precisa calcular saltos grandes).
    • Problemas se os dados mudarem entre uma consulta e outra (inconsistência).

2. Paginação por Offset (Offset-based Pagination)​

  • Como funciona: O cliente informa quantos registros deve pular (offset) e quantos deve pegar (limit). Exemplo: /items?offset=40&limit=20 → pula 40 registros e retorna os próximos 20.

  • Vantagens:

    • Flexível (permite pular para qualquer ponto da lista).
    • Simples de implementar em SQL (usa OFFSET e LIMIT).

  • Desvantagens:

    • Custo cresce com offsets altos (o banco precisa percorrer todos os registros até chegar no ponto).
    • Também sofre com inconsistência se os dados mudarem (itens podem “pular” ou se repetir).

3. Paginação por Cursor (Cursor-based Pagination)​

  • Como funciona: Em vez de usar números de página ou offset, o servidor devolve um marcador (cursor) que aponta para a posição do último item retornado. O cliente usa esse cursor na próxima requisição. Exemplo: /items?after=abc123&limit=20 → começa a partir do item identificado por abc123.

  • Vantagens:

    • Muito eficiente em grandes volumes de dados.
    • Evita inconsistência em dados dinâmicos (pois o cursor aponta para um item real, não um índice).
    • Melhor para APIs em tempo real (redes sociais, streams, etc.).

  • Desvantagens:

    • Mais complexo de implementar.
    • Não é fácil “pular para a página 10” — só dá para avançar ou voltar com base nos cursores.

✅ Resumo prático:

  • Page-based: bom para interfaces simples (ex: sites de e-commerce).
  • Offset-based: bom para consultas ad hoc, mas pesado em bases grandes.
  • Cursor-based: ideal para APIs modernas e dados dinâmicos/volumosos.

Exemplos usando Postgres​

-- Tabela de exemplo
CREATE TABLE products (
  id BIGSERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  price NUMERIC(10,2) NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- Índices úteis
CREATE INDEX ON products (created_at, id);

Page-based​

-- params: :page, :limit
-- ex: page=3, limit=20  => OFFSET = 40
SELECT id, name, price, created_at
FROM products
ORDER BY created_at DESC, id DESC
LIMIT :limit
OFFSET (:page - 1) * :limit;

Offset-based​

-- params: :offset, :limit
-- ex: offset=40, limit=20
SELECT id, name, price, created_at
FROM products
ORDER BY created_at DESC, id DESC
LIMIT :limit
OFFSET :offset;

info

O banco de dados faz toda a busca pelo banco com where order e depois aplica o offset

Cursor-based (keyset/seek pagination)​

  • Cursor por coluna temporal + desempate por id
-- params: :limit
SELECT id, name, price, created_at
FROM products
ORDER BY created_at DESC, id DESC
LIMIT :limit;