# 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=["content"],
)
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": ["content"]
}'
{
"matched_records": 42
}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=["content"],
)
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": ["content"]
}'
{
"matched_records": 42
}# 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=["content"],
)
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": ["content"]
}'
Authorizations
Headers
Required date-based version header
Path Parameters
The namespace to update documents in.
Body
- Per-ID patches
- By filter
- By filter
The request for the update_documents operation. Either documents or filter must be specified, and they are mutually exclusive. A filter must be accompanied by a non-empty set_fields and/or remove_fields.
An empty set_fields or remove_fields asks for no change, so it does not make a request by-filter: it is ignored, and a request that also has documents is still a valid per-ID update.
A by-filter patch is checked against the index schema the same way a per-ID patch is: a value must match the type its field declares, a field cannot be both set and removed, and a required field cannot be removed.
The list of partial document updates to apply. Mutually exclusive with filter, and with a non-empty set_fields or remove_fields.
1 - 1000 elementsShow child attributes
Show child attributes
A 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.
{ "category": { "$eq": "news" } }
The 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.
Show child attributes
Show child attributes
{ "category": "archive" }
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.
["content"]
Response
The update request was successfully accepted.
The response for the update_documents operation.
The 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.
42
Was this page helpful?