Estatísticas do planejador no PostgreSQL: statistics target, colunas correlacionadas e estimativas erradas

O que é

A documentação descreve as entradas do planejador: reltuples e relpages em pg_class para o tamanho da tabela, e pg_statistic (legível pela view pg_stats) com os valores mais comuns de cada coluna e suas frequências, um histograma dos demais valores, a fração de nulos e o número de valores distintos. O ANALYZE, executado manualmente ou pelo autovacuum, amostra a tabela para preencher esses dados. O número de entradas de valores mais comuns e de histograma por coluna é limitado por default_statistics_target (100 por padrão) ou por um valor definido por coluna com ALTER TABLE ... ALTER COLUMN ... SET STATISTICS. Quando há várias condições na mesma cláusula WHERE, o planejador multiplica as seletividades, o que, segundo a documentação, pressupõe que as condições sejam independentes.

Por que importa

O plano é escolhido com base em estimativas, não nos dados em si. Quando uma estimativa erra por ordens de grandeza, o planejador escolhe um nested loop onde era necessário um hash join, ou um index scan que acaba lendo metade da tabela, e a consulta fica lenta mesmo com todos os índices criados. O EXPLAIN ANALYZE mostra a divergência como linhas estimadas versus linhas reais, no nó em que ela começa.

Como aplicar

• Verifique primeiro se as estatísticas estão atualizadas: last_analyze e last_autoanalyze em pg_stat_user_tables. Uma tabela recém-carregada em massa muitas vezes não tem estatística nenhuma.
• Para uma coluna assimétrica (códigos de status, alguns poucos tenants enormes entre muitos pequenos) cuja estimativa esteja errada para os valores raros, aumente o target apenas nessa coluna, por exemplo SET STATISTICS 1000, e então execute ANALYZE; a documentação aponta como custo mais espaço em pg_statistic e um tempo de planejamento um pouco maior.
• Para condições sobre colunas correlacionadas (cidade e código postal, data do pedido e data de envio), crie estatísticas estendidas: CREATE STATISTICS s (dependencies, ndistinct, mcv) ON a, b FROM t, seguido de ANALYZE. As dependências funcionais valem apenas para condições de igualdade e listas IN com constantes; mcv registra as combinações mais comuns; ndistinct melhora as estimativas de GROUP BY.
• Para um filtro sobre uma expressão (lower(email), date_trunc('day', ts)), crie estatísticas de expressão com CREATE STATISTICS ON (expr) FROM t, que, segundo a documentação, traz benefícios semelhantes aos de um índice de expressão, sem o custo de manutenção do índice.
• Execute EXPLAIN ANALYZE novamente após cada alteração e mantenha-a apenas se as estimativas se aproximarem dos valores reais.

Armadilhas

Aumentar default_statistics_target globalmente consome espaço em pg_statistic e tempo de estimativa em todas as colunas, com pouco ganho; concentre-se nas colunas que precisam. O pg_upgrade só transfere a maior parte das estatísticas a partir do PostgreSQL 18 e nunca as estendidas, portanto uma atualização exige um novo ANALYZE. Um prepared statement pode executar um plano genérico, cujas estimativas ignoram o valor real do parâmetro. E uma amostra não consegue acompanhar uma distribuição que muda a cada hora.