Extensões: pgvector, JSONB e UUID
Uma extensão é um pacote de objetos SQL, como tipos e funções, registrado num banco pelo comando CREATE EXTENSION. Com a pgvector instalada no servidor, você acrescenta vetores às tabelas e consulta a similaridade entre embeddings pelo próprio SQL.
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
Três origens para um recurso
Os recursos que um app moderno usa no PostgreSQL chegam por caminhos diferentes. Essa origem muda o que você precisa instalar no servidor. Alguns tipos e funções fazem parte do núcleo e existem em qualquer banco, como o jsonb, o uuid e a função uuidv7(), que chegou no PostgreSQL 18. Outros vêm nos módulos contrib, distribuídos junto com o servidor e ligados banco a banco com CREATE EXTENSION. Um terceiro grupo vem de projetos externos, instalados à parte no servidor antes do CREATE EXTENSION funcionar.
banco lojaCada banco tem a própria lista de extensões instaladas.núcleo do servidorDisponível em todo banco, sem instalação.jsonbDocumentos JSON em formato binário, com operadores e índice GIN.uuidv7()Gera UUIDs ordenados pelo tempo, função nova no PostgreSQL 18.contribDistribuído com o servidor, ligado com CREATE EXTENSION.uuid-osspAlgoritmos extras de UUID, como as versões 1, 3 e 5.projeto externoInstalado à parte, depois ligado com CREATE EXTENSION.vectorA pgvector 0.8.7: tipo vector, operadores de distância e índices HNSW e IVFFlat.
A extensão fica registrada no banco. O pg_dump grava só o comando CREATE EXTENSION, sem copiar cada função. Na restauração, o servidor de destino recria tudo a partir dos próprios arquivos da extensão. Por isso a restauração de um banco com pgvector falha num servidor que não tem a pgvector instalada.
JSONB: documentos dentro da tabela
O PostgreSQL oferece dois tipos para JSON. O json guarda uma cópia exata do texto recebido, com espaços, ordem das chaves e chaves repetidas. As funções precisam interpretar esse texto a cada execução. O jsonb decompõe o documento num formato binário na gravação. A entrada fica um pouco mais lenta, segundo a documentação, mas o processamento fica bem mais rápido porque não há nova interpretação. O jsonb descarta espaços, não preserva a ordem das chaves e mantém só o último valor de uma chave repetida.
A documentação recomenda o jsonb para a maioria dos apps. Ele aparece em colunas de metadados, em configurações por cliente e em respostas de APIs externas guardadas para consulta. A coluna convive com as colunas tipadas da mesma tabela, de modo que o identificador, a data e o valor seguem com tipo próprio, enquanto o restante do payload vai para o jsonb.
O operador @> responde se um documento contém outro, como metadados @> '{"plano": "pro"}'. Um índice GIN na coluna atende esse operador e os operadores de existência de chave. Com a classe jsonb_path_ops, o índice fica menor e mais rápido para @>, ao custo de não atender os operadores de existência de chave.
UUID e o uuidv7 do PostgreSQL 18
O tipo uuid guarda identificadores de 128 bits, gravados em 16 bytes. A função gen_random_uuid(), presente no núcleo, gera a versão 4, totalmente aleatória. O PostgreSQL 18 acrescentou o uuidv4(), nome explícito para a mesma versão. Acrescentou também o uuidv7(), que começa com um carimbo de tempo em milissegundos, uma fração submilissegundo e bits aleatórios. As notas da versão 18 descrevem o uuidv7 como ordenável no tempo.
A ordem pesa no índice da chave primária. Valores aleatórios caem em pontos espalhados do B-tree, por isso inserções seguidas gravam em páginas diferentes do índice. Valores de uuidv7 gerados em instantes próximos tendem a ocupar regiões próximas do índice, embora a ordem entre servidores dependa dos relógios e da implementação geradora. A troca é que o identificador revela o instante aproximado da criação do registro, um detalhe a considerar quando o uuid aparece numa URL pública. O módulo contrib uuid-ossp continua disponível para os outros algoritmos, como as versões 1, 3 e 5.
pgvector: busca por similaridade
A pgvector é uma extensão de código aberto para busca de vetores por similaridade no PostgreSQL. Ela é mantida fora do projeto principal e funciona do PostgreSQL 13 em diante. A versão de referência desta página é a 0.8.7. Ela acrescenta o tipo vector, que guarda embeddings gerados por modelos de IA, ao lado das outras colunas da tabela. Uma tabela de documentos guarda o texto, o autor e o embedding na mesma linha. Com isso, uma única consulta filtra pelo autor e ordena pela distância até o embedding da pergunta.
O operador <-> calcula a distância euclidiana, o <=> calcula a distância de cosseno, o <#> devolve o produto interno negativo e o <+> calcula a distância L1. A consulta típica ordena por um desses operadores e limita o resultado, como ORDER BY embedding <=> $1 LIMIT 5, o formato das buscas de trechos relevantes em apps com geração aumentada por recuperação (RAG).
Sem índice, a pgvector faz busca exata: compara a pergunta com cada vetor da tabela. A busca encontra os vizinhos exatos segundo a métrica escolhida, mas isso não garante a relevância semântica dos textos. O tempo da consulta cresce junto com a tabela. Os índices HNSW e IVFFlat trocam parte da precisão por velocidade, numa busca aproximada. Segundo o README do projeto, o HNSW responde melhor que o IVFFlat na troca entre velocidade e precisão. Em compensação, ele demora mais para construir e ocupa mais memória. Com um índice aproximado, a mesma consulta pode devolver resultados diferentes dos da busca exata.
A pgvector não vem na imagem oficial do PostgreSQL no Docker. O projeto publica imagens próprias com a extensão, como pgvector/pgvector:pg18-trixie. Também publica instruções de instalação por pacote nas distribuições Linux. O próximo assunto mostra como o PostgreSQL mantém tudo isso consistente quando várias conexões gravam ao mesmo tempo, na página Transações e concorrência.