- `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.

```python Python theme={null}
# 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"],
)
```

```shell curl theme={null}
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`

:::code-group
```bash title="cURL"
curl --request POST \
  --url https://{index_host}/namespaces/{namespace}/documents/update \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

```json title="202"
{
  "matched_records": 42
}
```
:::

## Authorizations

- `Authorization` (header, string, required) — Bearer authentication header of the form `Bearer <token>`.

## Path Parameters

- `namespace` (path, string, required) — The namespace to update documents in.

## Headers

- `X-Pinecone-Api-Version` (header, string, required) — Required date-based version header

## Body

- `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.

## Response

- `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.

## Related pages

- [Upsert documents](./database-2026-07-data-plane-upsert-documents.md)
- [Search documents](./database-2026-07-data-plane-search-documents.md)
- [Fetch documents](./database-2026-07-data-plane-fetch-documents.md)
- [List documents](./database-2026-07-data-plane-list-documents.md)
- [Delete documents](./database-2026-07-data-plane-delete-documents.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.