Ir para o conteúdo
Promovaweb

Índices e planos de consulta

Sem índice, uma busca por e-mail percorre todas as linhas da tabela de clientes para achar um único valor. O índice é a estrutura auxiliar que localiza esse valor sem a varredura completa. O planejador estima o custo dos caminhos disponíveis e pode usar o índice para reduzir as páginas lidas, escolha que você vê com EXPLAIN.

Ficha e sumário da página

Referência técnica
PostgreSQL 18.7
Revisão
13 de novembro de 2026
Conteúdo
Documentação oficial consultada
  1. O caminho de uma consulta
  2. O que o EXPLAIN mostra
  3. Quando o planejador ignora o índice
  4. Os seis tipos de índice
  5. O custo de cada índice
  6. Índices sob medida para a consulta

O caminho de uma consulta

Toda consulta passa por quatro etapas dentro do processo backend antes de devolver linhas ao app. A documentação descreve esse caminho na seção sobre a vida de uma consulta:

  1. Parser

    SELECT ... WHERE

    Confere a sintaxe do SQL e monta a árvore da consulta.

  2. Reescrita

    CREATE VIEW

    Troca uma view pela consulta às tabelas que ela representa.

  3. Planejador

    EXPLAIN

    Monta os caminhos possíveis, estima o custo de cada um e escolhe o menor.

  4. Executor

    Index Scan

    Percorre o plano, lê as páginas, ordena, junta e devolve as linhas.

As quatro etapas de uma consulta no servidor, segundo a seção The Path of a Query da documentação. O índice entra na terceira etapa, como um dos caminhos que o planejador compara.

O planejador escolhe a forma de executar a consulta a partir dos caminhos que considera. Para uma tabela com índice na coluna filtrada, ele considera ao menos dois caminhos: a leitura sequencial da tabela inteira e a busca pelo índice. Cada caminho recebe um custo estimado, calculado a partir das estatísticas da tabela. O executor recebe o caminho de menor custo.

O que o EXPLAIN mostra

O comando EXPLAIN antes de uma consulta devolve o plano escolhido, sem executar a consulta. A documentação usa uma tabela de teste chamada tenk1, com dez mil linhas, para mostrar a diferença. Sem filtro, o plano lê tudo:

EXPLAIN SELECT * FROM tenk1;
Seq Scan on tenk1 (cost=0.00..445.00 rows=10000 width=244)

Com um filtro de igualdade na coluna unique1, que tem índice, o plano muda:

EXPLAIN SELECT * FROM tenk1 WHERE unique1 = 42;
Index Scan using tenk1_unique1 on tenk1 (cost=0.29..8.30 rows=1 width=244)
Index Cond: (unique1 = 42)

Cada linha do plano é um nó. O par cost=0.29..8.30 traz o custo para devolver a primeira linha e o custo total, numa unidade arbitrária: por convenção, ler uma página da tabela em sequência vale 1,0. O rows=1 é a estimativa de linhas devolvidas e o width=244 é o tamanho médio estimado de cada linha em bytes. Os exemplos têm filtros diferentes, por isso a comparação dos custos não mede o ganho de adicionar um índice à mesma consulta.

Os números do EXPLAIN são estimativas. O EXPLAIN ANALYZE executa a consulta de verdade e mostra, ao lado da estimativa, as linhas reais e o tempo gasto em cada nó. Por isso ele também grava: um EXPLAIN ANALYZE de um DELETE apaga as linhas, a menos que rode dentro de uma transação desfeita com ROLLBACK.

Quando o planejador ignora o índice

A presença de um índice não obriga o planejador a usá-lo. Com o filtro unique1 < 7000, a mesma tabela volta ao Seq Scan, porque 70% das linhas atendem a condição. Buscar cada linha pelo índice custaria mais caro que ler as páginas da tabela em sequência. Com unique1 < 100, o plano usa o índice num Bitmap Index Scan e depois lê só as páginas marcadas, um caminho intermediário para filtros que devolvem cerca de cem linhas.

A estimativa depende de estatísticas sobre a distribuição dos valores, guardadas pelo comando ANALYZE. O daemon de autovacuum atualiza essas estatísticas sozinho na maioria das instalações. Depois de uma carga grande, como uma importação de milhões de linhas, as estatísticas ficam velhas até a próxima passagem. Nesse intervalo, o planejador pode escolher um caminho ruim. Um ANALYZE manual na tabela resolve.

Os seis tipos de índice

O PostgreSQL traz seis tipos de índice no servidor, além da extensão bloom. Cada tipo usa um algoritmo diferente. O comando CREATE INDEX sem USING cria um B-tree, o tipo que atende a maior parte das colunas de um app:

  • B-treeIgualdade e faixas em valores ordenáveis, além de ORDER BY. É o padrão do CREATE INDEX.
  • HashSó igualdade, com um código de hash de 32 bits por valor.
  • GiSTEstrutura genérica para geometria, intervalos e busca do vizinho mais próximo.
  • SP-GiSTÁrvores particionadas, como quadtrees, para valores que não se distribuem por igual.
  • GINÍndice invertido para valores com vários componentes, como arrays, jsonb e texto pesquisável.
  • BRINResumo por faixa de blocos, pequeno, para colunas correlacionadas com a ordem física, como datas de log.

O tipo certo depende do operador da consulta. Um B-tree em email atende WHERE email = ... e ORDER BY email. Ele não serve para o operador @> de uma coluna jsonb, que usa um GIN. Numa tabela de eventos com datas próximas da ordem física das linhas, um BRIN pode ocupar menos espaço porque resume intervalos de páginas. O tamanho e o desempenho dependem da tabela e da configuração do índice.

O custo de cada índice

A documentação descreve o índice como algo que o sistema mantém sozinho depois de criado. Essa manutenção tem preço: cada INSERT precisa manter os índices aplicáveis à linha, inclusive a condição de cada índice parcial. Alterar uma coluna indexada também exige manutenção. Índices pouco lidos merecem análise, mas alguns verificam a unicidade dos valores ou atendem consultas raras que continuam necessárias. A visão pg_stat_user_indexes mostra quantas vezes cada um foi lido.

Índices sob medida para a consulta

Um índice pode cobrir mais de uma coluna. O índice em (cliente_id, criada_em) atende a consulta que filtra as compras de um cliente e ordena pela data, porque o B-tree guarda as entradas agrupadas pelo cliente e, dentro de cada cliente, pela data. A ordem das colunas pesa: numa consulta que filtra só pela data, o planejador costuma preferir outro caminho, porque as datas ficam espalhadas entre todos os clientes dentro do índice. O PostgreSQL 18 ampliou esse uso com o skip scan, citado nas notas da versão, que aproveita índices de várias colunas em mais casos.

O índice parcial guarda só as linhas que atendem uma condição declarada no próprio índice. Com CREATE INDEX ... WHERE ativa, apenas as assinaturas ativas entram na estrutura, que fica menor que o índice da tabela inteira e atende as consultas que repetem a mesma condição. O planejador só usa esse índice quando a consulta deixa claro que procura linhas dentro da condição.

O índice sobre expressão guarda o resultado de uma função em vez do valor bruto da coluna. Uma busca por e-mail sem diferenciar maiúsculas, escrita como WHERE lower(email) = ..., não aproveita o índice comum da coluna email, porque o valor comparado é outro. Um índice em lower(email) resolve esse caso, ao custo de calcular a função a cada gravação.

Os tipos jsonb e vector seguem a mesma lógica, com índices próprios para os operadores deles. O GIN atende as buscas dentro de documentos e os índices HNSW e IVFFlat da pgvector atendem a busca por similaridade, assunto da página Extensões: pgvector, JSONB e UUID.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.