Fetch data

Retrieve Pinecone documents from a namespace in a document index by ID or metadata filter to inspect their fields and metadata.

This page shows you how to fetch documents by ID or by metadata filter from a namespace in a document index. For a legacy vector index, see Fetch vectors.

You can also fetch data in the Pinecone console.

Fetches consume read units (RUs). See Understand Pinecone cost for how fetch cost is calculated.

​

Fetch documents

In an index with a document schema, fetch documents by ID or by metadata filter. A request specifies exactly one of ids or filter, and can name up to 1,000 IDs. include_fields selects which fields come back, and omitting it returns all of them.

​

Fetch documents by ID

To fetch specific documents, pass their IDs:

Python

# pip install --upgrade pinecone
from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

# To get the unique host for an index,
# see https://docs.pinecone.io/guides/indexes/target-an-index
index = pc.index(host="INDEX_HOST")

response = index.documents.fetch(
    namespace="articles",
    ids=["doc-1", "doc-2"],
    include_fields=["title", "body"],
)

The response keys each document by its ID:

{
    "documents": {
        "doc-1": { "_id": "doc-1", "title": "First", "body": "First body text." },
        "doc-2": { "_id": "doc-2", "title": "Second", "body": "Second body text." }
    },
    "namespace": "articles",
    "usage": { "read_units": 1, "egress_bytes": 98 }
}

​

Fetch documents by metadata

To fetch every document matching a metadata filter expression, pass a filter instead of ids:

Python

# Connect to an index as shown above.
response = index.documents.fetch(
    namespace="articles",
    filter={"category": {"$eq": "news"}},
    include_fields=["*"],
)

A filtered fetch returns one page at a time, holding 100 documents by default and 10,000 at most. When more documents match, the response carries a pagination.next token. Pass it back as pagination_token to get the next page, and stop when the response has no pagination token. In the REST API, limit sets the page size.

Unlike a filtered update or delete, a filtered fetch accepts the text-match operators $match_phrase, $match_all, and $match_any on full-text fields, so you can fetch documents by their text without running a search.

For the full request and response schema, see Fetch documents.

​

Data freshness

Pinecone is eventually consistent, so there can be a slight delay before new or changed documents are visible to queries. You can view index stats to check data freshness.