Noções Básicas de Busca de Texto Completo

O PostgreSQL oferece busca de texto completo nativa com tsvector, tsquery e índices GIN. Para muitos produtos, ele substitui um cluster Elasticsearch separado quando o volume de dados, as necessidades de classificação e a equipe operacional favorecem um único banco de dados.

Receita

-- Tabela mínima de documentos pesquisáveis
CREATE TABLE articles (
  id          bigserial PRIMARY KEY,
  title       text NOT NULL,
  body        text NOT NULL,
  published   timestamptz DEFAULT now()
);
 
-- Coluna tsvector gerada (PostgreSQL 12+)
ALTER TABLE articles
  ADD COLUMN search_vector tsvector
  GENERATED ALWAYS AS (
    setweight(to_tsvector('english', coalesce(title, '')), 'A') ||
    setweight(to_tsvector('english', coalesce(body, '')), 'B')
  ) STORED;
 
CREATE INDEX articles_search_idx ON articles USING gin (search_vector);
 
-- Busca
SELECT id, title, ts_rank(search_vector, query) AS rank
FROM articles, plainto_tsquery('english', 'postgresql replication') query
WHERE search_vector @@ query
ORDER BY rank DESC
LIMIT 20;

Quando usar isso: Busca de texto completo sobre dados relacionais, tamanho de corpus moderado (milhões de linhas) e a equipe deseja consistência transacional sem escrita dupla para um mecanismo de busca.

Exemplo de Trabalho

INSERT INTO articles (title, body) VALUES
  ('Streaming Replication', 'Envio de WAL físico para standbys para HA.'),
  ('Logical Replication', 'Alterações em nível de linha para atualizações e fan-out.'),
  ('Full-Text Search', 'Classificação tsvector integrada com índices GIN.');
 
EXPLAIN (ANALYZE, BUFFERS)
SELECT id, title,
       ts_rank_cd(search_vector, query) AS rank,
       ts_headline('english', body, query,
         'MaxFragments=2, MaxWords=20, MinWords=8') AS snippet
FROM articles,
     websearch_to_tsquery('english', 'replication OR "full text"') query
WHERE search_vector @@ query
ORDER BY rank DESC;

O que isso demonstra:

• Campos com peso (A título, B corpo) influenciam a classificação
• websearch_to_tsquery aceita sintaxe de busca amigável ao usuário
• ts_headline constrói trechos de resultados em SQL
• EXPLAIN confirma o uso do índice GIN em @@

Mergulho Profundo

FTS Integrado vs Busca Externa

Padrão ADR: Comece com o FTS do Postgres quando o corpus couber em uma única instância, as consultas forem por palavra-chave + levemente imprecisas e a equipe não puder gerenciar o Elasticsearch.

Opte pelo OpenSearch quando: busca sub-100ms em grande escala, analisadores complexos por idioma, fragmentação pesada de autocompletar ou equipe SRE de busca dedicada.

Objetos Principais

• tsvector - Bolsa de léxemas normalizada com pesos/posições opcionais.
• tsquery - Expressão de busca analisada com operadores (&, |, !, <-> frase).
• Operador de correspondência @@ - Teste booleano de correspondência; o índice GIN o acelera.
• Dicionários - Stemming, palavras irrelevantes, sinônimos (veja o artigo tsvector).

Configuração de Idioma

SELECT cfgname FROM pg_ts_config;
-- comum: english, simple, french
SELECT to_tsvector('simple', 'Running runs RUN');
-- simple: sem stemming, bom para SKUs e códigos de produtos

Use simple para identificadores; use english (ou específico do local) para prosa.

Armadilhas

• Sem índice em to_tsvector() no WHERE - Expressão não armazenada significa varredura sequencial. Correção: Coluna gerada armazenada ou tsvector mantido por trigger.
• Consultas OR explodem os resultados - websearch_to_tsquery com muitos termos OR. Correção: Exigir limite mínimo de classificação ou padrões pesados em AND.
• Caixa e diacríticos - FTS normaliza a caixa; acentos dependem do dicionário. Correção: Extensão unaccent ou colação ICU para busca sensível ao local.
• Busca de subcadeia - FTS corresponde a léxemas, não LIKE '%foo%'. Correção: pg_trgm para subcadeia; combinar em consultas híbridas.
• Vetores desatualizados após carga em massa - Colunas geradas são atualizadas automaticamente; as baseadas em trigger podem não ser. Correção: Verificar o caminho de manutenção após ETL.
• Inveja do Elasticsearch - Recriar índice invertido para cada ajuste de esquema. Correção: Iterar a classificação em SQL antes de adotar um segundo sistema.

Alternativas

FAQs

Relacionados

• tsvector & tsquery - dicionários e classificação
• Índices GIN para FTS - construção e manutenção de índices
• Busca Híbrida - combine com pgvector
• GIN e GiST - visão geral do método de acesso
• Melhores Práticas de Busca de Texto Completo - checklist operacional

Versões da pilha: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PostGIS 3.5+, pgbouncer 1.x e Patroni 3.x.