Updating and Deleting Documents in a Vector Index

Updating and deleting documents in a vector index means changing or removing the stored objects and their embeddings so search stops returning neighbours that no longer exist in the source of truth, and a missing delete path is why removed documents keep answering. Weaviate’s update documentation (as of September 2026) states that partial updates use PATCH, complete replacements use PUT, and updates that include vectorised text properties recalculate embeddings and reindex. Its delete documentation requires collection name plus identifying criteria (id or filters), and its vector-index concepts page states that cleanup asynchronously rebuilds the HNSW graph after deletes and updates while tombstoned objects remain connected until cleanup finishes. Google Vertex AI Vector Search update guides, DigitalOcean’s update-and-delete docs and practitioner upsert threads (extracted September 2026) cover the same mutate surface. Mutate mechanics sit under structures, trade-offs and limits because freshness is an index property, not a prompt instruction.

What does updating a vector index mean in RAG?

Updating a vector index means writing a new property set, a new vector, or both, for an object id the retriever already knows, so later queries see the revised neighbour. Weaviate distinguishes partial updates (PATCH / merge) from complete replacements (PUT / replace). Partial updates change specified properties and leave unspecified ones alone. Replacements provide a new object and drop properties you omit. For multi-tenancy collections, the tenant name is required on the mutate path as of Weaviate’s multi-tenant rules (v1.20+).

An update that never touches the vector leaves geometry stale when the text that should have been embedded changed. An update that re-embeds without deleting old ids can leave duplicates if ingest uses new ids for every version. Both shapes produce answers that look fluent and cite retired facts. The failure taxonomy for that symptom lives on stale index.

When should you use a partial update versus a full replace?

Use a partial update when a subset of fields changes and the rest must remain. Weaviate’s update docs (as of September 2026) describe PATCH-style merges for that case and note that if you update a previously vectorized property, Weaviate re-vectorizes and reindexes the object automatically. Use a full replace when the object should become exactly the payload you send, including deletions of properties that are no longer valid. Replacing with a smaller property set is also how Weaviate’s docs remove properties at object level when a dedicated property-delete API is not what you want.

Adding a brand-new property to the collection definition does not re-vectorize existing objects in Weaviate; only new objects pick up the new property for vectorisation until you update existing ones. That distinction matters when teams add a field and expect old chunks to magically re-embed. Plan an explicit backfill if old objects must include the new signal in their vectors.

When does a text change force a re-embed?

A text change forces a re-embed when the properties that feed the vectoriser change. Weaviate states that updates including a vector property recalculate the embedding unless updated text properties are configured to skip vectorisation, and that updating a previously vectorized property triggers automatic re-vectorisation and reindexing. If you supply an explicit vector in the update payload, that vector is stored as provided.

Skipping re-embed to save money leaves the index geometrically tied to old wording. The retriever then ranks neighbours by outdated meaning while the generator may see patched text from a side channel, or worse, still see old chunk text if the payload never landed. Re-embed cost belongs in pipeline cost; the correctness rule here is simpler: if meaning changed, the vector must change.

How does the delete path work, and what are tombstones?

Deletes remove objects by id or by a filter matching many ids. Weaviate’s delete docs (as of September 2026) show delete-by-id, delete-many with where filters, and delete-many by id sets using ContainsAny-style criteria. A configurable QUERY_MAXIMUM_RESULTS ceiling (default 10,000) limits how many objects a single delete query can remove; larger purges re-run the query. Collection name is required; tenant name is required when multi-tenancy is enabled.

On HNSW, deletion is not always instantly absent from the graph. Weaviate’s concepts page states that cleanup is an async process that rebuilds the HNSW graph after deletes and updates: prior to cleanup, objects are marked deleted but still connected; during cleanup, edges are reassigned and objects are deleted for good. That tombstone window is why a delete can succeed in the object store while a search still surfaces the neighbour for a short period, and why “we deleted it” incidents need both API success checks and search verification.

Why do removed documents keep being retrieved?

Removed documents keep being retrieved when delete was never called, when delete targeted the wrong id, when a new version was inserted under a new id without removing the old one, or when tombstones have not yet been cleaned from the graph. DigitalOcean’s verify step and Vertex AI’s remove-datapoints guidance both treat verification as part of the mutate workflow. OpenSearch forum threads in the live teardown set show practitioners chasing stale hits after partial updates that never dropped old vectors.

The operational fix is an idempotent ingest contract: stable document ids, upsert or delete-then-insert, and a scheduled reconcile that compares source ids to index ids. Change detection that decides when to call those APIs lives on incremental indexing. The incident shape when users notice first lives on the stale-index failure page.

What is upsert in a vector index?

Upsert inserts an object when the id is new and updates it when the id already exists, so re-running ingest converges instead of duplicating. Vertex AI’s upsert datapoints path and many store SDKs expose that call pattern explicitly. Weaviate’s create-or-update flows follow the same id-keyed idea even when the client method names differ between insert and update.

Upsert without stable ids is just insert. Teams that hash filenames with timestamps create endless duplicates and then blame “the index” for obsolete answers. Pick an id scheme from the source system primary key before the first production load.

Can you update metadata without changing the vector?

Yes, when the engine allows property patches that skip re-vectorisation for non-vectorised fields. Weaviate’s skip-vectorisation property settings and PATCH merges support metadata-only freshness for fields such as ACL flags or status enums that should not rewrite geometry. Vertex AI’s update embedding metadata and DigitalOcean’s metadata-only update paths document the same separation.

Metadata-only updates still matter for filtering: a document marked deprecated=true should disappear from filtered retrieval even if its vector is unchanged. If the status field is not filterable, the patch does nothing useful at search time. Coordinate metadata mutates with the filter schema on metadata filtering.

When do indexes need compaction or rebuild after mutates?

Indexes need compaction or rebuild when tombstones accumulate, when IVF centroids drift after heavy inserts, or when a store’s documentation says deleted space is reclaimed only on a maintenance pass. Vertex AI’s compaction notes and Weaviate’s async HNSW cleanup are two different product answers to “mutates leave structural debt.” Graph cleanup restores connectivity; centroid rebuild restores list quality; neither replaces calling delete in the first place.

Schedule maintenance from observed search freshness and storage growth, not from folklore. If deletes are rare and inserts dominate, invest in upsert id discipline first. If deletes are compliance-driven and frequent, verify cleanup lag against your legal removal SLA.

Vertex AI’s guides distinguish replacing an entire index, partially updating batch indexes, partially updating streaming indexes, upserting datapoints, updating embedding metadata and removing datapoints. That menu is the cloud form of the same mutate surface Weaviate expresses as PATCH, PUT, vector updates and delete-by-id or delete-many. DigitalOcean’s verify step after update and delete is the operational habit every stack needs: read the object back, then run a near-vector query that used to hit it and confirm absence or new content.

Consistency models matter when replicas serve search while cleanup runs. Weaviate’s replication and consistency concepts (extracted alongside the wave-3 docs set) discuss how distributed reads see updates; the practical RAG rule is to treat delete success and search absence as two checks, especially inside the tombstone window on HNSW. Compliance deletions should log both.

Batch delete ceilings exist to protect the cluster. Weaviate’s default maximum of 10,000 deleted objects per query means large GDPR-style purges are loops with verification, not one-shot calls. Plan those loops with rate limits and search spot-checks. A single huge filter delete that times out can leave a partial purge that looks successful in application logs.

Named vectors need per-vector updates when only one representation changed. Weaviate’s update docs (as of September 2026) show supplying vectors as a map for named-vector collections. Updating the wrong name leaves stale geometry in the representation you actually search.

A vector index stays honest only while updates re-embed what changed and deletes remove what left the source of truth. Weaviate’s PATCH versus PUT rules, automatic re-vectorisation on previously vectorized properties, filter deletes and async HNSW cleanup (as of September 2026) are the concrete mutate mechanics behind that claim. Wire stable ids, verify search after delete, and treat lingering neighbours as an index bug until proven otherwise.