How do Pinecone's upsert() and update() differ when changing one metadata field?

## Two write paths, different semantics Pinecone gives you two ways to change an existing record, and they differ in exactly the way PUT differs from PATCH in an HTTP API. **`upsert()` — full replace.** The record you send *is* the record afterwards. Fields you omit are not merged with what was stored; they are simply absent from the new record. That is a feature for ingestion (re-running a job over a source produces a clean, deterministic state) and a hazard for edits (a partial payload silently drops data). **`update()` — partial patch.** `index.update(id=..., set_metadata={...}, values=[...], namespace=...)` touches only what you name. `set_metadata` writes the given keys and leaves every other metadata key intact. Omit `values` and the stored embedding is untouched. ## Why the difference matters in practice Consider a document chunk whose metadata is `{"doc": "doc-1", "page": 4, "tenant": "acme", "status": "active"}` and you want `status` to become `archived`. With `update` it is one small request naming one key. The embedding never leaves your process, the other three keys survive, and there is nothing to re-read first. With `upsert` you must reconstruct the entire record. That means either keeping the original vector around (a few kilobytes per record you now have to carry through your code path) or fetching it back with `include_values=True`, and merging the metadata yourself. If you skip that merge and send only `{"status": "archived"}`, you have just destroyed `doc`, `page` and `tenant` — and the loss is silent. Queries keep working; the filters that depended on `tenant` simply stop matching. This is the classic bug in this area, and it shows up as "our tenant filter suddenly returns nothing for old records." ## Two sharp edges on update **It does not insert.** `update` is an operation on an existing record. Point it at an id that is not in the namespace and no record appears — you do not get a new record and you should not rely on an error to tell you. That makes it wrong for any "write if missing" path: for create-or-modify semantics you want `upsert`, and if you must know whether the record existed, `fetch` first. **It cannot remove a metadata key.** `set_metadata` sets keys. There is no unset form, so a field you want gone stays gone only if you rewrite the whole record with `upsert`, omitting it. Teams that expect to prune metadata should design for that: either use a sentinel value they can filter on, or accept a periodic full re-upsert from the system of record. ## Choosing between them A workable rule: - **Ingestion and re-ingestion → `upsert`.** You have the full record in hand, deterministic ids make it idempotent, and full replacement is exactly the semantics you want when the source changed. - **Small mutations to existing records → `update`.** Flags, lifecycle status, counters, ownership changes, anything where the embedding is unchanged. - **Re-embedding after a model change → `upsert`** (you are rewriting values and probably metadata anyway) — unless the change is purely the vector for a subset, where `update(values=...)` is leaner. ## Consistency and ordering Both are writes, so both are subject to the same visibility delay before queries and fetches reflect them; do not read back immediately and assert. And neither gives you compare-and-set: two concurrent writers patching the same record produce last-writer-wins, with no version check and no conflict error. If two pipelines can touch the same id, either partition ownership so only one does, or serialise the mutation upstream. There is no transaction spanning multiple records either — a batch upsert is not atomic across the batch, so partial visibility during a large write is normal and your readers must tolerate it. ## What an interviewer is checking That you know a vector database record is not a row you can freely `SET column = value` on, that you can name the operation that patches versus replaces, and that you have internalised the failure mode: the destructive one is quiet, and it destroys the metadata your filters depend on.