Franck PachotDatabase Developer Advocate
All minibooks
Database field guide · 25
Embeddings, ANN indexes, filters, and hybrid retrieval
Build and evaluate semantic retrieval with vector representations, approximate indexes, metadata filtering, and full-text hybrid ranking.
Build the mental model before choosing the mechanism.
This minibook was AI-generated from Franck Pachot's archived blog posts. Links to the original articles are included for source context and verification.01
An embedding model maps content into fixed-length vectors where a distance function approximates semantic similarity. Query and corpus vectors must share the same model and normalization contract.
02
Brute-force distance over every eligible vector provides a correctness reference. Approximate nearest-neighbor indexes reduce latency by exploring only a promising subset.
03
Graph and partition-based indexes tune search breadth, construction effort, memory, and recall. Higher search effort usually improves quality while increasing latency.
04
Metadata predicates can run before, during, or after ANN traversal. Post-filtering may return fewer than k rows and reduce recall when many visited candidates are ineligible.
05
Full-text ranking captures lexical precision while vector similarity captures semantic proximity. Hybrid retrieval normalizes and fuses ranks rather than pretending both scores share one scale.
06
Latency and throughput cannot establish retrieval quality. A representative query set with expected relevant documents supports recall, precision, ranking, and regression measurements.
07
Concrete mechanics, diagnostic evidence, and executable patterns to carry into a real system.
Keep a representative query set and compute exact nearest neighbors before tuning ANN. The baseline lets recall changes be measured rather than inferred from plausible-looking results.
SELECT id, embedding <=> $1 AS cosine_distance
FROM article
WHERE tenant_id = $2
ORDER BY embedding <=> $1
LIMIT 10;
-- Run without an ANN path for the labeled evaluation sample.Recall compares relevant exact neighbors recovered by ANN. Report its distribution across queries and filters alongside latency percentiles.
recall_at_k = len(set(exact_top_k) & set(ann_top_k)) / k
# Report mean, p5, and worst cohorts by filter selectivity.A selective predicate can starve post-filtered ANN results. Compare returned row count and recall while increasing traversal effort or using an index that incorporates filtering.
SET LOCAL hnsw.ef_search = 100;
SELECT id FROM article
WHERE category = $1
ORDER BY embedding <=> $2
LIMIT 20;
-- Sweep ef_search and category selectivity; record recall and latency.Reciprocal-rank fusion combines independent ranked lists without assuming text and vector scores have comparable scales.
rrf_score = 1 / (60 + text_rank) + 1 / (60 + vector_rank)
# Union candidate IDs, assign missing ranks no contribution,
# sort by rrf_score, and retain both ranks for diagnosis.08
Optional deep dives with the complete experiments and product-version context behind this guide.