Do Not Mix the Maps: A Safe Migration for Embedding Indexes

A search team replaces an embedding model because the candidate is cheaper and performs better on a public leaderboard. Both models emit 1,024 numbers, so the team overwrites vectors in the existing index as a background job. During the job, a new-model query meets a mixture of old- and new-model document vectors. Results remain syntactically valid, latency looks normal, and no database alarm fires. Relevance quietly becomes arbitrary.

The reader decision is: should this change be an offline rebuild, a parallel blue-green index, or a second named vector—and what evidence permits cutover? The answer depends on recoverability, live mutation rate, consequence, storage headroom, and whether the platform can route one complete vector space atomically.

The central rule is: an embedding is meaningful only inside the exact coordinate system that produced it. Never expose a search request to a partially migrated space. Preserve the source corpus, give each complete space an immutable epoch, evaluate the whole retrieval system, switch queries deliberately, and retain a tested rollback path.

The model name is not the migration boundary

An embedding system turns content into coordinates, but the effective mapping includes more than a provider and model label:

Google's current text-embedding documentation illustrates why representation details matter: it identifies a model's dimensionality and says its output is normalized, which makes several distance functions produce the same ranking for that output. That is a property of the documented output, not permission to assume that every model, reduced dimension, or local transformation shares it.

Equal dimensions do not establish compatible coordinates. A query encoded by model B cannot be compared meaningfully with documents encoded by model A merely because both arrays fit the same database field. Changing only chunking is also a new corpus epoch: the vector may use the same model, but it represents a different evidence unit with different identifiers and citation boundaries.

What primary evidence establishes—and where design begins

The production patterns are unusually concrete. Qdrant's embedding-model migration guide describes parallel collections with dual writes and alias cutover, or an added named vector followed by backfill and query switching. It also warns that deletes and partial updates need special treatment in a blue-green flow. Weaviate's vectorizer migration tutorial similarly starts with a representative baseline, evaluates the candidate on identical data, and presents collection aliases as the usual reversible production method.

Research supports contextual evaluation, not a universal winner. The 2023 MTEB paper evaluated 33 models across eight task families and found no single embedding method dominated all tasks. NIST's valid-and-reliable guidance says accuracy measurements should use clearly defined, realistic test sets representative of expected use, with documented methodology.

Those sources do not mandate the epoch receipt, cutover gates, or reconciliation ledger below. Those are ZharfAI analysis: a vendor-neutral operating pattern derived from the documented migration mechanics, vector behavior, and evaluation principles.

Choose the migration shape before starting the backfill

Treat in-place mutation as the exception, not the cheap default. If the router cannot prove that all queries and all documents use one epoch, it is not a safe live migration.

This complements the RAG knowledge-quality guide: source authority and citation quality still matter, but a migration adds the separate obligation to preserve retrieval geometry and evidence-unit identity.

Make the source corpus rebuildable

A vector store should not be the only surviving copy of what was embedded. Keep an authoritative source record or immutable content object plus enough transformation evidence to reproduce each searchable unit:

{
  "source_id": "policy-184",
  "source_version": "sha256:...",
  "chunk_id": "policy-184/v7/section-12",
  "content_hash": "sha256:...",
  "parser_version": "pdf-pipeline-9",
  "chunker_version": "semantic-480-v3",
  "redaction_policy": "privacy-6",
  "tenant_id": "tenant-42",
  "acl_version": "acl-991",
  "source_sequence": 38104,
  "deleted": false
}

Stable source identity and version-specific chunk identity solve different problems. source_id links editions of a document; chunk_id names the exact evidence unit returned to the answer layer. A content hash detects transformation drift. A monotonically increasing source sequence or comparable version check prevents an old backfill worker from overwriting a newer live update.

Keep tombstones until both spaces have observed them. A migration that re-creates a deleted document from a stale batch is a privacy and correctness failure, even if retrieval metrics improve.

Give each vector space an immutable receipt

Create an epoch record before writing the first target vector:

embedding_epoch = emb-2026-08-b
encoder = provider/model@immutable-revision
mode = document | query
dimensions = 1024
normalization = l2
distance = cosine
numeric_type = float32
parser = pdf-pipeline-9
chunker = semantic-480-v3
index = hnsw(m=..., ef_construction=...)
filters = tenant-acl-time-v5
reranker = rerank-contract-v4

Attach the epoch to document vectors, query encoding, index configuration, evaluation reports, and retrieval receipts. Refuse a query when the router's query epoch differs from the selected collection or named vector. Do not silently fall back to “whatever vector exists.”

Elasticsearch's dense-vector reference documents distinct similarity semantics and accuracy/speed tradeoffs in approximate index settings. The receipt therefore needs search geometry and index parameters, not only the encoder. It should join the broader AI release passport, but remain query-visible so operators can prove which retrieval epoch answered a request.

Move live mutations without losing order

The safe choreography is a state transition, not “run a re-embed script”:

1. Materialize the target epoch and prevent unreviewed configuration edits.
2. Record a source high-water mark.
3. Start a durable change stream or dual-write path carrying source sequence, upsert, and delete events to both epochs.
4. Backfill records at or below the high-water mark from authoritative content, not old vector payloads alone.
5. Apply each mutation conditionally: a lower sequence cannot replace a higher one.
6. Reconcile counts, hashes, ACLs, tombstones, vector coverage, and freshness lag.
7. Evaluate and shadow the target without serving its results to users.
8. Switch query encoder and index route as one versioned operation.
9. Observe outcome gates; keep the old epoch current through the rollback window.

Qdrant's guide distinguishes safe point deletion in its named-vector approach from operations that need pausing or extra logic in a parallel collection. Generalize that warning: enumerate every mutation verb your system actually supports. Upsert-only dual writing is not consistency if editors can delete payloads, alter access lists, merge documents, or change tenant ownership elsewhere.

Evaluate retrieval, not embeddings in isolation

Build a frozen migration set from real, permitted operating traffic. Include frequent queries, rare intents, Persian and English, short and long questions, entity-heavy requests, time-sensitive material, access-filtered cases, expected no-result cases, and known incidents. Keep sensitive queries protected and use accountable human judgments or verified downstream outcomes.

Measure layers separately:

The pgvector project documentation states that approximate indexes trade recall for speed and recommends monitoring recall against exact search. This matters during migration: a model improvement can be cancelled by more aggressive quantization, a smaller candidate budget, or different filtering behavior. Compare exact old versus exact new first; then measure each production index against its exact counterpart.

Do not carry score thresholds across epochs. Cosine 0.78 in one space does not inherit the same meaning in another. Recalibrate accept, rerank, ask-for-more-evidence, and abstain thresholds on target-epoch distributions and consequences.

Run shadow queries without creating side effects

For an allowed sample of production queries, encode and search both epochs. Return only the current result; store a privacy-reviewed comparison record containing epoch IDs, candidate identifiers, ranks, latency, applied filters, and judgment status. Do not duplicate downstream tool calls or user-visible actions.

Segment the comparison. Aggregate wins can conceal a collapse in Persian retrieval, one tenant's product names, fresh documents, or long-tail policy questions. NIST's AI RMF Measure Playbook calls for documented test sets and methods, assessment of external validity, and renewed metrics as operating conditions or models change. A migration report should therefore state where evidence is strong, weak, or absent.

Shadowing also exposes operational differences: query-encoder throttling, cold caches, tail latency, missing ACL fields, and target freshness. A relevance win that cannot meet the service budget is not yet a release.

Worked example: a bilingual policy assistant

Consider a hypothetical assistant searching five million Persian and English policy chunks. The team wants a new multilingual encoder and a revised chunker. Because both representation and evidence boundaries change, it chooses parallel collections.

The source table assigns every document version a sequence and keeps delete tombstones. The target collection stores new chunk IDs, the target epoch, content hash, language, tenant, ACL version, and effective time. A change stream begins at sequence 38,104; the backfill handles older state, while conditional live writes win over stale batches.

The evaluation set contains 1,200 adjudicated queries: 400 Persian, 400 English, 200 cross-language, and 200 access-filter/no-answer cases. The team compares exact retrieval first, tunes the target approximate index second, then runs a one-week shadow. The candidate raises overall nDCG but loses recall for Persian legal citations and newly updated documents. Cutover is blocked. Investigation finds inconsistent Persian normalization and a lagging ACL/change stream. Both are repaired and the complete evaluation rerun.

At cutover, one router configuration changes query_epoch and collection_alias together. Each retrieval receipt records both. The old collection continues receiving mutations for seven days. Rollback is a route reversal, not an emergency re-embedding job.

The numbers are illustrative, not a ZharfAI deployment or a universal threshold. The lesson is the order of proof: completeness, access parity, exact retrieval, approximate retrieval, downstream outcome, operations, then cutover.

Failure modes that often look healthy

Public embedding benchmarks are useful for candidate discovery. They are not acceptance tests for a corpus, language mix, access policy, or downstream answer contract.

Cut over only on a decision-complete gate

Before switching, require evidence for all of the following:

• the exact encoder revision, modes, dimensions, normalization, transformations, geometry, filters, and index settings are frozen in the target epoch;
• every eligible source version has exactly the expected target chunks and vectors;
• every delete, ACL change, and live update is reconciled at or beyond the high-water mark;
• query encoding and index routing change atomically and reject epoch mismatch;
• evaluation covers relevant languages, tenants, intents, freshness, filters, no-answer cases, and past incidents;
• exact and approximate retrieval are measured separately, and score thresholds are recalibrated;
• answer quality, citations, abstention, latency, capacity, and cost remain within approved limits;
• dashboards expose epoch, coverage, divergence, freshness lag, filtered recall, and rollback readiness;
• the old epoch remains protected, current, and routable until the rollback window closes;
• a named owner can stop cutover and a practiced procedure can reverse it.

This also extends the recovery-cut architecture: backups are insufficient if source content, transformation versions, query encoder, index, filters, and router cannot be restored as one compatible retrieval state.

What to monitor after the switch

Watch target-only signals and old-versus-new deltas: zero-result rate, retrieved-language mix, stale-document rate, access-filter drops, exact-to-ANN recall sample, citation support, abstention, user correction, latency tails, encoder errors, index saturation, and cost per successful task. Keep the evaluation set alive with newly adjudicated failures; do not quietly rewrite old labels to make the release look better.

End the rollback window by decision, not by storage pressure. First prove that the target has survived normal load, rare queries, content churn, deletes, access changes, and at least one rollback exercise. Then stop old-epoch writes, take a protected final snapshot if policy permits, document residual uncertainty, and remove the old index under change control.

The durable principle is simple: preserve the source, name the whole space, compare like with like, and switch the route—not individual coordinates.

Source Notes — Reviewed 2026-08-25

• Qdrant — Migrate to a New Embedding Model
• Weaviate — Switching vectorizers
• Google Cloud — Get text embeddings
• Elastic — Dense vector field type
• ACL Anthology — MTEB: Massive Text Embedding Benchmark
• pgvector — Open-source vector similarity search for Postgres
• NIST AIRC — AI Risks and Trustworthiness
• NIST AIRC — AI RMF Measure Playbook