Branching vector databases

An embeddings store has a property that makes people treat it like glass: rebuilding it costs real money. Re-embedding a few million chunks through an API is a bill you can read from across the room, and even self-hosted models turn a rebuild into hours of GPU time. So the vector database becomes the thing nobody touches. Reindex settings stay wherever they landed, quantization experiments never run, and the eval suite reads from the same collection production reads from, very carefully.

The fix is the one code already has. Fork the store, do the risky thing to the fork, keep or discard the result. Qdrant, Weaviate, and Meilisearch all branch on Layerbase Cloud, alongside 13 other engines. The managed vector services offer snapshots and backups, which get you a restore point; none of them offers this: a live, writable, copy-on-write fork of a running store that exists alongside its parent seconds later.

Fork it locally in two minutes

The Layerbase CLI runs the same workflow on your machine. Qdrant serves plain HTTP locally, so curl is enough:

npm i -g layerbase

lbase create vectors --engine qdrant --start

curl -X PUT http://127.0.0.1:6333/collections/docs \
  -H 'Content-Type: application/json' \
  -d '{"vectors": {"size": 4, "distance": "Cosine"}}'

curl -X PUT 'http://127.0.0.1:6333/collections/docs/points?wait=true' \
  -H 'Content-Type: application/json' \
  -d '{"points": [{"id": 1, "vector": [0.1, 0.2, 0.3, 0.4], "payload": {"source": "handbook"}}]}'

Fork it and check the fork inherited everything:

lbase branch vectors vectors-test
lbase url vectors-test

The branch runs on its own port with the parent's collection and points already in it. Write to the branch and the parent never sees it:

# `lbase url` prints the branch's own endpoint, so no port guessing
curl -X PUT "$(lbase url vectors-test)/collections/docs/points?wait=true" \
  -H 'Content-Type: application/json' \
  -d '{"points": [{"id": 2, "vector": [0.9, 0.8, 0.7, 0.6], "payload": {"source": "experiment"}}]}'

curl http://127.0.0.1:6333/collections/docs/points/2

{"status": {"error": "Not found: No point with id 2 found"}, ...}

Point 2 exists on the branch and returns not-found on the source. That isolation check is the exact test every engine passes before it is allowed on the branching list. Weaviate and Meilisearch behave the same way with their own APIs, schema and indexes included.

Where this earns its keep

Per-eval-run forks for RAG. A retrieval eval is only trustworthy if the store does not move under it, and a good eval often needs to mutate the store: re-rank payloads, tweak filters, delete the documents you suspect are polluting recall. Fork the database at the start of the run, mutate the fork freely, record the scores, delete the fork. Two eval configurations get two forks of the same parent and a fair fight.

Scratch stores for agents. An agent that can write to your embeddings store is an agent that can ruin your embeddings store. Hand it a branch instead. It gets real data with full read-write freedom, and the blast radius of a bad run is a branch delete. This is the same pattern as disposable databases for CI and agents, applied to the store that is most expensive to rebuild.

Reindexing and quantization without a leap of faith. HNSW parameters, scalar versus binary quantization, a new analyzer configuration in Meilisearch. These are exactly the settings you want to benchmark against production-shaped data and exactly the ones nobody benchmarks, because the store is precious. Benchmark the branch. Recall drops? Delete it. Recall holds? Apply to the parent knowing what happens.

A checkpoint before the bulk operation. About to delete every vector matching a filter you wrote at 6 pm? Branch first. If the filter was wider than you thought, the parent still has everything, and branch reset re-forks a mangled branch from the parent's current state in one command.

In the cloud

On Layerbase Cloud branch-ready databases sit on copy-on-write storage, so forking a multi-gigabyte embeddings store takes seconds and shares blocks with its parent. You pay for the vectors you change, not for a second copy of all of them, and creating the fork re-embeds nothing, so it costs no model calls at all. Free includes one branch per database, Solo three, Pro ten. Branches also wire into the Vercel integration and a GitHub Actions workflow, so a pull request that changes your retrieval code can get its own fork of the store automatically.

How the same mechanism branches 16 engines, from Postgres to Qdrant, is covered in Branching with any database. Branching lives in the filesystem, not the engine, which is why the vector stores could join at all.

Create a Qdrant, Weaviate, or Meilisearch database and fork it before your next eval run. The eval gets a stable store, production stays untouched, and the fork is gone before the results finish rendering.