Update documents
Apply partial updates to documents in a namespace. Documents are selected either per ID with documents, or in bulk with filter.
documents: Each update is identified by its_id. Any other fields set new values for those fields, and fields listed in_remove_fieldsare removed from the document. Fields that are not mentioned are left unchanged. Updates to a document that does not exist are accepted but have no effect.filter: The same patch is applied to every document matching a metadata filter expression. The patch is given byset_fieldsand/orremove_fields, at least one of which must be specified. Text-match operators ($match_phrase,$match_all,$match_any) are not supported in a filtered update; they are only supported in search. The response reportsmatched_records, the number of documents the filter matched.
documents and the by-filter fields (filter, set_fields, remove_fields) are mutually exclusive.
# pip install --upgrade pinecone
import os
from pinecone import Pinecone
pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
index = pc.Index(name="articles")
NAMESPACE = "example-namespace"
# Patch specific documents by ID
index.documents.update(
namespace=NAMESPACE,
documents=[
{"_id": "doc1", "title": "Updated title"},
{"_id": "doc2", "_remove_fields": ["content"]},
],
)
# Apply the same patch to every document matching a metadata filter
index.documents.update(
namespace=NAMESPACE,
filter={"category": {"$eq": "news"}},
set_fields={"category": "archive"},
remove_fields=["year"],
)PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io"
# EXAMPLE REQUEST 1: Patch specific documents by ID
curl "https://$INDEX_HOST/namespaces/__default__/documents/update" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"documents": [
{ "_id": "doc1", "title": "Updated title" },
{ "_id": "doc2", "_remove_fields": ["content"] }
]
}'
# EXAMPLE REQUEST 2: Update by metadata filter
curl "https://$INDEX_HOST/namespaces/__default__/documents/update" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"filter": { "category": { "$eq": "news" } },
"set_fields": { "category": "archive" },
"remove_fields": ["year"]
}'POST /namespaces/{namespace}/documents/update
{
"matched_records": 42
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
},
"status": 400
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
},
"status": 400
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
},
"status": 400
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
},
"status": 400
}Authorizations
Section titled “Authorizations”Api-KeystringrequiredAn API Key is required to call Pinecone APIs. Get yours from the console.
Headers
Section titled “Headers”X-Pinecone-Api-VersionstringrequiredRequired date-based version header
Path Parameters
Section titled “Path Parameters”namespacestringrequiredThe namespace to update documents in.
documents?object[]The list of partial document updates to apply. Mutually exclusive with filter, and with a non-empty set_fields or remove_fields.
Show child attributes
_idstringrequiredThe unique identifier of the document to update.
Required string length: 1 - 512
_remove_fields?string[]A list of field names to delete from the document.
filter?objectA metadata filter expression selecting the documents to patch with set_fields and remove_fields. Must not be empty; an empty filter is rejected rather than matching every document. Text-match operators ($match_phrase, $match_all, $match_any) are not supported here, since documents are selected on metadata alone. Mutually exclusive with documents.
set_fields?objectThe fields to set on every document matching filter, and the values to set them to. When non-empty, only valid together with filter; an empty object asks for no change and is ignored.
remove_fields?string[]The names of the fields to remove from every document matching filter. When non-empty, only valid together with filter; an empty list asks for no change and is ignored.
Response
Section titled “Response”202 — The update request was successfully accepted.
The response for the update_documents operation.
matched_records?integerThe number of documents that matched filter when the update was accepted. Only returned for a filtered update; a per-ID update reports no count. The patch is applied asynchronously, so this is a point-in-time count rather than a guarantee of the number of documents ultimately patched.
Example: 42