Build Vector Search Inside a SQL Database

Write You a Vector Database is a short hands-on course for systems and backend engineers. You will build a small in-memory vector database in Rust, first with exact nearest-neighbor search and then with approximate indexes. The final system will answer SQL top-k queries through DataFusion and make the tradeoff between recall, latency, and memory visible.

The original 2024 C++/BusTub course is preserved as a deprecated, unmaintained edition. It is no longer the recommended path for new learners.

Why Build a Vector Database?

Embeddings turn text, images, and other data into fixed-dimensional vectors. A vector database stores those vectors and retrieves the items closest to a query vector under a distance metric. Exact search compares the query with every stored vector. Approximate nearest-neighbor (ANN) indexes avoid much of that work in exchange for returning an imperfect result set.

This course builds vector search as a database feature rather than as an isolated ANN library. The goal is not only to understand IVFFlat and HNSW as algorithms, but also to see how vectors, distance expressions, query planning, execution, and indexes fit together behind one SQL top-k query.

What You Will Build

The proposed course has one cumulative Rust implementation:

1. An exact-search collection with stable point IDs and a bounded top-k operator.
2. A benchmark and recall harness that treats exact search as the correctness oracle.
3. IVFFlat, NSW, and HNSW indexes behind the same search interface.
4. A thin DataFusion adapter that turns a safe SQL top-k pattern into a vector-index scan.

The core will be an ordinary Rust library. DataFusion supplies SQL parsing, planning, Arrow arrays, and execution, but the collection and indexes remain independent of it. This separation makes the integration small enough to understand and shows which responsibilities belong to the SQL engine and which belong to the vector index.

Learning Goals

After completing the course, you should be able to:

• define the semantics and edge cases of Euclidean, cosine, and inner-product search;
• implement exact top-k search without sorting the entire collection;
• explain how IVFFlat and HNSW trade build cost, memory, latency, and recall;
• design benchmarks that compare ANN results with exact ground truth;
• recognize when a SQL top-k query can safely use an approximate index; and
• separate a storage and search engine from its SQL interface.

What This Course Will Not Cover

The required path will not implement embedding models, persistent index files, online updates or deletes after an index is built, crash recovery, filtered ANN search, distributed execution, GPU kernels, or an HTTP service. It will also avoid calling an existing ANN library for the algorithms students are meant to learn.

Those boundaries keep the course focused on vector search. They also make every required component small enough to test, measure, and explain.

Prerequisites

You should be comfortable with Rust ownership, traits, error handling, iterators, and Cargo. You should also know basic database concepts such as records, indexes, SQL ordering, and query plans.

Prior knowledge of nearest-neighbor algorithms, Apache Arrow, or DataFusion is not required. The course will introduce the small subset of DataFusion’s extension interface used by the final chapter.

How to Use This Book

Start with the Rust course design proposal. It defines the selected architecture, system contracts, progression, and scope. Implementation chapters will be published only with matching starter code, completed checkpoints, and focused tests.

Each implementation chapter will begin with an observable capability, the relevant invariants, and a small prediction exercise. It will end with focused verification and questions that require evidence from the implementation or benchmark rather than recall from the prose.

Every chapter will start from the runnable state produced by its prerequisite. New algorithms will first be compared with an exact oracle and then integrated behind the existing collection API. The same SQL query shown in the design proposal will run through the ANN index in the final chapter.

Community

Join skyzh’s Discord server to study with the write-you-a-vector-db community.

About the Author

Chi is a database systems engineer and the author of Mini-LSM and LLM Serving in a Week. He has worked on storage and database systems including TiKV, AgateDB, TerarkDB, RisingWave, Neon, and RisingLight, and served as a teaching assistant for CMU’s Database Systems course.

Your feedback is greatly appreciated. Join our Discord community.
Found an issue? Open an issue or pull request at github.com/skyzh/write-you-a-vector-db.
write-you-a-vector-db © 2024-2026 by Alex Chi Z. All Rights Reserved.