Lição 0 · núcleo ~1 hora

Páginas, custo, e o que o planeador está a minimizar

Esta lição não fala de índices. Fala do que um índice serve para evitar — e sem isso, tudo o que vem a seguir vira regras decoradas que falham no primeiro caso invulgar.

1. Objetivo

No fim consegues, dada uma tabela e o seu número de páginas, calcular à mão o custo que o Postgres atribui a uma varredura sequencial, e conferir que o teu número bate certo com o do EXPLAIN. E consegues explicar porque é que o tempo de uma query se prevê melhor contando páginas do que contando linhas.

2. Recuperar

Primeira lição: não há nada para recuperar ainda. Em vez disso, responde de memória — sem correr nada — e guarda o que respondeste. Vais confrontá-lo daqui a pouco.

1. Uma tabela com 1 000 000 de linhas. Uma query que devolve 1 linha, sem índice. Quantas linhas é que achas que a base de dados teve de examinar?
   Confere depois de leres «O mecanismo»

   Todas. Mas a pergunta está mal feita, e é esse o ponto da lição: ela não examinou «1 000 000 de linhas», leu 8348 páginas — e é esse o número que prevê o tempo.

2. A mesma query demora 15 ms. Se a tabela tiver o dobro das linhas, quanto achas que demora?
   Confere depois

   Aproximadamente o dobro — mas porque o número de páginas duplica, não porque o número de linhas duplica. A distinção parece pedante até apareceres com uma tabela de 3 colunas e outra de 40.

3. O mecanismo

A base de dados não lê linhas

Um disco — mesmo um SSD — não entrega bytes avulsos: entrega blocos. O Postgres organiza tudo o que guarda em páginas de 8 kB (é o valor por omissão, fixado quando o servidor é compilado). Uma página contém tantas linhas quantas lá couberem, e a unidade de leitura é a página inteira.

A consequência é a ideia central de todo este curso:

Isto explica de antemão coisas que de outra forma parecem arbitrárias. Porque é que um índice que devolve 1% das linhas pode não acelerar nada? Porque se esse 1% estiver espalhado por todas as páginas, leste a tabela toda na mesma — e ainda por cima em saltos. Vais medir exatamente isso na lição 3.

A tabela é um monte, não uma lista ordenada

Uma tabela em Postgres chama-se heap, e a palavra é literal: é um monte. As linhas ficam onde houver espaço, na ordem em que foram inseridas ou atualizadas, sem ordem lógica nenhuma. Não há «a linha número 500 000»; há a linha que está na página 4172, posição 7.

Por isso, sem mais nada, encontrar uma linha só se faz de uma maneira: ler todas as páginas e olhar para todas as linhas. É a varredura sequencial — sequential scan, Seq Scan no EXPLAIN.

O planeador não mede tempo. Calcula um custo.

Quando escreves uma query, o Postgres considera várias formas de a executar e escolhe uma. Para escolher, precisa de comparar — e não pode executar cada alternativa para ver qual é mais rápida. Por isso atribui a cada plano um custo: um número numa unidade inventada, em que 1 = ler uma página sequencialmente. Tudo o resto está calibrado em relação a isso.

4. Exemplo trabalhado

Vamos reproduzir à mão, com papel e lápis, o número que o planeador anuncia. Se bater certo, deixas de ter de acreditar em mim — passas a poder verificar.

Prepara a base de treino (faz isto uma vez; usa-se no curso inteiro):

createdb treino_indices
psql -d treino_indices -f preparar.sql

O preparar.sql cria uma tabela encomendas com 1 000 000 de linhas.

Passo 1 — perguntar à tabela o seu tamanho

Porquê primeiro isto: o custo de um Seq Scan depende de duas coisas que o planeador lê do catálogo — quantas páginas e quantas linhas. Se não souberes estes dois números, não podes prever nada.

SELECT relpages, reltuples::bigint
FROM pg_class WHERE relname = 'encomendas';

 relpages | reltuples
----------+-----------
     8348 |   1000000

8348 páginas × 8 kB ≈ 65 MB. Confere: 1 000 000 de linhas com ~68 bytes úteis cada, mais o cabeçalho de 23 bytes por linha e o espaço de gestão da página.

Passo 2 — escrever a conta antes de correr o EXPLAIN

Porquê por esta ordem: se correres primeiro, deixas de estar a prever e passas a estar a justificar. A fórmula de um Seq Scan com um filtro simples tem três parcelas, e cada uma corresponde a trabalho mesmo feito:

• Ler as páginas: 8348 × seq_page_cost (1.0) = 8348
• Processar cada linha: 1 000 000 × cpu_tuple_cost (0.01) = 10 000
• Avaliar o = em cada linha: 1 000 000 × cpu_operator_cost (0.0025) = 2500

Total previsto: 8348 + 10 000 + 2500 = 20 848.

Repara no que a conta diz: o trabalho de CPU (12 500) é maior do que o de leitura (8348). Não é engano — é o que acontece quando um filtro tem de ser avaliado em todas as linhas.

Passo 3 — conferir

EXPLAIN SELECT * FROM encomendas WHERE estado = 'entregue';

Seq Scan on encomendas  (cost=0.00..20848.00 rows=969867 width=36)

Passo 4 — ler os dois números do cost

cost=0.00..20848.00 são dois números, e confundi-los é o erro seguinte:

• 0.00 — custo de arranque: o trabalho antes de sair a primeira linha. Num Seq Scan é zero, porque a primeira linha sai logo da primeira página.
• 20848.00 — custo total: o trabalho até sair a última linha.

A distinção importa mais do que parece. Um Sort tem de ler tudo antes de devolver o que quer que seja, logo tem custo de arranque alto — e por isso perde contra um índice quando há um LIMIT 10, mesmo que o custo total seja parecido.

5. Exemplo com lacunas

Agora a mesma conta para uma tabela diferente. Os passos 1 e 3 estão dados; completa os outros.

6. Erros comuns

7. Praticar

psql -d treino_indices -c "EXPLAIN SELECT * FROM encomendas;"

Seq Scan on encomendas  (cost=0.00..18348.00 rows=1000000 width=36)

psql -d treino_indices
SET seq_page_cost = 2;
EXPLAIN SELECT * FROM encomendas WHERE estado = 'entregue';
RESET seq_page_cost;

Seq Scan on encomendas  (cost=0.00..29196.00 rows=969867 width=36)

8. Quiz

Lê a explicação de todas as opções, incluindo as que não escolheste — é aí que está o que faltava perceber.

9. Explica por palavras tuas

10. Resumo

• A base de dados lê páginas de 8 kB, não linhas. O tempo prevê-se contando páginas.
• Uma tabela é um monte sem ordem: sem índice, encontrar uma linha obriga a ler todas as páginas.
• O cost é uma unidade arbitrária em que 1 = ler uma página em sequência. Não é tempo e não se converte em tempo.
• O custo de um Seq Scan é relpages×1 + reltuples×0.01 + reltuples×0.0025 (com filtro) — e bate certo ao cêntimo.
• Os limiares do planeador vêm de parâmetros configuráveis, não de leis. Quem cita percentagens fixas está a descrever a máquina dele.

11. Fontes

• Documentação do PostgreSQL 17 — Database Page Layout. postgresql.org/docs/17/storage-page-layout.html — fonte primária para o tamanho da página e o que lá vive dentro. 🌐 Verificado a 2026-09-15
• Documentação do PostgreSQL 17 — Planner Cost Constants. runtime-config-query.html — os valores por omissão de cada parâmetro de custo e a advertência explícita de que as unidades são arbitrárias. 🌐 Verificado a 2026-09-15
• Documentação do PostgreSQL 17 — Using EXPLAIN. using-explain.html — porquê: é o texto que faz a conta do Seq Scan passo a passo, e é o melhor de toda a documentação. O que saltar: nada; são poucas páginas. 🌐 Verificado a 2026-09-15
• Todos os números desta lição foram medidos em PostgreSQL 17.11 (Homebrew, macOS arm64), com os parâmetros nos valores por omissão, sobre a tabela de preparar.sql. Na tua máquina os valores de relpages podem diferir ligeiramente; a fórmula não muda. ✅ Corrido a 2026-09-15