Ir para o conteúdo
Promovaweb

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
  1. Três origens para um recurso
  2. JSONB: documentos dentro da tabela
  3. UUID e o uuidv7 do PostgreSQL 18
  4. pgvector: busca por similaridade

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.
De onde vem cada recurso desta página num banco PostgreSQL 18. Os tipos do núcleo existem em todo banco. Os módulos contrib e as extensões externas entram com CREATE EXTENSION. As externas exigem a instalação dos arquivos no servidor antes.

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.

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.