Pular para o conteúdo
Setup do Dev
Guias

EXPLAIN ANALYZE no PostgreSQL: como ler o plano de uma consulta lenta

Testamos com 2 milhões de pedidos no PostgreSQL 18: a busca por cliente caiu de 385 ms para 0,8 ms, e o plano mostrou o motivo, linha por linha.

Por Setup do Dev
5 min de leitura
Compartilhar
Capa do Setup do Dev em cinza-azulado com grade: "Lendo o plano do EXPLAIN ANALYZE", com o logo do PostgreSQL, 385 → 0,8 ms em destaque e o plano antes e depois do índice

Uma consulta que buscava os pedidos de um cliente levava 385 milissegundos numa tabela de 2 milhões de linhas. Depois de um índice, passou a levar 0,8 ms, quase 500 vezes menos. O número diz que melhorou; o EXPLAIN ANALYZE diz por quê, e é ele que mostra onde mexer quando a consulta lenta é a sua.

Os planos deste guia saíram de um PostgreSQL 18.4 aqui da redação, numa tabela temporária, que some quando a conexão fecha. O teste inteiro cabe em duas consultas:

CREATE TEMPORARY TABLE pedidos (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  cliente_id int NOT NULL,
  status text NOT NULL,
  criado_em timestamptz NOT NULL,
  total numeric(10,2) NOT NULL);

INSERT INTO pedidos (cliente_id, status, criado_em, total)
SELECT (random() * 99999)::int + 1,
       CASE WHEN r < 0.90 THEN 'entregue' WHEN r < 0.98 THEN 'cancelado' ELSE 'pendente' END,
       now() - random() * interval '730 days',
       round((random() * 900 + 10)::numeric, 2)
FROM (SELECT random() AS r FROM generate_series(1, 2000000)) s;

São 100 mil clientes, 90% dos pedidos entregues, 2% pendentes e datas espalhadas por dois anos.

A primeira leitura: um Seq Scan

Sem índice nenhum além da chave primária, a busca por um cliente devolve este plano:

EXPLAIN (ANALYZE, BUFFERS)
SELECT id, status, total FROM pedidos WHERE cliente_id = 4242;

Seq Scan on pedidos  (cost=0.00..41667.00 rows=21 width=23)
                     (actual time=18.182..385.617 rows=17.00 loops=1)
  Filter: (cliente_id = 4242)
  Rows Removed by Filter: 1999983
  Buffers: local hit=16667
Execution Time: 385.660 ms
Plano de um Seq Scan com as partes marcadas: a estimativa do planejador, o que aconteceu, as linhas removidas pelo filtro e as páginas lidas
Como ler um nó do plano, no teste do Setup do Dev

Cada linha do plano é um nó, e cada nó tem duas metades. A primeira, entre parênteses, é a estimativa do planejador: o custo, em unidades arbitrárias que só servem para comparar planos, as linhas que ele espera devolver (21) e a largura média delas em bytes. A segunda é o que aconteceu: o tempo até a primeira e até a última linha e as linhas de verdade (17).

O resto do diagnóstico está nas linhas de baixo. Seq Scan é a leitura da tabela inteira; Rows Removed by Filter diz que ele descartou 1.999.983 linhas para achar 17; e Buffers conta 16.667 páginas de 8 KB, uns 130 MB lidos da memória. Aparece local porque a tabela é temporária; numa tabela comum, a palavra é shared, e o read ao lado do hit indica o que veio do disco.

No PostgreSQL 18, o BUFFERS já vem ligado no EXPLAIN ANALYZE, e as linhas aparecem com duas casas decimais (17.00), segundo as notas da versão. Em versões anteriores, peça o BUFFERS à mão.

Quando a estimativa erra feio

Antes do ANALYZE, o mesmo plano dizia rows=7083 para as mesmas 17 linhas. Sem estatísticas, o planejador chuta. A documentação recomenda rodar o ANALYZE depois de qualquer carga grande, e lembra que o autovacuum não alcança tabelas temporárias. Estimativa e realidade muito distantes são a primeira coisa a procurar num plano ruim: é ali que o planejador escolhe o caminho errado.

O índice, e o plano lido de dentro para fora

Com CREATE INDEX ON pedidos (cliente_id), o plano muda de forma:

Bitmap Heap Scan on pedidos  (cost=4.58..82.75 rows=20 width=23)
                             (actual time=0.111..0.135 rows=17.00 loops=1)
  Recheck Cond: (cliente_id = 4242)
  Heap Blocks: exact=17
  ->  Bitmap Index Scan on pedidos_cliente_idx  (cost=0.00..4.58 rows=20 width=0)
                                               (actual time=0.077..0.078 rows=17.00 loops=1)
        Index Cond: (cliente_id = 4242)
        Index Searches: 1
Execution Time: 0.782 ms

O plano agora tem dois nós, e se lê de dentro para fora: o mais recuado roda primeiro. O Bitmap Index Scan consulta o índice e monta o mapa das páginas que têm o cliente 4242. O Bitmap Heap Scan visita só essas páginas: Heap Blocks: exact=17, uma página por pedido, contra as 16.667 de antes. O Index Searches, outra novidade do 18, conta quantas buscas o índice fez.

O relatório da semana repetiu a história. A soma dos pedidos dos últimos sete dias, agrupada por status, levou 1.168 ms com Seq Scan e 48,8 ms com um índice em criado_em, 24 vezes menos. Por cima do nó de leitura apareceu um HashAggregate, o nó que agrupa, com 32 kB de memória.

Gráfico de barras com os tempos do teste: 385,7 ms contra 0,78 ms na busca por cliente, 1.168,2 ms contra 48,8 ms no relatório da semana e 821,2 ms contra 55,5 ms na contagem por status
Os tempos do teste no PostgreSQL 18.4

Quando o índice fica de fora

Numa segunda rodada, com índice também em status, contar os pedidos entregues continuou num Seq Scan de 821 ms. Com 90% da tabela no resultado, o planejador calcula que ler tudo em sequência sai mais barato que pular de página em página, e acerta. Para os pendentes, 2% da tabela, o índice entrou, e a contagem levou 55 ms. O Heap Blocks: exact=15183 mostra que esses 39 mil pedidos estavam espalhados por quase todas as páginas, e mesmo assim o índice compensou.

Por isso índice em coluna com poucos valores, como um status, só ajuda nas consultas pelos valores raros. Se o filtro comum é o valor que domina a tabela, o índice ocupa espaço e não entra no plano.

O cuidado que a documentação destaca

O ANALYZE do EXPLAIN executa o comando de verdade. Num SELECT, tudo bem; num UPDATE ou DELETE, os dados mudam. A página do EXPLAIN indica o caminho: BEGIN; EXPLAIN ANALYZE UPDATE ...; ROLLBACK;. E o tempo medido inclui o próprio trabalho de medir, então compare planos sempre na mesma máquina, com os dados já em memória.

Na prática, o roteiro é curto: rode o EXPLAIN (ANALYZE, BUFFERS), procure o nó que gasta mais tempo, compare rows estimado e real, e veja quantas linhas o filtro jogou fora. O índice certo costuma estar escrito ali.

Fontes: Documentação do PostgreSQL 18: EXPLAIN, Usando o EXPLAIN, Carga de dados, Notas do PostgreSQL 18

Produzido com auxílio de IA e revisado pela redação.

Comentários (0)

Ainda não há comentários. Comece a conversa.

Deixe seu comentário

Seu e-mail não será publicado. O primeiro comentário de cada pessoa passa por moderação.

Seja respeitoso

Neste artigo

  1. A primeira leitura: um Seq Scan
  2. Quando a estimativa erra feio
  3. O índice, e o plano lido de dentro para fora
  4. Quando o índice fica de fora
  5. O cuidado que a documentação destaca

Mais lidas

Editorias

Leia também

Newsletter semanal

O essencial da tecnologia, toda sexta no seu e-mail

Uma curadoria da redação com as notícias que importam para quem desenvolve, joga e trabalha com tecnologia. Sem spam.

Ao assinar, você concorda com a política de privacidade. Cancele quando quiser.