skip to content

In Cloudflare Vectorize, how do insert() and upsert() differ for an existing vector ID, and when can a query see the write?

level: middleimportance: should knowfreq 26%

answer

  1. first write wins versus last
  2. replaced whole, never merged
  3. a mutationId, not the vectors
  4. processedUpToMutation in describe()
  5. batch into fewer, larger calls

basics

~20 s

insert() keeps an existing vector and skips the new one; upsert() replaces it in full, metadata included. Both return a mutationId and apply asynchronously, so a write is queryable seconds to minutes later, which describe() shows through processedUpToMutation.

solid answer

~40 s

With an ID already in the index, `insert()` leaves the stored vector alone and `upsert()` replaces values and metadata in full, with no merge, so a re-index must resend the metadata. Both, like `deleteByIds()`, resolve with a `mutationId`: the change is logged durably and applied by an asynchronous job, median under 30 seconds and p99 under 2 minutes since July 2026. `describe()` or `wrangler vectorize info` shows `processedUpToMutation`. Vectorize applies at most 200,000 vectors or 1,000 updates per job, so a bulk load should send large batches (up to 1,000 per binding call, 5,000 via the HTTP API), not one vector per call.

code

javascript · 16 lines
javascript
export async function reindexPage(env, page, chunks, staleIds) {
  const texts = chunks.map((c) => c.text);
  const { data } = await env.AI.run("@cf/baai/bge-base-en-v1.5", { text: texts });

  const vectors = chunks.map((c, i) => ({
    id: `${page.path}#${i}`,
    values: data[i],
    metadata: { product: page.product, language: page.language, url: page.url, title: page.title },
  }));

  const { mutationId } = await env.DOCS_INDEX.upsert(vectors);
  if (staleIds.length > 0) {
    await env.DOCS_INDEX.deleteByIds(staleIds);
  }
  return mutationId;
}

go deeper

for a junior

Recall that insert keeps an existing vector while upsert replaces it, and that a write shows up in queries only after a short delay.

for a middle

Explain the asynchronous path: a mutationId, a write-ahead log, a job that rebuilds the index, and processedUpToMutation in describe() as the way to see progress.

for a senior

Design a re-index that survives edits: deterministic IDs, full metadata on every upsert, deletes for vanished chunks and large batches that respect the job limits.

for a principal

Set the freshness promise the product can make: search reflects edits within about two minutes at p99, so flows that need instant results must not depend on Vectorize alone.

## Two writes with different rules for an existing ID Every Vectorize vector has a string `id`, up to 64 bytes, that should map back to what it was made from; for a docs site, a page and chunk such as `workers/limits#2`. The binding offers two ways to write vectors, and they differ only when that ID is already in the index: | Call | ID is new | ID already exists | |---|---|---| | `insert(vectors)` | stores the vector | keeps the stored vector; the new one is not written | | `upsert(vectors)` | stores the vector | replaces the stored vector **in full** | So `insert()` twice with the same ID leaves the first version, and `upsert()` twice leaves the last. Re-running an indexing job with `insert()` after a page was edited therefore changes nothing for the edited chunks, and the vector count stays the same. An indexing job that re-embeds edited pages uses `upsert()`. "In full" matters. An upsert does **not merge**: the stored vector, values and metadata alike, is replaced by what the call sends. A job that upserts new values without the `product`, `language` and `url` metadata leaves a vector with no metadata, which then drops out of every filtered query. A shrinking page is the other trap. If a page went from five chunks to three, upserting chunks 1 to 3 leaves chunks 4 and 5 in the index with stale text. The job has to call `deleteByIds(["page#4", "page#5"])` for IDs that no longer exist. ## Writes are asynchronous On current indexes, `insert()`, `upsert()` and `deleteByIds()` all resolve with `{ mutationId }`, not with the written vectors. The change is durable at that point, recorded in a write-ahead log, but not yet queryable: an asynchronous job reads the current index files, builds an updated index, writes it back and commits it. Since July 2026 the median time for a change to become queryable is under 30 seconds and the p99 under 2 minutes; some guide pages still say "a few seconds". Two consequences follow: - A test or an admin tool that writes a vector and queries it on the next line will often not find it. That is expected, not a bug. - To know whether a write is live, read the index's progress: `describe()` on the binding, or `wrangler vectorize info docs-search`, reports `vectorCount`, `processedUpToMutation` and `processedUpToDatetime`, and every change up to that mutation is reflected in queries. ## Batching decides how fast a bulk load finishes Vectorize groups pending changes into jobs of at most **200,000 vectors or 1,000 separate updates**, whichever comes first. The second number is the one that bites: 1. A job that inserts 250,000 vectors one call at a time creates 250,000 updates, so 250 jobs run one after another; the documentation estimates at least an hour. 2. The same vectors sent as 100 calls of 2,500 each fit in two or three jobs and are queryable within minutes. The per-call ceilings are **1,000 vectors** for a Workers binding call and **5,000** through the HTTP API. From a laptop or CI, `wrangler vectorize insert docs-search --file=embeddings.ndjson` (or `wrangler vectorize upsert`) reads newline-delimited JSON, one complete vector per line with a unique `id`, and sends it in batches set by `--batch-size`; the docs advise at most 5,000 vectors per file to stay under the Cloudflare API's global rate limit. A single upload can be up to 100 MB. ## What a re-indexing job should do - Use deterministic IDs (page path plus chunk number), so a re-run overwrites rather than duplicates. - Use `upsert()` and always send the complete metadata with the values. - Delete the IDs of chunks that no longer exist. - Send vectors in batches close to the per-call ceiling, not one per call. - Record the last `mutationId`, and check `processedUpToMutation` before declaring the new content searchable. - Remember that `deleteByIds()` is asynchronous too: a removed page can still appear in results until its mutation is applied, so a takedown that must be instant also needs a check in the search Worker. - Read a stored vector back with `getByIds()` when debugging a write; it returns the values and metadata exactly as the index holds them. Splitting pages into chunks, and how big a chunk should be, is retrieval design, covered with retrieval; this question stays with how Vectorize applies the writes.

  • An integration test inserts a vector and immediately queries for it, and fails about half the time; what is wrong?
    Nothing in Vectorize: writes are asynchronous, and `insert()` only returns a `mutationId`. The test should wait until `describe()` reports a `processedUpToMutation` at or past its write, or poll the query with a timeout, rather than query on the next line. Asserting on the returned `mutationId` checks the write was accepted.
  • Why does inserting 250,000 vectors one per call take so much longer than in 100 calls?
    Vectorize applies queued changes in jobs capped at 200,000 vectors or 1,000 separate updates. One call per vector makes 250,000 updates, so about 250 jobs run in turn, at least an hour by the docs' estimate. In 100 calls of 2,500 vectors the same load fits in two or three jobs and is queryable within minutes.

  • Uses insert() to refresh edited pages and wonders why nothing changes
  • Expects upsert() to merge new metadata into the stored metadata
  • Queries right after insert() and treats a miss as data loss
  • Reads upsert()'s result as the list of vectors now searchable
  • Writes one vector per call during a bulk load
  • Never deletes the IDs of chunks a page no longer has

Assumes Vectorize as of 2026-10-10: a July 2026 write-ahead-log change cut the median time to queryable to under 30 seconds and p99 to under 2 minutes.