Vector databases from the ground up
Indexes, filters and recall you can measure
- Intermediate
- 10 chapters
- 157 min read
What a vector index actually is, and the decisions behind it: cosine versus dot product, flat search versus HNSW and IVF, filtering before ranking, tombstones and re-embedding, hybrid retrieval with reranking, sharding and replication, and a capstone that measures recall@k instead of trusting a benchmark.
What You'll Learn
- Explain what a vector index stores and what the database adds around it
- Choose a similarity metric that matches the embedding model
- Compare flat search with HNSW and IVF, and measure the recall each one loses
- Apply metadata filters without breaking the top-k promise
- Handle updates, deletes and an embedding-model migration without stale results
- Fuse lexical and dense retrieval, then rerank the shortlist
- Size and shard a collection, and merge results across shards correctly
- Quantise vectors and measure what the memory saving costs in recall
- Operate a shared index for many tenants with scopes, quotas and a delete path
- Build a small index and measure its recall against exact search
Prerequisites
- Comfortable with Python lists, dictionaries and classes
- The RAG course is useful but not required
- No API key is needed — the examples use hand-built vectors
Vocabulary
The terms the chapters assume, in plain words.
- approximate nearest neighbour (ANN)
- A search that checks only part of the index, so it is fast but may miss some of the true closest matches.
- collection
- A named group of vectors that share one configuration and are searched together.
- cosine similarity
- The dot product of two unit-length arrows, from 1 when they point the same way to -1 when they oppose.
- dot product
- Multiply matching numbers in two lists and add the results; it grows with both length and agreement.
- embedding
- A list of numbers that places a piece of text in a space where similar meanings sit close together.
- embedding model
- The trained program that turns text into vectors, with one fixed output width.
- hybrid search
- Running a word-matching search and a meaning-based search together, then combining their ranked lists into one.
- index
- A structure built ahead of time so the database can find nearby items without comparing against every one.
- magnitude
- The length of a vector, found by squaring its numbers, adding them and taking the square root.
- metadata filter
- A rule that keeps only the items whose stored facts, such as date or owner, match before or during the search.
- model card
- A short document describing a trained system: its data, its scores and its known limits.
- normalised vector
- A vector divided by its own length, so it has length one and only direction remains.
- quantisation
- Storing each number with less precision, which shrinks memory and usually costs a little accuracy.
- recall
- The share of the truly closest items that a search actually returned.
- reranking
- Scoring a short list of results again with a slower, more careful method and putting the best first.
- similarity function
- A rule that scores two vectors and returns a number saying how alike they are.
- top-k
- The shortlist a search returns: its best few results, cut off at a number chosen in advance.
- training loss
- The average error an embedding model makes on the text pairs it is trained to match.
- unit length
- A vector whose magnitude is exactly 1, which makes a dot product read as pure agreement.
- vector
- An ordered list of numbers, where each position is one measured property.
Course Content
- 01What a vector index isNot started
A vector index answers one question fast: which stored vectors are nearest to this one? Everything else a vector database does is storage, filtering and operations around that answer.
- 02Similarity metricsNot started
Cosine, dot product and Euclidean distance are three ways to say “close”. They disagree about magnitude, and the embedding model you chose was trained with one of them in mind.
- 03Flat versus approximate indexesNot started
Flat search compares the query to everything and is exact. HNSW walks a graph and IVF probes a few partitions; both are faster and both can miss. The knob is real, and it can be measured.
- 04Metadata filteringNot started
A filter decides which vectors are eligible before ranking. Where you apply it decides whether you return k results or k attempts, and a selective filter can make an ANN index useless.
- 05Updates and deletesNot started
Most vector indexes are built once and updated badly. An update is a delete and an insert, a delete is often a tombstone, and the gap between what is stored and what is live is where stale answers come from.
- 06Hybrid search and rerankingNot started
Dense vectors are good at meaning and bad at exact strings. Lexical search is the reverse. Run both, fuse the two lists, and rerank a shortlist with a model that reads the query and the document together.
- 07Sharding and scaleNot started
One machine holds a finite number of vectors. Sharding splits the corpus, replication copies it, and both change what top-k means and what a delete costs.
- 08Quantisation and memoryNot started
Float32 vectors are the memory bill. Scalar and product quantisation shrink them four to ninety-six times, and the only honest exchange rate is the recall you measured on your own queries.
- 09Multi-tenant operationsNot started
A tenant is a promise about blast radius, not a column. Shared filters, per-tenant collections and separate clusters trade cost for isolation, and every one of them needs quotas, a delete path and a test with two tenants.
- 10Capstone: a small index with recall measurementNot started
Build a flat index and a partitioned index over the same vectors, then measure recall@k and the work each one does. The number that matters is the one you measured on your own queries.