Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 36 ยท Production Patterns

Updates, Deletes and Index Versioning

Keep a RAG index fresh: sync by content hash, delete chunks for removed documents, handle stale data, and migrate embedding models with a blue-green index swap.

A RAG index is a copy of your knowledge, and copies go stale. Prices change, policies are rewritten, pages are deleted, a customer asks you to erase their data. If the index is not updated, the assistant confidently quotes yesterday's truth. This lesson covers the mechanics of keeping the index correct: incremental sync, deletion, freshness, and safe migrations when the embedding model or chunking changes.

Design for updates from day one

The key design decision is stable identity. Every chunk needs:

  • a doc_id (the source document, stable across edits),
  • a deterministic chunk_id (for example doc_id#section-3#hash),
  • a content_hash of the chunk text (and of the settings that produced it),
  • source_updated_at and indexed_at timestamps,
  • metadata for filtering (metadata filtering): tenant, version, language, ACL.

With those, an update job can compare "what the source says now" with "what the index holds" and apply only the difference.

Incremental sync with content hashes

Re-embedding a whole corpus nightly is slow and costly. Instead, hash each chunk and compare:

  • New hash not in the index: embed and insert.
  • Missing hash (a chunk id in the index but not in the source): delete.
  • Unchanged hash: skip, no embedding call.
Python Plan an incremental sync

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Only two embedding calls are needed, and the removed page is purged. Note the order in production: write new vectors first, then delete old ones (or use an upsert keyed by chunk_id), so there is never a moment when a document has no chunks.

Updates change more than text

A document edit can change how many chunks it has. If a page shrinks from 12 chunks to 9 and you only upsert, chunks 10 to 12 stay behind as ghosts. The robust patterns are:

  • Delete by doc_id, then insert the new chunks (in a transaction if your store supports it).
  • Compare sets of chunk ids per document as above, and delete the extras.
  • Version stamp each indexing run (run_id) and delete anything for that document with an older run_id once the new chunks are in place.

Deleting data for real

Deletes come in two kinds:

  1. Content deletes: the source was removed or unpublished. Remove its chunks so they cannot be retrieved.
  2. Privacy deletes: a user exercises the right to erasure, or a legal hold ends. Chunks, vectors, caches, logs, backups and the original files must all be purged. Vectors derived from personal data are personal data. Plan this up front: tag chunks with the data subject or tenant so a deletion query is possible.

Many vector databases implement deletes as tombstones: the point is hidden immediately but space is reclaimed by background compaction. That is fine for retrieval correctness, but verify with a test that deleted ids are really never returned, and know your engine's behaviour for filtered ANN search with many tombstones.

Remember the other places stale data hides: the answer and retrieval caches (include a corpus version in the cache key or purge on updates), chat history that quoted the old text, and exported evaluation sets.

Freshness and staleness signals

  • Event-driven updates: webhooks or change-data-capture trigger re-indexing within seconds. Best for fast-changing data.
  • Scheduled sync: a cron job every hour or night. Simple and usually enough for documentation.
  • Time-aware ranking: boost recent documents, or filter on valid_from and valid_to for policies that change on a date.
  • Show dates in citations so users can judge freshness.
  • Staleness monitor: alert when the newest indexed_at for a source is older than its SLA.

Blue-green re-indexing for model or chunking changes

Embeddings from different models live in different spaces: you cannot compare a vector from model A to one from model B, and you cannot mix them in one index. Likewise, changing dimensions, normalization, chunk size or the cleaning pipeline changes what a chunk is. So major changes require building a new index beside the old one:

  1. Create docs_v2 with the new embedding model and settings.
  2. Backfill all documents into it (batch, rate-limited, resumable).
  3. Replay updates that arrived during the backfill (dual-write to both indexes meanwhile).
  4. Evaluate docs_v2 on your evaluation set (retrieval metrics) and compare to docs_v1.
  5. Switch an alias (or config flag) from v1 to v2, ideally for a percentage of traffic first.
  6. Keep v1 for a rollback window, then delete it.
Python Alias swap between index versions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The application only ever talks to the alias docs, so the switch and the rollback are single, instant operations. Many engines support aliases natively (Elasticsearch, OpenSearch, Qdrant, Weaviate, Milvus); where they do not, store the active index name in configuration.

Store the embedding model name and version in the index metadata. Querying an index with a different model than the one used to build it is a silent, hard-to-notice bug: no error, just bad results.

Backups and recovery

The vector index can be rebuilt from the source documents, so treat the source of truth (documents, chunking config, metadata) as the thing to back up, and the index as a cache you can regenerate. Still, snapshot the index when rebuilding is slow or expensive, and rehearse a restore. Keep the ingestion code and configuration in version control so a rebuild is reproducible.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why hash chunk text during ingestion?

    A hash comparison tells you what is new, changed or unchanged without calling the embedding model.
  2. 2. A page shrinks from 12 chunks to 9 and you only upsert. What goes wrong?

    Upsert does not remove chunk ids that no longer exist; delete by doc id or diff the id sets.
  3. 3. Why can't you mix vectors from two embedding models in one index?

    Each model defines its own space; similarity only makes sense within one model.
  4. 4. What is the benefit of querying through an alias?

    The application never changes; only the alias target does.

Summary

  • Give every chunk stable ids, a content hash and timestamps.
  • Sync incrementally: embed new or changed, delete removed, skip the rest.
  • Delete by document, not just by chunk, and purge caches and logs for privacy requests.
  • Re-embed into a new index and swap an alias when the model or chunking changes; record the model version.
  • Treat sources as truth and the index as rebuildable.

Next: Security, Access Control and Prompt Injection