Update documents

• documents: Each update is identified by its _id. Any other fields set new values for those fields, and fields listed in _remove_fields are 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 by set_fields and/or remove_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 reports matched_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

• X-Pinecone-Api-Version (header, string, required) — Required date-based version header
• namespace (path, string, required) — The namespace to update documents in.

• documents (body, object[]) — The list of partial document updates to apply. Mutually exclusive with filter, and with a non-empty set_fields or remove_fields.
• filter (body, object) — 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.
• set_fields (body, object) — 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.
• remove_fields (body, 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.

• 202 — The update request was successfully accepted.
• 400 — Bad request. The request body included invalid request parameters.
• 401 — Unauthorized. Possible causes: missing or invalid API key.
• 4XX — An unexpected error response.
• 5XX — An unexpected error response.