Menu

EXPLAIN ANALYZE no PostgreSQL: como ler um plano

O EXPLAIN mostra o plano que o PostgreSQL escolhe para uma consulta, e o EXPLAIN ANALYZE executa a consulta e acrescenta as linhas e os tempos reais de cada etapa. Aprenda a ler a árvore do plano e os nós mais comuns.

Esta página tem editores executáveis. Edite, execute e veja a saída na hora.

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)
ParteSignificado
cost=STARTUP..TOTALtrabalho 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
widthtamanho médio estimado da linha em bytes
actual timemilissegundos até a primeira linha e até a última, por loop
rows (o real)linhas retornadas, por loop
loopsquantas 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 Scanlê a tabela inteira
Index Scanacha as linhas por um índice e depois lê cada linha na tabela
Index Only Scanresponde pelo índice sem visitar a tabela
Bitmap Index Scan + Bitmap Heap Scanjunta pelo índice a localização das linhas que batem e depois lê essas linhas na ordem da tabela
Nested Looppara cada linha externa, procura correspondências na entrada interna; bom quando o lado externo é pequeno
Hash Join + Hashmonta uma tabela hash com uma entrada e consulta com a outra
Merge Joinjunta duas entradas já ordenadas pela chave do join
Sort, Incremental Sortordena linhas para ORDER BY, DISTINCT ou um merge join
HashAggregate, GroupAggregateGROUP BY com tabela hash, ou sobre uma entrada ordenada
Limitpara depois de N linhas
Gatherreú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.

Ilustração das linguagens de programação do Coddy

Aprenda a programar com o Coddy

Começar