Skip to main content
A new embedding model enters as an evaluation space of your ingestion plugin. Documents ingested from then on get vectors in it, but the ones you already have do not. A backfill fills that space for a Corpus’s past documents, at low priority, and a promotion then makes search use it. You can also backfill a second plugin selected in ingestion.evaluation; it creates its own segments from each document’s canonical Parts. See Configuration for the selection and Upgrade or switch a plugin for promotion.

Prerequisites

  • A version of your ingestion plugin whose manifest declares the new space, activated with it as evaluation and the current one as served (see Upgrade or switch a plugin). For another model of the same plugin, it must preserve that plugin’s stored segments. A second evaluation plugin can use different cuts.
  • A key of the Organization that owns the Corpus with the actions plugins:admin, operations:read (to follow the backfill) and operations:write (to pause, resume or cancel it), in QUIVR_OPERATOR_KEY, and the Corpus id in CORPUS_ID.
  • Optional: an input_price on the new space in the manifest (usd_per_million_tokens), so the estimate shows a cost. Without it the cost is unknown.

Steps

1

Estimate it

A dry run is required. It counts the documents to fill and estimates how long it takes and what it costs:
registration_id selects any ingestion registration in the active plan; omit it to use the default ingestion plugin. spaces defaults to that plugin’s evaluation spaces; name them in spaces to choose. For a second plugin, documents of the source formats assigned to it in the pinned plan are in scope, including documents without that plugin’s segments. Existing segments of that owner are reused. Name its primary space explicitly when preparing an owner switch. If the owner has no segments yet, the dry run estimates segments and tokens from the current served projection; completion counters use the new owner’s actual cuts. To fill only part of the Corpus, add accepted_after or accepted_before: the time Quivr accepted each document. estimated_seconds uses the deployment’s backfill.rate, or the recent throughput when it is slower (duration_basis).
2

Start it

Send the same body with dry_run set to false. When confirmation_required is true, because the cost exceeds backfill.max_cost_without_confirmation, add "confirm_cost": true:
The answer is an Operation, Quivr’s record of a long-running administrative task. The same key and body return the same Operation. Keep its id:
3

Follow it

counters shows versions_in_scope, versions_done, versions_skipped and segments. One backfill of a Corpus runs at a time: another one is refused with 409 backfill_in_progress until it ends. Pause, resume or cancel it with POST /v0/operations/{id}/pause, /resume or /cancel, each with an idempotency_key body. A paused or restarted backfill continues after its checkpoint and never fills a document twice.
4

Promote the space

When the Operation is succeeded, make search use the new space:
The promotion returns 202 Accepted and an Operation with a Location header. Read GET /v0/operations/{operation_id} with plugins:admin until it succeeds or fails. Imports continue during the coverage check. On success, admin.served_space_id names the selected space and admin.previous_space_id names the one it replaced.A promotion applies to this space’s owner across the deployment. Other plugins keep their served spaces. Its Operation fails with coverage_incomplete while some Corpus has current documents segmented by this owner without a vector in the space: backfill those Corpora first. {"force": true} promotes anyway, and the documents without a vector drop out of semantic results until a backfill fills them.After the promotion Operation succeeds, move meaning alerts to the new space: alerts that match by vector meaning return not_ready until you do.

Check it worked

The new space is served and covers every segment produced by its owner. Semantic hits name it in vector_space_id.

Fill and promote another plugin

To change the plugin that produces segments and vectors, follow Try and switch a vector model. That guide owns the second-plugin setup, deployment-wide fill, comparison, registration activation, alert migration and rollback. The space promotion above changes models within one owner; it does not select a different plugin for a format.

Go back to the previous model

Promote the former space the same way. It stayed an evaluation space and kept its vectors, so search uses it again after the promotion Operation succeeds. Then move meaning alerts back to it. A promotion survives restarts, activations and rollbacks while the ingestion plugin enables both spaces. Once a plugin version stops declaring one of them, its own spaces settings decide again.

How a backfill runs

  • It runs on its own worker queue, with at most backfill.concurrency Versions in flight per step (default four), paced at backfill.rate Versions per second (see Configuration), so live ingestion keeps its capacity.
  • It is pinned to the Pipeline Plan active when it started, like other work, and fails with pinned_plugin_unavailable or pinned_plan_stopped rather than moving to another plugin version.
  • On its first step, the Corpus’s search index starts carrying the new space, so documents ingested from then on get their vectors from live ingestion. The backfill fills only the documents that already had theirs.
  • It creates no new Version and no content event in the change feed. Documents outside its window are not touched.
  • If this plugin already has stored segments, a document it now cuts differently is skipped and counted as skipped_segmentation_differs: rebuild the Corpus to re-cut it (see Write an ingestion plugin). A refusal by the plugin is counted as skipped_ingestion_refused, and a document the plugin cannot embed within its deadline as skipped_plugin_deadline. Rerun the backfill to try skipped documents again.

Troubleshooting