Skip to main content
This page shows you how to update documents in a namespace of a document index. You can patch fields on a document by ID, or patch metadata fields across every document matching a filter. To replace whole documents, use the upsert operation instead. For a legacy vector index, see Update vectors.
Updates consume write units (WUs). See Understand Pinecone cost for how update cost is calculated.

​
Update documents

In an index with a document schema, upsert replaces the whole document for a given _id. To change individual fields instead, use the documents update operation, which leaves the fields you don’t mention unchanged. To patch specific documents, send one entry per _id. Include the fields you want to set, and name any fields to drop in _remove_fields. Both schema-declared fields and metadata fields can be set or removed this way:
To apply the same patch to every document matching a metadata filter expression, send filter with set_fields, remove_fields, or both:
The response reports how many documents matched the filter:
For the full request and response schema, see Update documents.

​
Limitations

  • By-ID requests: Each request can patch up to 1,000 documents, or 96 when the schema declares embed or sparse_embed (even a metadata-only patch). See Update limits.
  • By-filter requests: set_fields and remove_fields both accept metadata fields only, and reject a field declared in the schema with a 400. A by-filter update applies one value to every matched document, which would leave vector and full-text-searchable fields identical across the whole match set. To change a schema-declared field, patch each document by ID.
  • Text-match filters: A by-filter update rejects text-match operators ($match_phrase, $match_all, $match_any) with a 400. To update documents by text match, search for them first and patch the IDs the search returns.
This operation ignores the dry_run parameter that Update by metadata on the legacy Vectors API supports. A dry_run request returns 202 with a matched_records count and applies the update anyway. It also accepts unrecognized parameters rather than rejecting them, so check the parameter names before you send a request you can’t undo.

​
Data freshness

Pinecone is eventually consistent, so there can be a slight delay before updates are visible to queries. You can use log sequence numbers to check whether an update request has completed.

​
See also