EXPLAIN query mostra o plano que o PostgreSQL escolhe para uma consulta: uma árvore de etapas (nós) com custos e quantidades de linhas estimados. EXPLAIN ANALYZE query também executa a consulta e acrescenta o tempo, as linhas e os loops reais de cada nó. Leia a árvore do nó mais indentado para fora: os nós internos passam suas linhas para o nó de cima.
Não há índice em email, então o plano é um Seq Scan: o PostgreSQL lê todas as linhas e fica com as que passam no Filter. Rows Removed by Filter mostra o trabalho desperdiçado. Os tempos mudam a cada execução; o formato do plano importa mais que os números.
Ler uma linha do plano
Cada nó imprime uma linha neste formato:
Seq Scan on users (cost=STARTUP..TOTAL rows=N width=W) (actual time=FIRST..LAST rows=N loops=L)
| Parte | Significado |
|---|---|
cost=STARTUP..TOTAL | trabalho estimado antes da primeira linha e para todas as linhas, em unidades do planejador (não milissegundos) |
rows (o primeiro) | número estimado de linhas que o nó retorna |
width | tamanho médio estimado da linha em bytes |
actual time | milissegundos até a primeira linha e até a última, por loop |
rows (o real) | linhas retornadas, por loop |
loops | quantas vezes o nó rodou; multiplique o tempo e as linhas por ele |
Os custos de um nó pai incluem os dos filhos. Planning Time e Execution Time, no final, são os totais da instrução inteira.
Reconhecer os nós mais comuns
EXPLAIN (COSTS OFF) esconde os números, então fica mais fácil ver o formato do plano:
Leia de dentro para fora. As duas tabelas são percorridas e os clientes filtrados vão para um Hash. O Hash Join consulta esse hash com cada pedido, e o GroupAggregate no topo conta o resultado. Os nós que você mais vai encontrar:
| Nó | O que faz |
|---|---|
Seq Scan | lê a tabela inteira |
Index Scan | acha as linhas por um índice e depois lê cada linha na tabela |
Index Only Scan | responde pelo índice sem visitar a tabela |
Bitmap Index Scan + Bitmap Heap Scan | junta pelo índice a localização das linhas que batem e depois lê essas linhas na ordem da tabela |
Nested Loop | para cada linha externa, procura correspondências na entrada interna; bom quando o lado externo é pequeno |
Hash Join + Hash | monta uma tabela hash com uma entrada e consulta com a outra |
Merge Join | junta duas entradas já ordenadas pela chave do join |
Sort, Incremental Sort | ordena linhas para ORDER BY, DISTINCT ou um merge join |
HashAggregate, GroupAggregate | GROUP BY com tabela hash, ou sobre uma entrada ordenada |
Limit | para depois de N linhas |
Gather | reúne linhas dos workers paralelos |
Achar estimativas de linhas erradas
A verificação mais útil no EXPLAIN ANALYZE é comparar as rows estimadas com as rows reais no mesmo nó. Quando estão muito distantes, o planejador escolheu o plano com números errados, muitas vezes porque as estatísticas faltam ou estão defasadas:
O scan retorna 10 linhas reais, mas a estimativa é bem maior porque a tabela ainda não foi analisada. Adicione ANALYZE tasks; antes do EXPLAIN e a estimativa chega perto de 10. O autovacuum analisa as tabelas em segundo plano, mas rode ANALYZE você mesmo depois de uma carga em massa (veja VACUUM e autovacuum).
Explicar uma alteração de dados sem mantê-la
O EXPLAIN ANALYZE executa a instrução, então um UPDATE ou DELETE altera linhas. Coloque dentro de uma transação e faça rollback:
As 1000 linhas continuam lá depois do rollback.
Ver o I/O com BUFFERS e outras opções
EXPLAIN (ANALYZE, BUFFERS) SELECT ...; -- pages read from cache (hit) and disk (read)
EXPLAIN (ANALYZE, BUFFERS, SETTINGS) SELECT ...; -- also list changed planner settings
EXPLAIN (FORMAT JSON) SELECT ...; -- machine-readable, for plan visualizers
EXPLAIN (ANALYZE, TIMING OFF) SELECT ...; -- row counts without per-node timing overhead
BUFFERS mostra o I/O: um nó com muitas páginas read foi ao disco. O PostgreSQL 17 adicionou SERIALIZE (o custo de converter as linhas de saída em texto) e MEMORY (a memória do planejador). O guia oficial do EXPLAIN mostra mais planos.
Testar um plano com configurações do planejador
Para ver o plano que o PostgreSQL usaria sem um determinado método, desligue esse método na sua sessão. Faça isso só em testes, nunca em código de produção:
Com 100 linhas o planejador prefere um Seq Scan; com enable_seqscan = off o plano mostra Index Scan using items_pkey. Compare os tempos dos dois EXPLAIN ANALYZE para ver se o índice ajuda. RESET enable_seqscan; volta ao padrão.
Perguntas frequentes
Qual a diferença entre EXPLAIN e EXPLAIN ANALYZE?
EXPLAIN só planeja a consulta e mostra estimativas. EXPLAIN ANALYZE também executa a consulta e acrescenta o tempo, as linhas e o número de loops reais de cada nó, então demora o mesmo que a própria consulta.
O que significa cost num plano do PostgreSQL?
Cost é a estimativa do planejador em unidades arbitrárias, calibradas para que ler uma página sequencialmente custe 1 (seq_page_cost). Serve para comparar planos da mesma consulta, não como tempo em milissegundos.
O EXPLAIN ANALYZE altera dados?
Altera. Em INSERT, UPDATE, DELETE e MERGE ele faz a mudança. Rode entre BEGIN e ROLLBACK para medir sem manter o resultado.
Por que um Seq Scan é escolhido quando existe um índice?
Porque o planejador estima que ele é mais barato: a tabela é pequena, a consulta retorna boa parte das linhas ou a condição não consegue usar o índice. Estatísticas defasadas também podem enganá-lo, e o ANALYZE resolve isso.