Enable pgvector extension
La extensión pgvector añade el vector data type y similarity search operators a PostgreSQL. Antes de poder usar embeddings, hay que activar pgvector en la BBDD
comando para activar pgvector
CREATE EXTENSION IF NOT EXISTS vector;
verificar que se ha instalado
SELECT * FROM pg_extension WHERE extname = 'vector'
Design schemas for vector storage
Un buen diseño combina embeddings con los metadatos de la app necesarios para filtrar y mostrar.
Cuando defines una columna de vector, tienes que especificar el número de dimensiones
vector(n)
ejemplo de creación que guarda el embedding en la misma tabla que los metadatos
CREATE TABLE documents (
id SERIAL PRIMARY KEY,
title TEXT NOT NULL,
content TEXT,
category TEXT,
practice_area TEXT,
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW(),
embedding vector(1536)
);
si tenemos múltiples embeddings (titulo vs contenido) podemos guardarlos en la misma tabla
CREATE TABLE documents (
id SERIAL PRIMARY KEY,
title TEXT NOT NULL,
content TEXT,
title_embedding vector(384),
content_embedding vector(1536)
);
Insert and update embeddings
Para apps con cambios frecuentes quizás es mejor regenerar los embeddings en batches durante off-peak hours y no actualizarlos en tiempo real.
ejemplo de single insert vectores
INSERT INTO documents (title, content, category, practice_area, embedding)
VALUES (
'Corporate Merger Agreement Template',
'This agreement outlines the terms and conditions for the merger of...',
'contracts',
'corporate',
'[0.0123, -0.0456, 0.0789, -0.0321, ...]'::vector
);
ejemplo de batch insert vectores
INSERT INTO documents (title, content, category, embedding)
VALUES
('Document 1', 'Content...', 'legal', '[...]'::vector),
('Document 2', 'Content...', 'legal', '[...]'::vector),
('Document 3', 'Content...', 'legal', '[...]'::vector);
ejemplo de update con vectores
UPDATE documents
SET content = 'Updated document content...',
embedding = '[0.0234, -0.0567, ...]'::vector,
updated_at = NOW()
WHERE id = 42;
Query vectors with distance ops
pgvector provee de tres distance operators para medir similitud entre vectores. Cada uno calcula un tipo diferente.
L2 distance (Euclidean distance)
L2 distance (distancia euclideana) mide la línea recta entre dos vectores en el espacio vectorial. Es el operador <->. Cuando más pequeños los valores más similares son los vectores.
Funciona muy bien cuando la magnitud de los vectores conlleva significado.
SELECT id, title, embedding <-> '[0.0123, -0.0456, ...]'::vector AS distance
FROM documents
ORDER BY distance
LIMIT 10;
Cosine distance
Cosine distance mide el ángulo entre dos vectores, ignorando sus magnitudes. Es el operador <=>. Los valores van del rango 0 (dirección idéntica) a 2 (direcciones opuestas).
Cosine distance es la opción más común para text embeddings porque se centra en la dirección del significado y no en la longitud del vector.
SELECT id, title, embedding <=> '[0.0123, -0.0456, ...]'::vector AS distance
FROM documents
ORDER BY distance
LIMIT 10;
Negative inner product
Calcula el dot product de dos vectores y lo hace negativo. Es el operador <#>.
Negative inner product es útil para maximum inner product search, donde larger dot products indica vectores más similares. La negación lo convierte a una distancia donde valores más pequeños son mejores.
SELECT id, title, embedding <#> '[0.0123, -0.0456, ...]'::vector AS distance
FROM documents
ORDER BY distance
LIMIT 10;
Vector data types and precision
pgvector ofrece tres data types para guardar vectores, cada uno con un storage y performance diferente.
Para la mayoría de casos es mejor usar el standard
vectortype. Si necesitamos ahorrar espacio, y solo después de comprobar que la precisión es suficiente, podemos usarhalfvec
vector type
vector type almacena elementos como single-precision (32-bit) floats. Es el standard para la mayoría de casos y da buen balance de precisión y almacenamiento.
halfvec
halfvec type almacena elementos como half-precision (16-bit) flaots. Reduce el almacenamiento a la mitad comparado con vector, manteniendo suficiente precisión para al mayoría de similarity search tasks.
Usa halfvec cuando el almacenamiento sea un problema y hayas verificado que la precisión reducida no impacta tus búsquedas
CREATE TABLE documents_compact (
id SERIAL PRIMARY KEY,
title TEXT NOT NULL,
embedding halfvec(1536)
);
sparsevec
sparsevec type almacena sparse vectors donde la mayoría de elementos son cero. En vez de guardar todas las dimensiones, solo guarda los nonzero values y sus posiciones.
Este tipo es útil para modelos que producen sparse embeddings.
CREATE TABLE sparse_documents (
id SERIAL PRIMARY KEY,
title TEXT NOT NULL,
embedding sparsevec(10000)
);