Week 10 • Day 6Week 10
Day 6:Week 10, Day 6: Index Lifecycle — Tombstones, Versioned Upserts & Blue-Green Alias Swapping
Battle-tested daily lesson note • 100% runnable code, interview Q&A, test suite & interactive quiz
Week 10, Day 6: Index Lifecycle — Tombstones, Versioned Upserts & Blue-Green Alias Swapping
1. The "Stale Vector Ghost" Bug in Production RAG
Suppose runbook_payments.md originally had 6 chunks (C0..C5) stating:
"The on-call escalation phone number is
+1-555-OLD-NUM."
A week later, someone updates runbook_payments.md into a shorter 4-chunk document (C0..C3) stating:
"The on-call escalation phone number is
+1-555-NEW-NUM."
If your ingestion job simply runs UPSERT on chunk IDs C0..C3 without deleting the old C4 and C5 from the previous version of runbook_payments.md, chunks C4 and C5 remain in the vector database forever as "Stale Vector Ghosts", feeding contradictory, outdated instructions to your LLM!
2. Atomic Document Version Upserts & Soft-Delete Tombstones
- Document-Level Manifest & Tombstoning:
Every vector entry stores
doc_idandversion. Whendoc_idis updated toversion + 1:- All existing vectors for
doc_idare marked in atombstone_set(soft-deleted immediately in time so no search can return them). - The new chunks for
doc_idare inserted. - When the tombstone ratio exceeds a threshold (e.g.,
20%), a background Vacuum / Compaction rebuilds the contiguous matrix to reclaim RAM.
- All existing vectors for
- Blue-Green Index Alias Swapping:
When upgrading embedding models (
text-embedding-004 -> v005), buildindex_greenin the background while production traffic readsalias_prod -> index_blue. Onceindex_greenpasses Week 8's Golden Eval Gate, atomically repointalias_prod -> index_greenin0.001 mswith zero downtime!
In Simple English: Safe Database Updates Without Downtime (Tombstones & Blue-Green Alias)
- Why Deletion Is Hard in HNSW Graphs: Deleting one node inside a highway web breaks roads crossing through it! So Vector DBs stamp deleted records with a Tombstone flag ("skip me!") and periodically rebuild clean segments in the background (Compaction).
- Blue-Green Alias Swapping: When upgrading from Embedding Model v1 to v2 across 1 million docs, never overwrite the live table in place! Build
docs_index_v2safely next door, test it, and atomically flip thedocs_prodalias pointer in 1 millisecond with zero downtime!