pgvector-semantic-search

SKILL.md

pgvector for Semantic Search

Semantic search finds content by meaning rather than exact keywords. An embedding model converts text into high-dimensional vectors, where similar meanings map to nearby points. pgvector stores these vectors in PostgreSQL and uses approximate nearest neighbor (ANN) indexes to find the closest matches quickly—scaling to millions of rows without leaving the database. Store your text alongside its embedding, then query by converting your search text to a vector and returning the rows with the smallest distance.

This guide covers pgvector setup and tuning—not embedding model selection or text chunking, which significantly affect search quality. Requires pgvector 0.8.0+ for all features (halfvec, binary_quantize, iterative scan).

Golden Path (Default Setup)

Use this configuration unless you have a specific reason not to.

Embedding column data type: halfvec(N) where N is your embedding dimension (must match everywhere). Examples use 1536; replace with your dimension N.

Distance: cosine (<=>)

Index: HNSW (m = 16, ef_construction = 64). Use halfvec_cosine_ops and query with <=>.

Query-time recall: SET hnsw.ef_search = 100 (good starting point from published benchmarks, increase for higher recall at higher latency)

Query pattern: ORDER BY embedding <=> $1::halfvec(N) LIMIT k

This setup provides a strong speed–recall tradeoff for most text-embedding workloads.

Core Rules