Blog

Estatísticas desatualizadas depois da carga em massa: ANALYZE, default_statistics_target e a estimativa que erra por mil vezes

Um SaaS de gestão de pedidos importou o histórico de um cliente novo: 3,9 milhões de pedidos entraram via COPY numa tabela de 40 milhões de linhas. A importação terminou sem erro, os dados estavam corretos e, mesmo assim, o job de consolidação daquele cliente foi cancelado por timeout na mesma noite e o relatório de vendas por SKU não abriu no dia seguinte. Nenhum índice tinha sumido, nenhuma consulta tinha mudado. O planejador do Postgres estimava 2.304 pedidos para o cliente, quando havia 3.912.455, e com essa estimativa escolheu um nested loop que consultou um índice 3,9 milhões de vezes. Um ANALYZE de 11 segundos levou a consulta de 41 minutos para 48 segundos. Este artigo explica de onde vem a estimativa, por que o autoanalyze não rodou depois da carga, quais tabelas ele nunca analisa, como colocar ANALYZE dentro do job de carga e quando vale ajustar default_statistics_target, SET STATISTICS e estatísticas estendidas.

2026-11-15 / Arquitetura / 13 min

01

A importação que deixou o relatório do cliente novo 1.698 vezes errado

O sintoma confunde porque afeta só uma parte dos dados. Os clientes antigos continuavam com relatórios rápidos, e o time começou procurando problema no volume do cliente novo, no tamanho do arquivo importado ou em lock deixado pela carga. A pista certa só apareceu quando alguém comparou, no EXPLAIN ANALYZE, a coluna rows estimada com a real.

D0 22:10  importação do cliente novo (cliente_id 9123): 3.912.455 pedidos via COPY
          pedidos tinha 40,1 milhões de linhas
          limite de autoanalyze: 50 + 0,1 x 40.100.000 = 4.010.050 linhas modificadas
          n_mod_since_analyze depois da carga: 3.912.455 -> abaixo do limite

D0 23:00  job de consolidação do cliente 9123: cancelado por statement_timeout (15 min)
D1 08:30  relatório de vendas por SKU do cliente: carregando até o timeout do gateway
D1 14:20  EXPLAIN ANALYZE: estimado rows=2304, real rows=3.912.455 (1.698 vezes mais)
D1 14:26  ANALYZE pedidos (11 s) -> o mesmo relatório em 48 s, com hash join
D2 05:40  autoanalyze roda sozinho, quando as escritas normais do dia passam do limite
EXPLAIN (ANALYZE, BUFFERS)
SELECT i.sku, sum(i.quantidade) AS unidades, sum(i.total) AS receita
  FROM pedidos p
  JOIN pedido_itens i ON i.pedido_id = p.id
 WHERE p.cliente_id = 9123
 GROUP BY i.sku;

-- Antes do ANALYZE: o planejador espera 2.304 linhas e escolhe nested loop.
-- Real: 3.912.455 linhas, e o índice de pedido_itens é consultado 3,9 milhões de vezes.
HashAggregate  (rows=2304) (actual time=2463102.338..2463551.244 rows=48211 loops=1)
  ->  Nested Loop  (rows=6912) (actual time=0.061..2461308.114 rows=11734870 loops=1)
        ->  Index Scan using pedidos_cliente_idx on pedidos p
              (rows=2304) (actual time=0.031..9120.556 rows=3912455 loops=1)
              Index Cond: (cliente_id = 9123)
        ->  Index Scan using pedido_itens_pedido_idx on pedido_itens i
              (rows=3) (actual time=0.412..0.624 rows=3 loops=3912455)
              Index Cond: (pedido_id = p.id)
Execution Time: 2463551.870 ms

-- Depois do ANALYZE: estimativa na ordem certa e hash join.
HashAggregate  (rows=51000) (actual time=47920.114..48102.630 rows=48211 loops=1)
  ->  Hash Join  (rows=11790000) (actual time=3412.880..44016.301 rows=11734870 loops=1)
        Hash Cond: (i.pedido_id = p.id)
        ->  Seq Scan on pedido_itens i  (rows=131200000) (actual ... rows=131184020 loops=1)
        ->  Hash  (rows=3930000) (actual ... rows=3912455 loops=1)
              ->  Index Scan using pedidos_cliente_idx on pedidos p  (rows=3930000) ...
Execution Time: 48102.630 ms

O plano ruim não é um defeito do planejador. Para 2.304 pedidos, buscar os itens de cada um pelo índice é de fato a escolha mais barata. O problema é que ele decidiu com uma fotografia da tabela tirada antes da importação, quando o cliente 9123 não existia. Estimativa errada por três ordens de grandeza é sempre o primeiro suspeito quando uma consulta que não mudou fica lenta logo depois de uma carga.

02

De onde vem a estimativa: reltuples, MCV, histograma e n_distinct

O planejador não conta linhas na hora de planejar. Ele usa o que o ANALYZE gravou: o total de linhas e páginas em pg_class (reltuples e relpages) e, por coluna, a fração de nulos, a quantidade estimada de valores distintos, a lista dos valores mais comuns com suas frequências (MCV) e um histograma com os demais valores. Tudo isso vem de uma amostra de 300 x default_statistics_target linhas, ou seja, 30 mil linhas no padrão, independentemente do tamanho da tabela.

-- O que o planejador sabe sobre cliente_id.
SELECT null_frac,
       n_distinct,
       array_length(most_common_freqs, 1)                AS qtd_mcv,
       (SELECT sum(f) FROM unnest(most_common_freqs) f)  AS soma_freq_mcv,
       9123 = ANY (most_common_vals::text::bigint[])     AS cliente_no_mcv
  FROM pg_stats
 WHERE schemaname = 'public'
   AND tablename = 'pedidos'
   AND attname = 'cliente_id';
-- null_frac 0 | n_distinct 18400 | qtd_mcv 100 | soma_freq_mcv 0.041 | cliente_no_mcv false

-- Estimativa para um valor fora da lista de MCV:
-- (1 - null_frac - soma_freq_mcv) / (n_distinct - qtd_mcv) x linhas da tabela
-- (1 - 0 - 0.041) / (18400 - 100) x 44.000.000 = cerca de 2.300 linhas, contra 3,9 milhões reais

-- Quando o autoanalyze vai rodar nesta tabela.
SELECT s.n_mod_since_analyze,
       50 + 0.1 * c.reltuples AS limite_autoanalyze,
       greatest(s.last_analyze, s.last_autoanalyze) AS ultimo_analyze
  FROM pg_stat_user_tables s
  JOIN pg_class c ON c.oid = s.relid
 WHERE s.relname = 'pedidos';
-- n_mod_since_analyze 3912455 | limite_autoanalyze 4010050 | ultimo_analyze 2026-10-28 03:12

Para igualdade, se o valor está na lista de MCV, o planejador usa a frequência medida. Se não está, ele assume que todos os valores fora da lista dividem igualmente o que sobrou. Era exatamente o caso do cliente 9123: fora da lista, porque não existia na última amostra, ele recebeu a mesma fatia de um cliente médio. O total de linhas não estava tão errado, porque o planejador corrige reltuples pelo tamanho físico atual da tabela. O que estava errado era a distribuição, e só um novo ANALYZE corrige distribuição.

  • Valor novo fora da MCV: estimado como um valor médio, mesmo que tenha virado o maior da tabela.
  • Data acima do último limite do histograma: o planejador consulta o índice para descobrir o valor máximo real, mas só quando existe índice B-tree na coluna.
  • Colunas correlacionadas, como cliente_id e status: sem estatística estendida, as seletividades são multiplicadas como se fossem independentes.
  • n_distinct subestimado em coluna com muitos valores raros: a amostra vê poucos repetidos e o planejador espera menos grupos no GROUP BY.

03

Por que o autoanalyze não salvou a carga

O autovacuum dispara um ANALYZE quando n_mod_since_analyze passa de autovacuum_analyze_threshold + autovacuum_analyze_scale_factor x reltuples. Com os padrões, 50 linhas mais 10% da tabela. Numa tabela de 40,1 milhões de linhas, isso dá 4.010.050 modificações. A importação inseriu 3.912.455. Ficou abaixo do limite, e o autoanalyze só rodou no dia seguinte, quando as escritas normais completaram a diferença.

Mesmo quando a carga passa do limite, há uma janela sem estatística: o autovacuum acorda a cada autovacuum_naptime (1 minuto por padrão), só enxerga as modificações depois do COMMIT e pode estar ocupado com outras tabelas, limitado por autovacuum_max_workers. O job que carrega e consulta em seguida quase sempre cai nessa janela. Em alguns tipos de tabela, ele simplesmente nunca vai rodar.

SituaçãoO autoanalyze resolve?O que fazer
Carga abaixo de 10% de uma tabela grandeSó quando o acumulado passar do limite, às vezes dias depoisANALYZE no próprio job ou scale_factor menor na tabela
Carga seguida de consulta no mesmo jobNão, a consulta roda antes de o autovacuum acordarANALYZE entre a carga e a consulta
Tabela temporáriaNunca: o autovacuum não acessa tabelas temporáriasANALYZE logo depois de preencher
Tabela particionada (pai)Nunca para o pai; as partições são analisadas normalmenteANALYZE periódico no pai, que alimenta consultas e joins na hierarquia
Restore de dump lógico ou pg_upgrade até o 17Demora, e as consultas rodam sem estatística até lávacuumdb --all --analyze-in-stages logo depois
TRUNCATE seguido de recarga completaSó depois da carga e do naptime, com estatística antiga no meioANALYZE ao final da recarga, antes de liberar a tabela

04

ANALYZE como parte da carga, não como manutenção

A correção estrutural é tratar estatística como parte do dado carregado. Quem muda a distribuição da tabela de forma brusca é responsável por atualizar a estatística antes de liberar a tabela para consultas pesadas. ANALYZE pega um lock SHARE UPDATE EXCLUSIVE, que não bloqueia SELECT, INSERT, UPDATE nem DELETE, pode rodar dentro de transação e enxerga as linhas inseridas pela própria transação.

// importar-pedidos.js
import { createReadStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';
import pg from 'pg';
import { from as copyFrom } from 'pg-copy-streams';

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });

export async function importarPedidos(arquivoCsv, clienteId) {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    await client.query("SET LOCAL statement_timeout = '30min'");

    await pipeline(
      createReadStream(arquivoCsv),
      client.query(
        copyFrom(
          'COPY pedidos (cliente_id, status, criado_em, total) FROM STDIN WITH (FORMAT csv, HEADER true)',
        ),
      ),
    );

    // Carga e ANALYZE na mesma transação: quem consultar depois do COMMIT já encontra estatística nova.
    // ANALYZE enxerga as linhas inseridas pela própria transação e não bloqueia leitura nem escrita.
    // Sem coluna listada: atualiza todas as colunas e as estatísticas estendidas da tabela.
    await client.query('ANALYZE pedidos');
    await client.query('COMMIT');
  } catch (err) {
    await client.query('ROLLBACK');
    throw err;
  } finally {
    client.release();
  }

  await consolidarCliente(clienteId);
}

async function consolidarCliente(clienteId) {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    await client.query(
      'CREATE TEMP TABLE pedidos_cliente (id bigint PRIMARY KEY, total numeric(14, 2)) ON COMMIT DROP',
    );
    await client.query(
      'INSERT INTO pedidos_cliente (id, total) SELECT id, total FROM pedidos WHERE cliente_id = $1',
      [clienteId],
    );
    // Tabela temporária: o autovacuum nunca a analisa, então o ANALYZE é obrigatório.
    await client.query('ANALYZE pedidos_cliente');

    // Agora a consulta pesada roda com estimativa correta.
    await client.query(
      `INSERT INTO resumo_sku (cliente_id, sku, unidades, receita)
       SELECT $1::bigint, i.sku, sum(i.quantidade), sum(i.total)
         FROM pedidos_cliente p
         JOIN pedido_itens i ON i.pedido_id = p.id
        GROUP BY i.sku
       ON CONFLICT (cliente_id, sku)
       DO UPDATE SET unidades = EXCLUDED.unidades, receita = EXCLUDED.receita`,
      [clienteId],
    );
    await client.query('COMMIT');
  } catch (err) {
    await client.query('ROLLBACK');
    throw err;
  } finally {
    client.release();
  }
}

O custo é previsível: o ANALYZE lê uma amostra de páginas, não a tabela inteira, e por isso levou 11 segundos numa tabela de 44 milhões de linhas. Em tabelas muito largas ou com alvo de estatística alto, listar só as colunas usadas em filtros e joins reduz o tempo, com uma ressalva: as estatísticas estendidas só são recalculadas quando todas as colunas delas estão no ANALYZE. Na dúvida, ANALYZE na tabela inteira.

  1. Carregar com COPY ou INSERT em lotes.
  2. Rodar ANALYZE na tabela de destino, na mesma transação ou logo depois do COMMIT.
  3. Rodar ANALYZE em toda tabela temporária ou de staging usada em join.
  4. Só então executar consolidações, refresh de materialized view e relatórios.
  5. Registrar o tempo do ANALYZE no log do job, para perceber quando ele começar a crescer.

05

default_statistics_target, SET STATISTICS e estatísticas estendidas

Atualizar a estatística resolve o caso da carga. Há outra família de erro em que a estatística está atualizada e mesmo assim é pobre demais: a coluna tem distribuição muito desigual, com poucos valores enormes e milhares de valores pequenos, ou duas colunas andam juntas. Aí o ajuste é no conteúdo da estatística, e sempre por coluna, nunca subindo default_statistics_target para o banco inteiro.

-- Autoanalyze por tabela: 1% de mudança ou 50 mil linhas, o que vier primeiro.
ALTER TABLE pedidos SET (
  autovacuum_analyze_scale_factor = 0.01,
  autovacuum_analyze_threshold    = 50000
);

-- Mais amostra e mais MCV só na coluna com distribuição muito desigual.
ALTER TABLE pedidos ALTER COLUMN cliente_id SET STATISTICS 1000;

-- Correlação entre colunas: o planejador para de multiplicar seletividades como se fossem independentes.
CREATE STATISTICS pedidos_cliente_status (ndistinct, dependencies, mcv)
  ON cliente_id, status FROM pedidos;

-- Toda mudança de alvo ou estatística nova só vale depois do próximo ANALYZE.
ANALYZE pedidos;

-- Tabela particionada: o autovacuum analisa as partições, mas nunca o pai.
ANALYZE eventos;            -- pai particionado: estatística da hierarquia inteira
ANALYZE eventos_2026_11;    -- partição recém-carregada
AjusteQuando usarCusto
autovacuum_analyze_scale_factor por tabelaTabela grande que recebe cargas abaixo de 10% do tamanhoMais ANALYZE automático, cada um barato
SET STATISTICS 500 a 1000 na colunaDistribuição desigual: tenants, status raros, chaves com cauda longaANALYZE mais lento e planejamento um pouco mais caro nessa coluna
CREATE STATISTICS (dependencies, ndistinct, mcv)Filtros e GROUP BY em colunas correlacionadasMais espaço em pg_statistic_ext_data e tempo de ANALYZE
ALTER COLUMN SET (n_distinct = ...)n_distinct estimado muito abaixo do real e estável no tempoValor fixo que precisa ser revisto se o dado mudar
default_statistics_target globalQuase nunca: aumenta o custo de todas as colunasANALYZE e planejamento mais lentos no banco inteiro

Com alvo 1000, a amostra passa de 30 mil para 300 mil linhas e a lista de MCV pode guardar até mil valores. No caso do cliente novo, isso não teria evitado o incidente, porque nenhuma amostra antiga conhece um valor que ainda não existia. Alvo maior melhora a fotografia; só o ANALYZE tira uma fotografia nova.

06

Detectar estatística velha antes do usuário

pg_stat_user_tables mostra quanto cada tabela mudou desde o último ANALYZE. Uma consulta agendada que lista as tabelas com maior percentual modificado encontra o problema antes que um relatório fique lento, e serve como alerta para cargas que alguém esqueceu de acompanhar com ANALYZE.

-- Tabelas com muita mudança desde o último ANALYZE, ordenadas pelo percentual.
-- Limite efetivo de autoanalyze, considerando os parâmetros globais.
SELECT s.schemaname,
       s.relname,
       c.reltuples::bigint                          AS linhas,
       s.n_mod_since_analyze,
       round((100.0 * s.n_mod_since_analyze / greatest(c.reltuples, 1))::numeric, 1) AS pct_modificado,
       current_setting('autovacuum_analyze_threshold')::bigint
         + current_setting('autovacuum_analyze_scale_factor')::float8 * c.reltuples AS limite_global,
       greatest(s.last_analyze, s.last_autoanalyze) AS ultimo_analyze
  FROM pg_stat_user_tables s
  JOIN pg_class c ON c.oid = s.relid
 WHERE s.n_mod_since_analyze > 10000
 ORDER BY s.n_mod_since_analyze / greatest(c.reltuples, 1) DESC
 LIMIT 20;
  • Alertar quando uma tabela com mais de 1 milhão de linhas passar de 5% modificado sem ANALYZE.
  • Ativar auto_explain com log_min_duration e log_analyze em amostragem, para guardar o plano das consultas lentas com rows estimado e real.
  • Em pg_stat_statements, observar consultas cujo tempo médio salta logo depois de janelas de carga.
  • No EXPLAIN ANALYZE, desconfiar de qualquer nó com diferença acima de 10 vezes entre rows estimado e real, principalmente em nested loop.
  • Incluir ANALYZE no runbook de restore, de pg_upgrade e de qualquer backfill grande.

FAQ

Perguntas frequentes

Devo rodar ANALYZE depois de toda inserção?

Não. Para escrita contínua e distribuída, o autoanalyze já é suficiente, eventualmente com scale_factor menor nas tabelas grandes. ANALYZE explícito vale depois de mudanças bruscas de distribuição: importação, backfill, TRUNCATE com recarga, preenchimento de tabela temporária ou de staging e restore. A regra prática é: se o job muda mais de alguns por cento da tabela de uma vez, ele termina com ANALYZE.

ANALYZE trava a tabela em produção?

Não para a aplicação. Ele usa SHARE UPDATE EXCLUSIVE, que convive com leituras e escritas e só conflita com VACUUM, outro ANALYZE, CREATE INDEX CONCURRENTLY e alterações de esquema. O custo é de I/O para ler a amostra, normalmente alguns segundos mesmo em tabelas grandes. Se um autovacuum estiver rodando na mesma tabela, o ANALYZE manual espera por ele, o que vale considerar no timeout do job.

Aumentar default_statistics_target resolve estimativa errada?

Só quando a estatística está atualizada e pobre, por exemplo numa coluna com distribuição muito desigual. Se a causa é estatística velha depois de uma carga, alvo maior não ajuda, porque a amostra antiga não conhece os valores novos. E subir o valor global encarece ANALYZE e planejamento de todas as colunas: prefira SET STATISTICS na coluna problemática e CREATE STATISTICS para colunas correlacionadas.

Quem muda a distribuição da tabela atualiza a estatística

Consulta que fica lenta logo depois de uma carga, sem mudança de código nem de índice, quase sempre é estatística velha: o planejador decide com uma fotografia anterior aos dados novos, erra a estimativa por ordens de grandeza e escolhe o plano errado. O autoanalyze não cobre cargas abaixo de 10% da tabela, a janela entre carga e consulta, tabelas temporárias e o pai de tabelas particionadas. A correção é colocar ANALYZE dentro do job de carga, reduzir o scale_factor das tabelas grandes, usar SET STATISTICS e estatísticas estendidas só onde a distribuição pede e monitorar n_mod_since_analyze. Se os seus jobs de importação deixam relatórios lentos no dia seguinte, eu posso revisar o fluxo de carga, os planos e a configuração do banco.