# 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"],
)
// npm install @pinecone-database/pinecone
import { Pinecone } from '@pinecone-database/pinecone';
// Reads PINECONE_API_KEY from the environment
const pc = new Pinecone();
const index = pc.index({
name: 'articles',
namespace: 'example-namespace',
});
// Patch specific documents by ID
await index.documents.update({
documents: [
{
_id: 'doc1',
title: 'Updated title',
},
{
_id: 'doc2',
_remove_fields: ['content'], // Reserved document key, sent as-is
},
],
});
// Apply the same patch to every document matching a metadata filter
const response = await index.documents.update({
filter: {
category: {
$eq: 'news',
},
},
setFields: {
category: 'archive',
},
removeFields: ['year'],
});
console.log(`Matched ${response.matchedRecords} documents`);
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/pinecone-io/go-pinecone/v7/pinecone"
)
func main() {
ctx := context.Background()
pc, err := pinecone.NewClient(pinecone.NewClientParams{
ApiKey: os.Getenv("PINECONE_API_KEY"),
})
if err != nil {
log.Fatalf("Failed to create Client: %v", err)
}
idx, err := pc.DescribeIndex(ctx, "articles")
if err != nil {
log.Fatalf("Failed to describe index: %v", err)
}
idxConnection, err := pc.Index(pinecone.NewIndexConnParams{
Host: idx.Host,
Namespace: "example-namespace",
})
if err != nil {
log.Fatalf("Failed to create IndexConnection: %v", err)
}
// Patch specific documents by ID
_, err = idxConnection.UpdateDocuments(ctx, &pinecone.UpdateDocumentsRequest{
Documents: []pinecone.Document{
{
"_id": "doc1",
"title": "Updated title",
},
{
"_id": "doc2",
"_remove_fields": []string{"content"},
},
},
})
if err != nil {
log.Fatalf("Failed to update documents: %v", err)
}
// Apply the same patch to every document matching a metadata filter
res, err := idxConnection.UpdateDocuments(ctx, &pinecone.UpdateDocumentsRequest{
Filter: map[string]interface{}{
"category": map[string]interface{}{
"$eq": "news",
},
},
SetFields: map[string]interface{}{
"category": "archive",
},
RemoveFields: []string{"year"},
})
if err != nil {
log.Fatalf("Failed to update documents: %v", err)
}
if res.MatchedRecords != nil {
fmt.Printf("Matched %d documents\n", *res.MatchedRecords)
}
}
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"]
}'
{
"matched_records": 42
}Update documents
Update documents in a namespace, either by ID with documents or in bulk with filter. You can’t use both in one request.
documents: Each entry is identified by_id. Fields you set get new values, fields listed in_remove_fieldsare removed, and other fields don’t change.filter: Appliesset_fieldsand/orremove_fieldsto every matching document. It can change only metadata fields. The response reportsmatched_records.
Setting a field that declares embed or sparse_embed re-embeds its text. Every request that does this is metered, including retries, and the response reports the tokens used in usage.embed_total_tokens. An update to an _id that doesn’t exist has no effect, but any text it sets is still embedded and metered. An index that embeds a field accepts at most 96 documents per request.
# 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"],
)
// npm install @pinecone-database/pinecone
import { Pinecone } from '@pinecone-database/pinecone';
// Reads PINECONE_API_KEY from the environment
const pc = new Pinecone();
const index = pc.index({
name: 'articles',
namespace: 'example-namespace',
});
// Patch specific documents by ID
await index.documents.update({
documents: [
{
_id: 'doc1',
title: 'Updated title',
},
{
_id: 'doc2',
_remove_fields: ['content'], // Reserved document key, sent as-is
},
],
});
// Apply the same patch to every document matching a metadata filter
const response = await index.documents.update({
filter: {
category: {
$eq: 'news',
},
},
setFields: {
category: 'archive',
},
removeFields: ['year'],
});
console.log(`Matched ${response.matchedRecords} documents`);
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/pinecone-io/go-pinecone/v7/pinecone"
)
func main() {
ctx := context.Background()
pc, err := pinecone.NewClient(pinecone.NewClientParams{
ApiKey: os.Getenv("PINECONE_API_KEY"),
})
if err != nil {
log.Fatalf("Failed to create Client: %v", err)
}
idx, err := pc.DescribeIndex(ctx, "articles")
if err != nil {
log.Fatalf("Failed to describe index: %v", err)
}
idxConnection, err := pc.Index(pinecone.NewIndexConnParams{
Host: idx.Host,
Namespace: "example-namespace",
})
if err != nil {
log.Fatalf("Failed to create IndexConnection: %v", err)
}
// Patch specific documents by ID
_, err = idxConnection.UpdateDocuments(ctx, &pinecone.UpdateDocumentsRequest{
Documents: []pinecone.Document{
{
"_id": "doc1",
"title": "Updated title",
},
{
"_id": "doc2",
"_remove_fields": []string{"content"},
},
},
})
if err != nil {
log.Fatalf("Failed to update documents: %v", err)
}
// Apply the same patch to every document matching a metadata filter
res, err := idxConnection.UpdateDocuments(ctx, &pinecone.UpdateDocumentsRequest{
Filter: map[string]interface{}{
"category": map[string]interface{}{
"$eq": "news",
},
},
SetFields: map[string]interface{}{
"category": "archive",
},
RemoveFields: []string{"year"},
})
if err != nil {
log.Fatalf("Failed to update documents: %v", err)
}
if res.MatchedRecords != nil {
fmt.Printf("Matched %d documents\n", *res.MatchedRecords)
}
}
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"]
}'
{
"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=["year"],
)
// npm install @pinecone-database/pinecone
import { Pinecone } from '@pinecone-database/pinecone';
// Reads PINECONE_API_KEY from the environment
const pc = new Pinecone();
const index = pc.index({
name: 'articles',
namespace: 'example-namespace',
});
// Patch specific documents by ID
await index.documents.update({
documents: [
{
_id: 'doc1',
title: 'Updated title',
},
{
_id: 'doc2',
_remove_fields: ['content'], // Reserved document key, sent as-is
},
],
});
// Apply the same patch to every document matching a metadata filter
const response = await index.documents.update({
filter: {
category: {
$eq: 'news',
},
},
setFields: {
category: 'archive',
},
removeFields: ['year'],
});
console.log(`Matched ${response.matchedRecords} documents`);
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/pinecone-io/go-pinecone/v7/pinecone"
)
func main() {
ctx := context.Background()
pc, err := pinecone.NewClient(pinecone.NewClientParams{
ApiKey: os.Getenv("PINECONE_API_KEY"),
})
if err != nil {
log.Fatalf("Failed to create Client: %v", err)
}
idx, err := pc.DescribeIndex(ctx, "articles")
if err != nil {
log.Fatalf("Failed to describe index: %v", err)
}
idxConnection, err := pc.Index(pinecone.NewIndexConnParams{
Host: idx.Host,
Namespace: "example-namespace",
})
if err != nil {
log.Fatalf("Failed to create IndexConnection: %v", err)
}
// Patch specific documents by ID
_, err = idxConnection.UpdateDocuments(ctx, &pinecone.UpdateDocumentsRequest{
Documents: []pinecone.Document{
{
"_id": "doc1",
"title": "Updated title",
},
{
"_id": "doc2",
"_remove_fields": []string{"content"},
},
},
})
if err != nil {
log.Fatalf("Failed to update documents: %v", err)
}
// Apply the same patch to every document matching a metadata filter
res, err := idxConnection.UpdateDocuments(ctx, &pinecone.UpdateDocumentsRequest{
Filter: map[string]interface{}{
"category": map[string]interface{}{
"$eq": "news",
},
},
SetFields: map[string]interface{}{
"category": "archive",
},
RemoveFields: []string{"year"},
})
if err != nil {
log.Fatalf("Failed to update documents: %v", err)
}
if res.MatchedRecords != nil {
fmt.Printf("Matched %d documents\n", *res.MatchedRecords)
}
}
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"]
}'
Authorizations
An API Key is required to call Pinecone APIs. Get yours from the console.
Body
- Per-ID patches
- By filter
Set either documents or filter. A filter needs a non-empty set_fields or remove_fields.
The list of partial document updates to apply. At most 1000 updates, or 96 on an index whose schema declares embed or sparse_embed. Mutually exclusive with filter, and with a non-empty set_fields or remove_fields.
maxItems states the general limit. A client that batches updates must size batches at 96 when any field of the index schema declares embed or sparse_embed.
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. Only metadata fields can be set here; every data field is refused, that is, vector fields, full-text-searchable text and embedded text, not only fields that declare embed or sparse_embed. Update those per ID with documents. 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" }
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
Usage information for the upsert_documents and update_documents operations.
Present only when the request embedded text, that is, when it wrote text to a field whose schema declares embed or sparse_embed. A request that embedded nothing returns no usage.
Show child attributes
Show child attributes
{ "embed_total_tokens": 24 }
Was this page helpful?