Fetch, update, delete, and list documents

Search returns the best matches. The methods on this page work on documents you can name: by ID, by ID prefix, or by a filter on their fields. The examples use the article-search index from Declare a schema and upsert documents, with category and year as metadata.

Updates and deletes apply asynchronously, like upserts: the call returns once the server accepts the change, and a read made right afterward may still show the old documents.

Fetch documents

fetch() takes either ids or filter. Fetching by ID returns response.documents, a dict from ID to Document. An ID that does not exist is left out rather than raising an error:

from pinecone import Pinecone

pc = Pinecone(api_key="your-api-key")
index = pc.index("article-search")

response = index.documents.fetch(
    namespace="articles-en",
    ids=["article-101", "article-102"],
    include_fields=["title", "year"],
)
for doc_id, doc in response.documents.items():
    print(doc_id, doc.title, doc.year)

Unlike search, fetch returns every stored field when you omit include_fields.

A fetch by filter returns every matching document a page at a time. Read each page, then pass response.pagination.next back as pagination_token until pagination is None:

pagination_token = None
while True:
    response = index.documents.fetch(
        namespace="articles-en",
        filter={"category": {"$eq": "history"}},
        pagination_token=pagination_token,
    )
    for doc_id, doc in response.documents.items():
        print(doc_id, doc.title)
    if response.pagination is None:
        break
    pagination_token = response.pagination.next

Filters for fetch take the same operators as search filters, including the text-match operators on full-text fields; see Filter the search.

Update documents

update() changes only the fields you name and keeps the rest. An upsert, by contrast, replaces the whole document, so use update to change one field without resending the vector. Patch documents by ID with documents; in each patch, every key other than _id sets a field, and _remove_fields lists fields to drop:

index.documents.update(
    namespace="articles-en",
    documents=[
        {"_id": "article-101", "category": "engineering"},
        {"_id": "article-102", "_remove_fields": ["year"]},
    ],
)

To set or remove the same fields on every document that matches a filter, pass filter with set_fields, remove_fields, or both:

response = index.documents.update(
    namespace="articles-en",
    filter={"year": {"$lt": 2020}},
    set_fields={"category": "archive"},
)
print(response.matched_records)

A patch naming an ID that does not exist does nothing. To remove a field, list it in _remove_fields or remove_fields; setting it to None fails with a 400. Changing the text of an embed or sparse_embed field has Pinecone embed the new text, and response.usage reports the tokens embedded.

Delete documents

delete() takes exactly one of ids, filter, or delete_all=True. Deleting an ID that does not exist is not an error.

index.documents.delete(namespace="articles-en", ids=["article-101"])

response = index.documents.delete(
    namespace="articles-en",
    filter={"category": {"$eq": "archive"}},
)
print(response.matched_records)

index.documents.delete(namespace="drafts", delete_all=True)

The filters of update and delete reject the text-match operators ($match_phrase, $match_all, $match_any), so select documents by metadata or by ID. For a filtered update or delete, matched_records counts the documents that matched when the server accepted the request; it is None for the other forms.

List document IDs

list() returns the IDs in a namespace, sorted, as a Paginator that fetches pages as you iterate. Give your IDs a shared prefix, such as article-, and you can list one group of documents without a filter:

for record in index.documents.list(namespace="articles-en", prefix="article-"):
    print(record.id)

Each item carries only id. Pass a batch of IDs to fetch to read their fields. To checkpoint a long walk, iterate .pages() and save each page’s pagination_token, then resume later with list(..., pagination_token=token). See Pagination for the paginator’s other methods.