How to Re-Embed Content When a Model Changes Without Downtime

You changed the embedding model, and now half your semantic search results are garbage. The vectors your old model produced live in a different space than the ones your new model produces, so cosine similarity between them is meaningless. Product search returns unrelated items, your RAG pipeline retrieves the wrong passages, and support has no idea why. The naive fix, re-embed everything and swap the index, means a window where queries hit a half-populated index and users see broken results. For a catalog with millions of documents, that window is not minutes; it is hours.

Sanity is the AI-native content platform built to make this exact operation boring. As the Content Operating System for the AI era, it ties embeddings to your content rather than treating them as a separate database you have to babysit, so a model migration becomes a managed re-index instead of a fire drill across three systems.

This guide reframes re-embedding as a governed content operation, not a database migration. We cover blue-green index strategy, backfill without read downtime, cutover safety, and why owning embeddings inside the content layer removes an entire class of drift bugs.

Why a model change silently breaks retrieval

Embedding models map text into a high-dimensional vector space. The geometry of that space is specific to the model and, often, to the exact version and dimensionality. When you move from one model to another, or even from one version of the same model to the next, the coordinates shift. A vector produced by the old model and a vector produced by the new model are not comparable, because similarity is measured within a single space, not across two. Blend them and every distance calculation lies to you.

The failure is insidious because nothing crashes. Your index still returns results, your API still responds with a 200, and your dashboards stay green. What degrades is relevance, which no infrastructure alarm watches. A merchandiser notices that searching for "waterproof hiking boots" surfaces sandals. A support agent notices the AI answer citing an unrelated policy. By the time anyone traces it to the model swap, days of bad retrieval have shipped.

The root cause is almost always the same: embeddings were stored in a system that has no idea which model produced them, at what dimensionality, or against which version of the source content. Vectors get treated as opaque numbers in a separate database, divorced from the documents they represent and the model that made them. That separation is exactly what turns a routine model upgrade into a production incident. The fix starts with treating embeddings as a property of governed content, versioned and traceable, rather than as loose rows in a vector store nobody owns.

The blue-green index pattern for embeddings

The safe way to re-embed at scale borrows from blue-green deployment. You never mutate the index your production traffic reads. Instead, you build a second, fully populated index alongside it using the new model, verify it, and only then flip reads over in a single atomic switch. The old index keeps serving every query until the new one is proven, so users never see a half-filled state.

Concretely, this means your retrieval layer needs a notion of an active index and one or more candidate indexes. Writes during the migration window fan out to both: the live index stays consistent for readers, and the candidate accumulates new-model vectors as the backfill runs. When the backfill completes and quality checks pass, you promote the candidate to active. If something looks wrong after cutover, you roll back by pointing reads at the old index again, which is still intact.

The hard part is coordination. You need to know which documents have been re-embedded, which are still pending, and which changed content mid-migration and must be re-processed. This is bookkeeping the content system should own, because it already tracks document identity, revisions, and change events. Sanity's Embeddings Index API and dataset embeddings keep vectors tied to the documents that produced them, so the platform knows what belongs in an index and can rebuild one deterministically. You are not manually reconciling a spreadsheet of IDs between a CMS and a bolted-on vector database at two in the morning.

Backfilling millions of documents without read downtime

A backfill is an embarrassingly parallel job, but the constraints are real: model provider rate limits, cost per embedding call, and the need to keep the live system fully responsive while it runs. The pattern that works is a throttled queue. Enumerate every document that needs a new-model vector, chunk the work, and process it at a rate the provider tolerates, writing results into the candidate index. Track completion per document so a crash resumes where it left off rather than starting over.

Freshness during the window is the subtle trap. A backfill of ten million documents can take hours, and content does not stop changing while it runs. If an editor updates a product description at hour three, and you already embedded that product at hour one, your candidate index now holds a stale vector. The answer is to subscribe to change events and re-enqueue any document that mutates during the migration, so the candidate converges on truth rather than a snapshot from when the job started.

This is where owning embeddings inside the content layer pays off. Because Sanity's embeddings are tied to content and the Content Lake exposes real-time subscriptions, a changed document is a signal the platform already emits. Functions can react to publish events and enrich or re-embed on the fly, so freshness is automatic instead of a separate stream you have to wire up, monitor, and hope stays in sync. The alternative, a standalone vector database, has no knowledge of your content's change events, so you build and operate that reconciliation plumbing yourself.

Cutover, verification, and rollback

Promotion should be a decision backed by evidence, not a hope. Before flipping reads to the candidate index, run an evaluation set: a fixed collection of representative queries with known good results. Compare retrieval quality between the old and new index on the same queries. If recall on your golden set holds or improves, promote. If it regresses, you caught the problem before a single user did, and the old index is still serving traffic untouched.

The cutover itself must be atomic from the reader's perspective. A single pointer, the active-index reference, moves from old to new. There is no moment where queries hit an index that is half old vectors and half new; readers see the old index fully, then the new index fully. Keep the old index warm for a defined cool-down period, long enough to be confident, so rollback is instant if a metric you did not think to test degrades in production.

Governance turns this from a risky script into a reviewable operation. Staging the re-embed, reviewing its results, and scheduling the cutover are the same disciplines you already apply to content changes. In Sanity, Content Releases and Studio-governed workflows let a model migration move through stage, review, and schedule like any other change, with an audit trail of who promoted what and when. That matters when a retrieval regression surfaces a week later and someone asks which model version shipped and who signed off on it.

Why the content layer should own embeddings

The recurring theme is ownership. When embeddings live in a separate vector database, that database is a silo. It has no concept of your document model, your revision history, your publish events, or your access controls. Every operation that spans content and vectors, re-embedding on a model change, invalidating on a content edit, enforcing who can see what, becomes glue code you write and maintain. That glue is where drift bugs breed, because the two systems can and will disagree about the state of the world.

Legacy CMSes stop at publishing and leave AI as an exercise for the reader, which is how teams end up bolting a vector store onto the side. Sanity is designed the other way around: AI is wired into the data model, the editor, and the delivery layer rather than added on top. Embeddings are a property of content, so they inherit content's identity, freshness, and permissions for free. A model change is a re-index of content you already govern, not a cross-system data migration you improvise.

This is what the Content Operating System framing means in practice. Model your business as structured content, automate everything including embedding maintenance through Functions and change subscriptions, and power anything downstream, whether that is semantic search, a RAG agent grounded through Sanity Context, or in-editor AI Assist. The embedding layer is not a separate product you integrate; it is the same content, represented for machines. Owning it there is what makes a model swap a scheduled operation instead of an incident, and what removes the entire class of bugs that come from two systems disagreeing about which vector belongs to which document.