Introduction
What NuclaDB is and how these docs are organized.
NuclaDB is a vector similarity search engine written from scratch in Go. The server, nucladbd, runs the HNSW graph, the crash-safe WAL, mmap snapshots, multi-tenancy, metadata filters, API keys and TLS, and a gRPC + REST API. Product quantization and a Raft-coordinated sharded cluster are also implemented and tested as Go packages, but the server doesn't run them yet. All of it is implemented directly in this repo, not imported from another engine.
Why this exists
Most "vector database" side projects wrap an existing engine (Qdrant, Pinecone, pgvector) behind an app. NuclaDB is the other direction: it implements the kind of internals those engines are built from, and is benchmarked head-to-head against a real Qdrant instance instead of assumed to be competitive.
What's in here
Quickstart
Install the CLI and run a scripted demo against a real local server.
Architecture
The single-node request flow: gRPC/REST, then the engine, WAL, HNSW, and mmap snapshot.
API reference
REST/JSON and gRPC request and response shapes, taken from the real Go structs and .proto file.
CLI reference
Every nucladb-cli command, with real recorded output, including quota and tenant errors.
Distributed cluster
Raft, consistent hashing, scatter-gather routing, async WAL replication, and health-checked failover.
Design decisions
Four writeups on what each major tradeoff cost, measured, not assumed.
Known limitations
A few things are worth knowing up front, so nothing here reads as more finished than it is:
- Qdrant's recall is a little higher at low
ef(0.959 vs 0.932 at ef=10), though NuclaDB is faster at everyeftested. See HNSW ef tuning. - Product quantization and the sharded cluster are libraries, not server modes:
nucladbdruns a single node without PQ. Nothing yet starts replication streams per shard or moves data on a rebalance. See Distributed cluster. - Flat product quantization gets 57.7% recall@10 at 16x compression; re-ranking the top 100 brings it to 99.3%. See Product quantization cost.
- A 4-shard cluster runs 38 to 45% slower (in QPS) than single-node, from scatter-gather network hops. See What Raft gave and cost.
- Replication is async, so a leader failover can lose an acknowledged write. The Jepsen-style tests report this rather than hide it.
The numbers in these docs come directly from committed benchmark output (bench/results.md, bench/results-cluster.md) or from the Go source itself. None of it is estimated.