Embeddings and Vector Search

#Context

// embed() calls whatever embedding model you use
const docs = ['Cancel your plan in Settings', 'Change your avatar']
const docVecs = await Promise.all(docs.map(d => embed(d)))

const q = await embed('stop subscription')
const scores = docVecs.map(v => cosine(q, v))
// [0.82, 0.11]  -> the first doc wins, with no shared words

Embedding / vector

The list of numbers a model outputs for one input, for example 768 or 1536 floats. All vectors from one model have the same length (dimension).

Similarity metric

How closeness is measured: cosine similarity (angle), dot product, or Euclidean distance.

kNN / exact search

k nearest neighbours: compare the query with every stored vector and keep the top k. Always correct, cost grows with N.

ANN index

A structure that finds most of the true nearest neighbours while only examining a small part of the data.

Recall@k

Of the true top k neighbours, the share the index actually returned. The quality metric for ANN.

#Why it matters

#Meaning as distance

Cosine, dot product, Euclidean

export function dot(a: number[], b: number[]): number {
  let s = 0
  for (let i = 0; i < a.length; i++) s += a[i] * b[i]
  return s
}

export function normalize(v: number[]): number[] {
  const len = Math.sqrt(dot(v, v))
  return v.map(x => x / len)
}

// cosine = dot of the normalised vectors; normalise once at write time
export const cosine = (a: number[], b: number[]) =>
  dot(normalize(a), normalize(b))

#Why exact search stops scaling, and how ANN indexes work

1. 1
   Memory first. 10 million vectors × 1,536 dimensions × 4 bytes per float32 = about 61 GB before any index overhead. Halving the dimension or quantizing halves or quarters that, which is often the deciding design choice.
2. 2
   HNSW (Hierarchical Navigable Small World). Each vector is a node in a graph linked to its close neighbours, with sparse upper layers for long jumps and a dense bottom layer. A search starts at the top, greedily walks towards the query, and drops a layer at a time. M (links per node) and ef_construction set build quality and memory; ef_search sets how many candidates a query explores, which is the recall-vs-latency dial.
3. 3
   IVF (inverted file index). Cluster the vectors into, say, 4,096 groups with k-means, and store each vector under its nearest centroid. A query compares itself with the centroids and scans only the closest nprobe groups. Cheaper to build and smaller than HNSW, but needs training data and degrades if the data drifts from the clusters.
4. 4
   PQ (product quantization) and friends. Compress each vector by splitting it into chunks and replacing each chunk with the ID of its nearest code word. Distances are computed on the codes, cutting memory many times over at some cost in accuracy; int8 and binary quantization are simpler versions of the same trade.
5. 5
   Measure recall@k. Run a sample of queries through exact search and through the index, and compare the top-k sets. Tune ef_search or nprobe until recall is where the product needs it, typically 0.95 or higher, then check latency.

#Where vectors live and how filters break them

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE chunks (
  id        bigserial PRIMARY KEY,
  doc_id    bigint NOT NULL,
  tenant_id bigint NOT NULL,
  content   text NOT NULL,
  embedding vector(1536) NOT NULL   -- must match the model's dimension
);

-- HNSW index for cosine distance (pgvector 0.5.0+)
CREATE INDEX ON chunks USING hnsw (embedding vector_cosine_ops);

-- <=> is cosine distance: smaller = more similar
SET hnsw.ef_search = 100;           -- recall vs latency for this session
SELECT id, content
FROM chunks
WHERE tenant_id = $2
ORDER BY embedding <=> $1
LIMIT 10;

Model changes mean re-embedding

#Pitfalls

• Mixing models between indexing and querying

  Embedding documents with one model and queries with another produces vectors in incompatible spaces, so the nearest neighbours are close to random while scores still look normal. Pin the model version, store it with the vectors and re-embed everything when it changes.

• Expecting embeddings to match exact tokens

  Semantic similarity blurs exactly what keyword search is good at: order IDs, error codes, SKUs, rare names, and often negation ("not refundable" lands near "refundable"). Combine vector search with keyword search (hybrid retrieval) for queries that contain identifiers.

• Post-filtering a selective filter

  When the index searches first and filters later, a narrow filter (one tenant, one date range) can eliminate almost every candidate, returning too few results with no error. Test with your most selective filters, not with the whole collection.

• Never measuring recall

  Index parameters chosen for speed can quietly drop recall to 0.8, meaning one in five true neighbours never shows up. Keep a small benchmark of queries, compare index results against exact search, and re-run it after every parameter or data-size change.

• Embedding text longer than the model reads

  Every embedding model has a maximum input length; beyond it the text is truncated, often silently, so the end of a long document never influences its vector. Split documents into chunks that fit, and embed each chunk separately.

#Interview questions