Blog

Índice parcial e índice de expressão que o banco não usa: predicado, tipo do parâmetro e a consulta que não casa

Um sistema de cobrança processava suas tarefas assíncronas numa tabela de 48 milhões de linhas, das quais só 31 mil estavam pendentes em qualquer momento. Um índice parcial de 14 MB, com WHERE status = 'pendente', deixava a consulta de reserva dos workers em 0,4 ms. Um deploy simples, que fez tarefas com timeout voltarem para a fila com um novo status, 'reprocessar', trocou o filtro do worker para status IN ('pendente', 'reprocessar'). A consulta passou para 11,2 segundos, o disco do banco saturou e a fila acumulou 180 mil tarefas em vinte minutos. O índice continuava lá, válido e atualizado; o planejador só não conseguia provar que ele servia para a consulta nova. Índices parciais e índices de expressão são das ferramentas mais eficientes do Postgres, mas funcionam por um contrato estrito: o WHERE precisa implicar o predicado do índice, e a expressão da consulta precisa ser a mesma do índice, inclusive no tipo. Este artigo mostra como o planejador faz essa verificação, quais mudanças pequenas a quebram (um valor a mais no IN, um parâmetro no lugar do literal, um now(), um cast diferente) e como auditar e travar isso com um teste de plano na aplicação.

2026-11-18 / Arquitetura / 13 min

01

O worker que passou a varrer 48 milhões de linhas

A tabela tarefas guardava todo o histórico: 99,9% das linhas estavam concluídas e nunca mais seriam lidas pelo worker. Por isso o índice era parcial. Um índice comum em (status, agendada_para) teria 1,9 GB e seria atualizado em toda escrita; o parcial tinha 14 MB, cabia inteiro em memória e só era tocado pelas linhas que entravam ou saíam do estado pendente.

D0 15:10  deploy: tarefas que falharam por timeout voltam para a fila com status 'reprocessar'
          o worker passa a buscar status IN ('pendente', 'reprocessar')
D0 15:12  consulta de reserva: de 0,4 ms para 11,2 s; leitura de disco do banco em 100%
D0 15:30  fila acumula 180 mil tarefas; escalar workers de 4 para 12 só piora a leitura
D0 16:05  rollback do deploy: a reserva volta a 0,4 ms em segundos
D1 10:00  EXPLAIN mostra Seq Scan com 47,9 milhões de linhas removidas pelo filtro
D1 10:40  tarefas_pendentes_idx não cobre 'reprocessar'; índice novo com os dois estados
D1 11:20  deploy refeito: reserva em 0,5 ms e idx_scan do índice novo subindo

O diagnóstico demorou porque nada parecia quebrado. Não havia erro, o índice aparecia no \d da tabela, o pg_stat_user_indexes mostrava idx_scan crescendo até as 15:10 e parando, e a consulta nova era só uma versão um pouco mais larga da antiga. O sintoma mais enganoso foi a reação ao escalonamento: mais workers significaram mais varreduras sequenciais simultâneas de 22 GB, e o banco ficou mais lento para todo o resto. Com FOR UPDATE na consulta, o Postgres nem pode usar varredura paralela, então cada reserva era um único processo lendo a tabela inteira.

02

Como o planejador decide que um índice parcial serve

Um índice parcial só contém as linhas que satisfazem o predicado. Para usá-lo, o planejador precisa ter certeza de que nenhuma linha que a consulta quer ficou de fora, ou seja, que o WHERE da consulta implica logicamente o predicado do índice. Essa prova é feita no planejamento, antes de qualquer dado ser lido, e é deliberadamente conservadora: se não der para provar, o índice é descartado, mesmo que na prática todos os dados estejam lá.

  1. O planejador separa o WHERE da consulta em condições combinadas por AND e tenta mostrar que elas, juntas, implicam cada parte do predicado do índice.
  2. Condições idênticas ao predicado provam na hora, depois da normalização: arquivada = false vira NOT arquivada, x IN (a) vira x = a.
  3. Comparações com constantes entram em regras de operadores B-tree: status = 'pendente' implica status IN ('pendente', 'reprocessar'), e agendada_para > '2026-06-01' implica agendada_para > '2026-01-01'.
  4. O que não é constante no momento do planejamento não prova nada: parâmetros de um plano genérico, now(), current_date e qualquer função que não seja IMMUTABLE.
  5. Se alguma parte do predicado não for provada, o índice parcial nem entra na lista de caminhos possíveis. Não é uma questão de custo: ele simplesmente não aparece.
-- A fila: 48 milhões de tarefas, 31 mil pendentes. O índice parcial tem 14 MB.
CREATE INDEX CONCURRENTLY tarefas_pendentes_idx
    ON tarefas (agendada_para)
 WHERE status = 'pendente';

-- Consulta original: o WHERE implica o predicado e o índice parcial entra no plano.
EXPLAIN (ANALYZE, BUFFERS)
SELECT id FROM tarefas
 WHERE status = 'pendente' AND agendada_para <= now()
 ORDER BY agendada_para
 LIMIT 50
   FOR UPDATE SKIP LOCKED;

Limit  (actual time=0.071..0.412 rows=50 loops=1)
  ->  LockRows  (actual time=0.070..0.405 rows=50 loops=1)
        ->  Index Scan using tarefas_pendentes_idx on tarefas  (actual time=0.041..0.188 rows=50 loops=1)
              Index Cond: (agendada_para <= now())
              Buffers: shared hit=58
Execution Time: 0.447 ms

-- Depois do deploy: 'reprocessar' entrou no IN e não é coberto pelo predicado.
EXPLAIN (ANALYZE, BUFFERS)
SELECT id FROM tarefas
 WHERE status IN ('pendente', 'reprocessar') AND agendada_para <= now()
 ORDER BY agendada_para
 LIMIT 50
   FOR UPDATE SKIP LOCKED;

Limit  (actual time=11204.388..11204.502 rows=50 loops=1)
  ->  LockRows  (actual time=11204.386..11204.494 rows=50 loops=1)
        ->  Sort  (actual time=11204.311..11204.330 rows=50 loops=1)
              Sort Key: agendada_para
              Sort Method: top-N heapsort  Memory: 31kB
              ->  Seq Scan on tarefas  (actual time=0.022..11187.604 rows=31877 loops=1)
                    Filter: ((status = ANY ('{pendente,reprocessar}'::text[])) AND (agendada_para <= now()))
                    Rows Removed by Filter: 47968123
                    Buffers: shared hit=402118 read=2468305
Execution Time: 11204.611 ms

-- Correção: o predicado do índice passa a cobrir os dois estados que o worker busca.
CREATE INDEX CONCURRENTLY tarefas_a_processar_idx
    ON tarefas (agendada_para)
 WHERE status IN ('pendente', 'reprocessar');
DROP INDEX CONCURRENTLY tarefas_pendentes_idx;

-- PostgreSQL 16+: com $1 no lugar do literal, nenhum índice parcial de status serve.
EXPLAIN (GENERIC_PLAN)
SELECT id FROM tarefas
 WHERE status = $1 AND agendada_para <= now()
 ORDER BY agendada_para
 LIMIT 50;

Limit  (cost=3812744.18..3812744.30 rows=50 width=14)
  ->  Sort  (cost=3812744.18..3836697.43 rows=9581302 width=14)
        Sort Key: agendada_para
        ->  Seq Scan on tarefas  (cost=0.00..3494469.00 rows=9581302 width=14)
              Filter: ((status = $1) AND (agendada_para <= now()))
Predicado do índiceCondição na consultaO índice pode ser usado?
status = 'pendente'status = 'pendente'Sim, condição idêntica
status IN ('pendente', 'reprocessar')status = 'pendente'Sim, o valor está na lista
status = 'pendente'status IN ('pendente', 'reprocessar')Não, 'reprocessar' fica fora do índice
status = 'pendente'status = $1 (plano genérico)Não, o valor é desconhecido no planejamento
agendada_para > '2026-01-01'agendada_para > '2026-06-01'Sim, a faixa está contida
agendada_para > '2026-01-01'agendada_para > now() - interval '1 day'Não, now() não é constante no planejamento
NOT arquivadaarquivada = falseSim, o planejador normaliza para NOT arquivada

A terceira linha é o incidente. A consulta pede um conjunto maior do que o índice guarda, e o planejador está certo em recusar: o índice não tem as tarefas em 'reprocessar'. A correção foi criar o índice com o predicado da consulta nova antes de subir o código, e só então remover o antigo. As duas operações com CONCURRENTLY, para não bloquear escrita numa tabela que recebe 300 inserções por segundo.

03

Parâmetro no lugar do literal: o plano genérico não prova nada

A mesma regra tem uma consequência menos óbvia. Se o valor que casa com o predicado chega como parâmetro, status = $1, o índice parcial só pode ser usado quando o plano é montado com o valor real. Em consultas não preparadas e nos planos custom de prepared statements, o Postgres substitui $1 pelo valor antes de planejar e a prova funciona. No plano genérico, $1 continua desconhecido, e nenhum índice com predicado sobre status é elegível. O EXPLAIN (GENERIC_PLAN), disponível a partir do PostgreSQL 16, mostra isso sem precisar preparar nada: o plano cai em varredura sequencial e ordenação de 9,5 milhões de linhas estimadas.

No modo padrão de plan_cache_mode, isso costuma se esconder: como o plano genérico sem o índice parcial fica muito mais caro que os planos custom, o Postgres continua montando plano custom a cada execução. O problema aparece quando alguém força plano genérico para economizar planejamento, quando um pooler ou driver é configurado com force_generic_plan para toda a aplicação, ou em funções PL/pgSQL e statements preparados em que o genérico vence por outros motivos. Nesses casos, a consulta passa a ignorar o índice parcial sem nenhuma mudança no código SQL.

  • Valores que definem a fatia lógica do índice (estado da fila, tipo de registro, flag de exclusão) devem ficar como literal no SQL. São constantes do código, não entrada do usuário, então escrevê-los no texto não abre brecha para injeção.
  • Parâmetros continuam no resto da consulta: limite, intervalo de datas, identificadores. Esses não fazem parte do predicado do índice.
  • Se o mesmo código atende vários estados vindos de fora, prefira consultas distintas por estado, cada uma com seu literal, a uma única consulta com status = $1.
  • Query builders e ORMs que parametrizam tudo automaticamente precisam de um escape para literal, como sql.raw ou equivalente, usado só para essas constantes.

04

Índice de expressão: a consulta precisa repetir a mesma expressão

Índices de expressão têm um contrato parecido, mas a verificação é ainda mais literal. O planejador compara a expressão da consulta com a expressão guardada no índice depois de normalizar as duas, e só usa o índice se forem estruturalmente iguais: mesmas funções, mesmos argumentos, mesmos casts. Ele não sabe que duas expressões diferentes produzem o mesmo valor, e não reescreve a consulta para caber no índice.

-- Índice de expressão criado para o relatório diário no horário de Brasília.
CREATE INDEX CONCURRENTLY pedidos_dia_local_idx
    ON pedidos (((criado_em AT TIME ZONE 'America/Sao_Paulo')::date));

-- Não casa: criado_em::date é outra expressão e ainda depende do TimeZone da sessão.
SELECT count(*) FROM pedidos
 WHERE criado_em::date = '2026-11-17';

-- Casa: a mesma expressão do índice, escrita do mesmo jeito.
SELECT count(*) FROM pedidos
 WHERE (criado_em AT TIME ZONE 'America/Sao_Paulo')::date = '2026-11-17';

-- JSON: o índice guarda bigint, então a consulta precisa comparar bigint.
CREATE INDEX CONCURRENTLY eventos_cliente_idx
    ON eventos (((payload->>'cliente_id')::bigint));

SELECT * FROM eventos WHERE payload->>'cliente_id' = '4821';         -- não usa: compara texto
SELECT * FROM eventos WHERE (payload->>'cliente_id')::int = 4821;    -- não usa: integer não é bigint
SELECT * FROM eventos WHERE (payload->>'cliente_id')::bigint = 4821; -- usa

-- Tipo do parâmetro: numeric obriga a converter a coluna bigint e o índice da PK sai do plano.
EXPLAIN SELECT * FROM pedidos WHERE id = 90210::numeric;

Seq Scan on pedidos  (cost=0.00..1015416.00 rows=150000 width=96)
  Filter: ((id)::numeric = '90210'::numeric)

EXPLAIN SELECT * FROM pedidos WHERE id = 90210::bigint;

Index Scan using pedidos_pkey on pedidos  (cost=0.56..8.58 rows=1 width=96)
  Index Cond: (id = '90210'::bigint)

O caso da data é comum. criado_em::date sobre uma coluna timestamptz não pode ser indexado, porque o resultado depende do TimeZone da sessão e a função não é IMMUTABLE. A equipe então cria o índice com AT TIME ZONE 'America/Sao_Paulo', que é estável, mas a consulta antiga continua com ::date e varre a tabela. Muitas vezes a melhor correção nem é o índice de expressão: um intervalo sobre a própria coluna, criado_em >= '2026-11-17 00:00-03' AND criado_em < '2026-11-18 00:00-03', usa o índice comum de criado_em e não depende do fuso da sessão.

Expressão no índiceExpressão na consultaResultado
lower(email)lower(email) = $1Usa o índice
lower(email)email ILIKE $1Não usa: outra operação
((payload->>'cliente_id')::bigint)payload->>'cliente_id' = '4821'Não usa: compara texto
((payload->>'cliente_id')::bigint)(payload->>'cliente_id')::int = 4821Não usa: o cast é para integer
((criado_em AT TIME ZONE 'America/Sao_Paulo')::date)criado_em::date = $1Não usa: expressão diferente

05

O tipo do parâmetro que faz até o índice comum sumir

O mesmo mecanismo afeta índices simples quando o tipo do valor comparado não é o da coluna. Para usar um índice B-tree, o operador da comparação precisa pertencer à família de operadores do índice com a coluna do lado esquerdo sem conversão. bigint comparado com integer ou smallint tem operadores cruzados na mesma família, e o índice funciona. bigint comparado com numeric não tem: o Postgres converte a coluna para numeric, a condição vira (id)::numeric = valor e o índice da chave primária deixa de ser elegível.

Origem do valorTipo que chega ao servidorEfeito em id bigint = $1
node-postgres (pg) com number ou stringunknown, inferido pela colunabigint, usa o índice
SQL gerado com $1::numeric ou literal 90210.0numericConverte a coluna, ignora o índice
JDBC setLongint8Usa o índice
JDBC setBigDecimalnumericConverte a coluna, ignora o índice
Coluna char(n) comparada com parâmetro texttextConverte a coluna, ignora o índice

O node-postgres envia parâmetros sem tipo e deixa o servidor inferir pelo contexto, o que evita a maioria desses casos. O risco aparece em casts explícitos escritos para "fazer a consulta passar", em camadas que declaram o tipo do parâmetro e em serviços de outras linguagens que acessam a mesma tabela. O sintoma no EXPLAIN é sempre o mesmo: um cast aplicado sobre a coluna dentro de Filter, em vez de Index Cond.

06

Encontrar os índices que existem mas não trabalham

Índices parciais e de expressão quebram em silêncio, então vale procurar por eles de propósito. A consulta abaixo lista apenas os índices com predicado ou expressão, ordenados pelos menos usados. Um idx_scan parado, ou um last_idx_scan antigo, num índice que foi criado para uma consulta frequente é o sinal de que a consulta mudou e o índice ficou para trás.

SELECT s.relname                                   AS tabela,
       s.indexrelname                              AS indice,
       s.idx_scan,
       s.last_idx_scan,                            -- PostgreSQL 16+
       pg_size_pretty(pg_relation_size(s.indexrelid)) AS tamanho,
       pg_get_indexdef(s.indexrelid)               AS definicao
  FROM pg_stat_user_indexes s
  JOIN pg_index i ON i.indexrelid = s.indexrelid
 WHERE i.indpred IS NOT NULL      -- parcial
    OR i.indexprs IS NOT NULL     -- de expressão
 ORDER BY s.idx_scan, pg_relation_size(s.indexrelid) DESC;
  1. Para cada índice suspeito, encontre no pg_stat_statements a consulta que deveria usá-lo, pelo texto ou pela tabela.
  2. Rode EXPLAIN com valores reais e procure Filter onde deveria haver Index Cond, ou Seq Scan onde deveria aparecer o índice.
  3. Compare o WHERE com pg_get_indexdef: valor fora do predicado, parâmetro no lugar do literal, now() na faixa, expressão ou cast diferente.
  4. Se o índice não serve para nenhuma consulta atual, remova com DROP INDEX CONCURRENTLY depois de conferir nas réplicas, porque as estatísticas de uso são por servidor.

07

Corrigir e impedir que volte: literal no SQL e teste de plano

A correção do incidente teve duas partes. No banco, o índice novo com o predicado que a consulta realmente usa. Na aplicação, um teste de contrato que roda no CI contra um banco com o mesmo esquema e quebra se a consulta deixar de poder usar o índice esperado. O teste desliga o seq scan só dentro da transação: o objetivo não é medir custo, que numa base de teste pequena sempre favorece a varredura, e sim garantir que o índice continua elegível.

// fila-repositorio.js
import pg from 'pg';

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

// Os estados cobertos pelo predicado do índice ficam como literal no SQL, nunca como $1.
// São constantes do código, não entrada do usuário: não há risco de injeção.
export const SQL_RESERVAR_TAREFAS = `
  SELECT id, tipo, payload
    FROM tarefas
   WHERE status IN ('pendente', 'reprocessar')
     AND agendada_para <= now()
   ORDER BY agendada_para
   LIMIT $1
     FOR UPDATE SKIP LOCKED`;

export async function reservarTarefas(client, limite = 50) {
  const { rows } = await client.query(SQL_RESERVAR_TAREFAS, [limite]);
  return rows;
}

// Lista os índices que o plano da consulta usa, com os parâmetros reais.
// enable_seqscan = off mede elegibilidade, não custo: numa base de teste pequena o seq scan venceria.
export async function indicesDoPlano(client, sql, params = []) {
  await client.query('BEGIN');
  try {
    await client.query('SET LOCAL enable_seqscan = off');
    const { rows } = await client.query(`EXPLAIN (FORMAT JSON) ${sql}`, params);
    const indices = new Set();
    const visitar = (no) => {
      if (no['Index Name']) indices.add(no['Index Name']);
      (no.Plans || []).forEach(visitar);
    };
    visitar(rows[0]['QUERY PLAN'][0].Plan);
    return [...indices];
  } finally {
    await client.query('ROLLBACK');
  }
}

// fila-repositorio.test.js
import { test, after } from 'node:test';
import assert from 'node:assert/strict';
import { pool, SQL_RESERVAR_TAREFAS, indicesDoPlano } from './fila-repositorio.js';

after(() => pool.end());

// Teste de contrato: quebra no CI se a consulta deixar de poder usar o índice parcial.
test('reserva de tarefas usa tarefas_a_processar_idx', async () => {
  const client = await pool.connect();
  try {
    const indices = await indicesDoPlano(client, SQL_RESERVAR_TAREFAS, [50]);
    assert.ok(
      indices.includes('tarefas_a_processar_idx'),
      `plano usou: ${indices.join(', ') || 'nenhum índice'}`,
    );
  } finally {
    client.release();
  }
});
  • Crie o índice novo antes do deploy que muda a consulta, nunca depois. CREATE INDEX CONCURRENTLY não bloqueia escrita, mas leva tempo numa tabela grande.
  • Trate o predicado do índice e o WHERE da consulta como um contrato: quem muda um precisa mudar o outro no mesmo pull request.
  • Prefira predicados com lista explícita, status IN ('pendente', 'reprocessar'), a negações como status <> 'concluida', que incluem qualquer estado novo e fazem o índice crescer sem ninguém perceber.
  • Mantenha o auto_explain registrando planos acima de algumas centenas de milissegundos nas consultas da fila: a troca de Index Scan por Seq Scan aparece no log antes de virar incidente.

Com o índice tarefas_a_processar_idx no lugar, a reserva voltou a 0,5 ms, o índice ficou em 15 MB e a fila de 180 mil tarefas foi drenada em onze minutos pelos quatro workers originais. Duas semanas depois, o teste de plano pegou um pull request que adicionava o estado 'agendada_manual' ao IN sem mexer no índice.

FAQ

Perguntas frequentes

Por que o Postgres não usa o índice parcial se todas as linhas que eu quero estão nele?

Porque ele precisa provar isso no planejamento, só com o texto da consulta e o predicado do índice, sem olhar os dados. Se o WHERE não implica o predicado por regras que o planejador conhece, como valores constantes contidos na lista ou faixas contidas na faixa do índice, o índice é descartado. Usar um índice parcial sem essa prova poderia devolver um resultado incompleto, e o Postgres prefere ser lento a ser errado.

Posso usar now() ou current_date no predicado de um índice parcial?

Não. Funções em predicados e expressões de índice precisam ser IMMUTABLE, e now() muda a cada transação. A alternativa é um predicado com data fixa, como agendada_para > '2026-01-01', recriado periodicamente, ou um predicado sobre estado em vez de tempo. E mesmo com predicado fixo, uma consulta com agendada_para > now() - interval '1 day' não prova a implicação, porque now() não é constante no planejamento: a consulta precisa repetir a condição do índice de forma literal para usá-lo.

Como saber se o problema é o predicado, a expressão ou o tipo do parâmetro?

O EXPLAIN com os valores reais mostra. Se a condição aparece em Filter com um cast sobre a coluna, como (id)::numeric, o problema é tipo. Se a expressão aparece em Filter escrita de um jeito diferente da do índice, é expressão. Se o índice parcial simplesmente não aparece e a condição está correta, compare o WHERE com o pg_get_indexdef do índice: quase sempre há um valor fora do predicado, um parâmetro ou um now() onde o índice espera um literal.

O índice certo só funciona com a consulta que casa com ele

Índices parciais e de expressão economizam espaço, escrita e memória, mas dependem de uma prova feita no planejamento: o WHERE precisa implicar o predicado, a expressão precisa ser a mesma e o tipo do valor não pode forçar um cast na coluna. Um valor a mais no IN, um parâmetro no lugar do literal ou um cast diferente quebram essa prova sem erro e sem aviso, e a consulta volta a varrer a tabela inteira. Tratar índice e consulta como um contrato, auditar os índices que pararam de ser usados e travar o plano com um teste no CI evita que isso apareça como incidente. Se o seu sistema tem consultas que ficaram lentas depois de mudanças pequenas, ou índices que existem mas não aparecem nos planos, eu posso revisar o esquema, as consultas e a estratégia de indexação.