Versioning Embeddings Without Breaking Production

~22 min · ops, migrations

Level 0Scout

0 XP0/41 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

Three things change over time

Embedding model — provider releases v3, you want to upgrade
Chunking strategy — you change splitter or chunk size
Metadata schema — you add a tenant_id or a permission level

All three require a re-ingest. The question is how to do it without a maintenance window.

The version-suffix discipline

Encode the version in the collection (or table) name: docs-bge-m3-v3, chats-openai-large-2026q2. The application keeps a config pointer. Migrations are: build the new collection in parallel, validate, flip the pointer, drop the old one a week later. The rollback is one config change.

Query-time fallback

During the migration window, query both old and new collections, return whichever has more results above the score floor. This catches the case where the new model is worse on a subset of queries before you fully cut over.

Code

Versioned collection helper·python

import os

DOCS_COLLECTION = os.environ.get('DOCS_COLLECTION', 'docs-bge-m3-v3')

def docs():
    return get_client().get_or_create_collection(DOCS_COLLECTION,
                                                 metadata={'hnsw:space': 'cosine'})

Dual-read during the cutover window·python

OLD = get_client().get_collection('docs-bge-m3-v2')
NEW = get_client().get_collection('docs-bge-m3-v3')

def retrieve(question: str, k: int = 5, min_score: float = 0.3):
    new_results = query(NEW, question, k)
    above = [r for r in new_results if (1 - r['distance']) >= min_score]
    if len(above) >= k:
        return above
    # Fall back to old collection if new collection is thin on this query
    return query(OLD, question, k)

External links

Exercise

Migrate a real (or seeded) collection from one embedding model to another using the parallel-collection pattern. Practice the rollback by reverting the config pointer. Time both directions — that wall-clock number is your real migration risk.

Progress

Progress is local-only — sign in to sync across devices.

← PreviousLatency: Batching, Async, and Where the Time Goes Next →Observability: Watching for Silent Decay

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.