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

  1. Document-Level Manifest & Tombstoning: Every vector entry stores doc_id and version. When doc_id is updated to version + 1:
    • All existing vectors for doc_id are marked in a tombstone_set (soft-deleted immediately in O(1)O(1) time so no search can return them).
    • The new chunks for doc_id are inserted.
    • When the tombstone ratio exceeds a threshold (e.g., 20%), a background Vacuum / Compaction rebuilds the contiguous matrix to reclaim RAM.
  2. Blue-Green Index Alias Swapping: When upgrading embedding models (text-embedding-004 -> v005), build index_green in the background while production traffic reads alias_prod -> index_blue. Once index_green passes Week 8's Golden Eval Gate, atomically repoint alias_prod -> index_green in 0.001 ms with 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_v2 safely next door, test it, and atomically flip the docs_prod alias pointer in 1 millisecond with zero downtime!