pgvector: vectores dentro de Postgres

Aparece RAG y el reflejo es montar una base vectorial dedicada: un segundo servicio, una segunda credencial, otra historia de backup que mantener y un job de sincronización para tenerla al día con tus datos reales. Para la mayoría de las apps, eso es un problema que compraste antes de necesitarlo. pgvector apuesta justo al revés: hace que el mismo Postgres que ya tienes corriendo también guarde y busque vectores, así los embeddings quedan en la misma tabla que las filas que describen. Sales de aquí sabiendo exactamente cuándo vale la pena esa apuesta, cómo dejarlo listo en el stack que de verdad uso (Supabase) y los dos o tres errores de índice que, sin avisar, se llevan toda la velocidad que viniste a buscar.

01 · Qué es

pgvector es una extensión de Postgres. Agrega un tipo de columna vector y una pequeña familia de operadores de distancia, más dos tipos de índice de vecino más cercano aproximado (ANN): HNSW e IVFFlat. Eso es todo lo que hay: ni un servidor aparte ni un protocolo aparte. Le hablas en SQL, dentro de la misma conexión y la misma transacción que todo lo demás en tu base.

Una vez habilitada la extensión, declaras una columna con una dimensión fija («vector(1536)» para un vector de «text-embedding-3-small» de OpenAI, «vector(1024)» para uno de Cohere) y guardas los embeddings como valores de columna normales. La similitud se convierte en un «ORDER BY» sobre un operador de distancia. Tres operadores cubren los casos comunes:

• «<=>»: distancia coseno. El default para la mayoría de embeddings de texto, que suelen venir normalizados.
• «<->»: distancia L2 (euclidiana).
• «<#>»: producto interno negativo.

En Supabase la extensión ya viene empaquetada, así que habilitarla es de verdad una sola sentencia. En un Postgres self-hosted instalas primero el binario de la extensión (un paquete o un paso de build) y luego la habilitas en cada base.

create extension if not exists vector;

alter table docs add column embedding vector(1536);

-- construye el índice DESPUÉS de cargar las filas en masa (ver sección 04)
create index on docs using hnsw (embedding vector_cosine_ops);

02 · Por qué importa

El argumento a favor de pgvector no es que sea la búsqueda vectorial más rápida del planeta: no lo es, y un motor dedicado bien afinado le gana en los extremos. El argumento es la colocación, y la colocación te da cosas que de verdad cuesta lograr de otra forma.

Cuando tus embeddings viven en la misma tabla que las filas que describen, una búsqueda semántica filtrada es una sola consulta:

select id, content
from docs
where tenant_id = 42
  and status = 'published'
  and lang = 'es'
order by embedding <=> :query_vec
limit 5;

Intenta hacer eso mismo contra un almacén vectorial aparte y de una vez heredas los problemas difíciles de los sistemas distribuidos. O denormalizas «tenant_id», «status» y «lang» en la metadata del almacén vectorial y los mantienes en sync en cada escritura (un job de sincronización que tarde o temprano se va a desfasar), o traes un conjunto amplio de candidatos del almacén vectorial y los filtras después en tu app, lo que bota resultados y rompe tu «limit». Con pgvector el planner lo resuelve de forma nativa, y tu row-level security, tus foreign keys y tus transacciones siguen aplicando igual. Borras un documento y su embedding se va en la misma sentencia.

Hay además un tema de honestidad que me importa: buena parte de la adopción de bases vectoriales se hace por adelantado. Los equipos aprovisionan para una escala que no tienen ni van a tener en un año, y mientras tanto pagan esa complejidad todos los días. Empezar en Postgres te deja posponer esa decisión hasta tener números reales, y "lo medí y pgvector no daba abasto" es una razón mucho mejor para migrar que "supuse que no iba a aguantar".

03 · Cuándo usarlo (y cuándo no)

pgvector es el default correcto en una franja amplia, y una mala elección clara fuera de ella. Sé honesto contigo mismo sobre de qué lado estás.

Tira de pgvector cuando

• Estás en el rango de unos pocos millones de vectores. Con HNSW y hardware razonable, el recall y la latencia se mantienen bien hasta bien entrados los pocos millones.
• Tu recuperación es pesada en filtros: multi-tenant, por estado, por idioma, por fecha. Este es el terreno de pgvector, porque el filtro y la búsqueda comparten el mismo planner.
• Ya estás en Postgres o Supabase y quieres lanzar recuperación hoy sin tener que operar un sistema nuevo.
• Tu ruta de escritura necesita que el embedding y la fila aterricen de forma atómica: consistencia transaccional entre el dato y su vector.

Busca otra cosa cuando

• Ya pasaste de las decenas de millones de vectores, o vas para allá rápido. Un motor dedicado (Qdrant, entre otros) con cuantización y un layout de índice pensado para la memoria va a aprovechar la RAM mucho mejor a esa escala.
• Necesitas un QPS muy alto con metas estrictas de latencia de cola que un Postgres compartido (que además sirve tu tráfico OLTP) no puede cumplir sin pelearse por los recursos.
• Necesitas funciones vectoriales nativas que pgvector no tiene: una interacción sofisticada entre índice y payload, cuantización binaria nativa con rescoring, o sharding diseñado para miles de millones de puntos.

04 · Quickstart: una tabla de recuperación que funciona

Acá va un montaje mínimo pero ya con forma de producción: una tabla con alcance por tenant, una columna de embedding, un índice HNSW y una consulta de recuperación que filtra y ordena en una sola pasada.

create extension if not exists vector;

create table docs (
  id          bigint generated always as identity primary key,
  tenant_id   bigint not null,
  status      text   not null default 'draft',
  content     text   not null,
  embedding   vector(1536)
);

-- 1. Carga PRIMERO tus filas y embeddings en masa.
-- 2. LUEGO construye el índice. Un HNSW sobre una tabla vacía, llenado
--    de a poco, es más lento de construir y da un grafo peor que uno
--    construido en masa.
create index docs_embedding_idx
  on docs using hnsw (embedding vector_cosine_ops);

-- Un índice btree de apoyo abarata el filtro por metadatos.
create index docs_tenant_status_idx on docs (tenant_id, status);

La consulta de recuperación, con un control para ajustar el esfuerzo de la búsqueda y un filtro razonable:

set hnsw.ef_search = 100;  -- más alto = mejor recall, consulta más lenta

select id, content,
       embedding <=> :query_vec as distance
from docs
where tenant_id = :tenant
  and status = 'published'
order by embedding <=> :query_vec
limit 5;

Algunas cosas que vale la pena que se te queden grabadas:

1. Construye el índice después de la carga masiva. Insertar en un HNSW que ya existe está bien para las escrituras del día a día, pero el grafo inicial sale notablemente mejor y se construye más rápido cuando pgvector ve todas las filas de una sola vez.
2. «ef_search» es tu control de calidad contra velocidad en tiempo de consulta. No cuesta nada cambiarlo por sesión, así que puedes probar varios valores contra un set etiquetado y quedarte con el más bajo que llegue a tu meta de recall.
3. Mantén un índice btree en las columnas por las que filtras. El planner lo puede combinar con la búsqueda vectorial; sin él, tu filtro termina degradándose a un escaneo.

05 · El detalle que mata tu rendimiento en silencio

Este es el que le cuesta a la gente latencia real sin un solo error que apunte al problema: el operador de distancia de tu consulta tiene que coincidir con la opclass con la que se construyó el índice. No son intercambiables, y un desajuste no falla a gritos: simplemente deja de usar el índice.

Un índice HNSW creado con «vector_cosine_ops» solo acelera el operador coseno «<=>». Si lo construyes para coseno y luego consultas con «<->» (L2) o «<#>» (producto interno), Postgres no puede usar ese índice para el ordenamiento, así que se va a un escaneo secuencial sobre cada fila. En una tabla chica ni lo notas. En unos cientos de miles de filas, tu búsqueda semántica "rápida" se vuelve de golpe un escaneo completo de tabla en cada request, y el único síntoma es que va lenta.

El arreglo es un hábito de treinta segundos: comprueba que el índice realmente se está usando.

explain analyze
select id from docs
order by embedding <=> :query_vec
limit 5;
-- Busca un "Index Scan using docs_embedding_idx".
-- Un "Seq Scan" aquí significa que el operador/opclass no coinciden,
-- o que el planner cree que un escaneo es más barato (a menudo: índice
-- sin construir, o estadísticas viejas — corre ANALYZE).

Dos trampas relacionadas de la misma familia:

• Construye el índice para el operador con el que de verdad vas a consultar. Si tus embeddings están normalizados, coseno y producto interno ordenan igual, pero aun así tienes que construir el índice para el operador que usa tu consulta. Decídelo una vez y constrúyelo acorde.
• Un filtro demasiado selectivo puede hacer que un escaneo sea de verdad más barato, y el planner va a elegirlo con razón. Eso no es un bug, pero si esperabas el índice ANN y no lo obtuviste, EXPLAIN te dice por qué en lugar de dejarte adivinando.

En cada proyecto de Supabase que armo arranco con pgvector, incluyendo las rutas de recuperación de mi propio trabajo; no porque sea la opción más potente, sino porque es la que puedo razonar, respaldar y asegurar con la misma base de datos que ya tengo corriendo. El día que un benchmark con datos reales diga que no alcanza, esa sí es una razón limpia y con evidencia para graduarte a un motor dedicado. Hasta entonces, la opción aburrida mantiene el sistema chico, y los sistemas chicos son justo los que siguen siendo fáciles de debuggear.