Keyword search and vector retrieval

01Keyword search, vector retrieval, and ranking: definitions

Keyword search retrieves documents by matching searchable terms extracted and normalized from text. Vector retrieval finds documents whose numeric representations, called embeddings, are close to a query embedding under a chosen similarity measure. Retrieval selects candidates, ranking orders them, and hybrid search combines lexical (term-based) and vector signals. The source database preserves business facts. A search index is a derived, lookup-optimized representation of those records; asynchronous indexing means a successful source write need not be immediately searchable.

Use separate tests for lexical relevance, semantic relevance, freshness, and authorization. For query reset MFA phone lost (MFA means multi-factor authentication), Acme document D1 describes authenticator recovery, while D2 includes “reset MFA” but describes a different administrative procedure. Birch’s private runbook D3 must remain excluded. This dataset illustrates retrieval and access constraints without making either a substitute for the other.

Treat relevance, freshness and access as separate acceptance criteria. A highly similar result can still describe an obsolete procedure or belong to another tenant.

02Inverted index, tokenization, postings, and BM25

An inverted index maps a term to the documents containing it. A tokenizer splits text into searchable units; an analyzer may normalize case, handle language, or apply stemming. Exact product codes and identifiers often need a separate exact-match field because ordinary text analysis can alter punctuation or structure.

Suppose the analyzed documents are D1: recover access authenticator lost, D2: admin reset mfa, and D4: reset phone access. Their small index includes:

For an AND query reset access, intersect the posting lists and obtain D4. An OR query can return D1, D2, and D4, then rank them. Positions support phrase matching; document and term statistics support ranking. BM25 is a common lexical ranking function that rewards useful term matches while accounting for frequency and document length. Its score is not a probability that the answer is true.

BM25 combines three ideas: a match on a rarer term carries more information, repeated occurrences of one term have diminishing benefit, and document-length normalization stops long documents winning merely because they contain more words. In the tiny corpus, mfa appears in one document while access appears in two; their document-frequency signals differ. Phrase positions, required terms and exact identifier fields remain separate query controls, rather than guarantees supplied by a high BM25 score.

03Embeddings and cosine similarity

For intuition, imagine two-dimensional vectors: query Q=(1,0), D1=(0.98,0.20), and D2=(0.60,0.80). After accounting for normalization, cosine similarity to Q is approximately 0.98 for D1 and 0.60 for D2. Real systems often use hundreds or thousands of dimensions; the two-dimensional numbers only illustrate relative direction.

Semantic retrieval can connect “phone lost” with “recover authenticator” without identical words. It can also retrieve a similar-sounding wrong procedure. Exact IDs, dates, negation, and small wording differences may matter more than broad similarity. Keep lexical matching and metadata constraints when they serve the query contract.

Cosine similarity compares the directions of two nonzero vectors: dot(Q,D) / (length(Q) * length(D)). The dot product multiplies corresponding coordinates and adds the products. A vector’s length is the square root of the sum of its squared coordinates. Normalizing a vector divides every coordinate by that length, giving a unit-length vector. For D1, the denominator is sqrt(0.98^2 + 0.20^2) ≈ 1.0002, so similarity is about 0.9798; D2 has unit length and scores 0.60. With unit-normalized vectors, dot product and cosine produce the same ranking, and squared Euclidean distance is 2 - 2*cosine. Without normalization these metrics can rank candidates differently. A zero vector needs an explicit handling policy because cosine is undefined.

04Search ingestion and query lifecycle

1. Ingest Acme document D1 version 7 with its ID, title, tenant, access policy, source version, and location.
2. Split long content into coherent chunks, retaining permissions and provenance on each chunk.
3. Build term postings and embeddings with recorded analyzer and model versions. Record which source version is indexed.
4. Authenticate the query request, derive its allowed tenant/document scope, analyze the query, and embed it using the compatible query model.
5. Retrieve scoped candidate IDs. Check each candidate against the source system’s current permissions, obtaining the exact content version and policy revision that were authorized; fetch that immutable version. On a version/policy mismatch, reauthorize or discard the candidate.
6. Fuse lists or rerank only content authorized by that decision. Before returning snippets, enforce the policy for when permission revocations take effect and withhold or retry any candidate whose required policy revision no longer matches.
7. Reauthorize a later source-document request. A search hit does not grant permanent access.

05Exact nearest neighbors, ANN, HNSW, and vector memory

Exact nearest-neighbor search returns the true nearest eligible vectors under the chosen metric. A simple exact baseline scores every eligible vector; an exact index may prune candidates only when it can prove they cannot change the answer. Exhaustive scoring is often useful as an evaluation baseline, but exactness is a result guarantee, not a requirement to scan every vector. Approximate nearest-neighbor search, ANN, uses an index to examine fewer candidates, trading some retrieval recall for latency and resource savings. Hierarchical Navigable Small World (HNSW) is a graph-based ANN approach: search navigates connections among nearby vectors rather than scanning all vectors.

For 10 million vectors with 768 float32 components, raw vectors consume 10,000,000 × 768 × 4 bytes = 30.72 GB in decimal units. Graph links, metadata, text, replicas, and indexing overhead add more. Quantization can reduce vector storage, with a quality and implementation tradeoff that must be measured.

HNSW uses a hierarchy: sparse upper layers provide long-range navigation, then the search descends to denser layers and explores a bounded candidate set near the query. Retaining more candidates generally improves recall at additional query work; adding graph connections costs memory and construction work. Tuning must include filtered queries and updates, not only unfiltered reads.

An inverted-file (IVF) index offers another tradeoff: train a set of coarse clusters, assign vectors to lists, and probe selected nearby lists at query time. Searching too few lists can omit the true neighbors. Product quantization is a separate compression technique that represents vector subvectors with compact codes; it can save memory while introducing distance error. Index navigation and numeric compression are different sources of approximation.

06Hybrid search, reciprocal rank fusion, and reranking

A simple hybrid strategy runs lexical and vector retrieval, deduplicates by document or chunk identity, and fuses their ranked lists. Do not add arbitrary raw scores without calibration: a BM25 score of 12 and a cosine score of 0.8 have different scales.

One way to avoid incompatible score scales is to combine each candidate’s position in the retrieved lists. Reciprocal rank fusion gives larger contributions to higher-ranked candidates and adds the contributions across lists. It does not require BM25 and cosine scores to mean the same thing.

Reciprocal rank fusion uses each item's rank, for example a contribution of 1/(60 + rank) from each list. If D1 is rank 1 in vector search and rank 4 in lexical search, its combined contribution is 1/61 + 1/64 ≈ 0.0320. The constant 60 is an illustrative choice, not a universal best setting. A reranker can then compare the query with a bounded candidate set more carefully, at additional latency and compute cost.

Deduplicate overlapping chunks, diversify where the task requires distinct sources, and preserve exact-match boosts for identifiers. The final page should contain useful evidence, not ten slightly different chunks of the same paragraph. Decide ranking behavior with evaluated queries, not the sophistication of the algorithm name.

07Precision, recall, index freshness, and authorization

Precision asks what fraction of returned documents are relevant. Recall asks what fraction of all relevant eligible documents were returned. The @k notation evaluates only the first k results, so both metrics need an explicit cutoff and a labeled set of relevant documents.

Assume a labeled query has five relevant authorized documents. The returned top five contain three of them. Precision@5 is 3/5 = 60%; recall@5 is 3/5 = 60% in this example. If there were ten relevant documents instead, precision would remain 60% but recall would be 30%. Rank-sensitive measures such as nDCG also value putting highly relevant results near the top.

Measure how long indexing, deletions and permission changes take, alongside p95 latency, empty results and cost. If revocation must take effect immediately, old index metadata cannot be the only access check. Track document versions, propagate deletion markers and check current permission before returning content. Build and validate a replacement index separately, then switch readers while retaining a rollback option. Updating the live index piece by piece can mix incompatible versions.

Start with the simplest search setup that meets measured needs. PostgreSQL full-text search and pgvector can keep search close to source records and permissions; measure exact vector search first. Add HNSW or IVFFlat when the speed benefit justifies their recall and resource costs. Filtering approximate results may leave too few matches, while searching further costs work. A separate service such as Elasticsearch or Azure AI Search can scale search independently, but its copied index still needs a freshness and access-control policy.

An index migration must move a compatible set of components together: query embedding model, stored embeddings, analyzer, chunking and ranking configuration must remain compatible. Record the serving generation on each request and evaluate the replacement on the same relevance and permission tests before switching traffic.

Precision and recall count useful results but do not distinguish where they appear within the evaluated list. Moving the best answer from first to fifth can make the experience worse without changing either count. Rank-sensitive measures evaluate that ordering; choose one that reflects whether the user needs a first useful answer or a useful result list.

Mean reciprocal rank (MRR) measures how early the first relevant result appears. For each query, use 1 / rank of its first relevant result, or zero if none appears within the evaluation cutoff; then average across queries. First hits at ranks 1, 4 and absent give (1 + 0.25 + 0) / 3 ≈ 0.417. MRR suits “find one good answer” tasks but ignores the quality of later results.

Normalized discounted cumulative gain (nDCG) sums graded relevance with lower weight at later ranks, then divides by the ideal ordering’s score at the same cutoff. It measures the quality of the ranked list, rather than only the first hit. State relevance labels, cutoff and the convention for queries with no relevant documents; do not compare scores from different evaluation sets as though they were interchangeable.

Recall the key ideas

Answer from memory before opening each card. Explain why the choice works and what it costs. Revisit missed cards tomorrow.