Working with namespaces¶

Namespaces are logical partitions within a Pinecone index. Vectors in different namespaces are completely isolated. A query in one namespace never returns results from another.

Common uses include separating data by customer, language, environment (staging vs. production), or data version.

The default namespace is the empty string "". All operations that accept a namespace parameter default to "" when namespace is omitted.

Upsert into a namespace¶

Pass namespace to upsert() to write vectors into a specific partition:

from pinecone import Pinecone, Vector

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

index.upsert(
    vectors=[
        Vector(id="product-001", values=[0.012, -0.087, 0.153, ...]),
        Vector(id="product-002", values=[0.045,  0.021, -0.064, ...]),
    ],
    namespace="catalog-us",
)

Vectors upserted without a namespace go into the default namespace "".

Query within a namespace¶

Pass namespace to query() to restrict the search to a single partition:

response = index.query(
    vector=[0.012, -0.087, 0.153, ...],
    top_k=10,
    namespace="catalog-us",
)
for match in response.matches:
    print(match.id, match.score)

Queries return response.namespace indicating which namespace was searched.

Query across multiple namespaces¶

query_namespaces() fans out queries in parallel and returns merged top results:

results = index.query_namespaces(
    vector=[0.012, -0.087, 0.153, ...],
    namespaces=["catalog-us", "catalog-eu", "catalog-ap"],
    metric="cosine",
    top_k=10,
)
for match in results.matches:
    print(match.id, match.score)

List namespaces¶

list_namespaces() yields one ListNamespacesResponse per page, following pagination automatically:

for page in index.list_namespaces():
    for ns in page.namespaces:
        print(ns.name, ns.record_count)

Each NamespaceDescription carries name, record_count, and size_bytes. When the namespace restricts which metadata fields are indexed, it also carries schema and indexed_fields.

size_bytes is approximate: data written before size tracking reads as 0, and recently deleted data may still be counted; compaction converges the value. 0 is also what the field reads as against a server older than 2026-07, so treat it as “no size reported” rather than “the namespace is empty”.

Filter by prefix to list a subset of namespaces:

for page in index.list_namespaces(prefix="catalog-"):
    for ns in page.namespaces:
        print(ns.name)

For a single page without automatic pagination, use list_namespaces_paginated():

page = index.list_namespaces_paginated(limit=50)
for ns in page.namespaces:
    print(ns.name, ns.record_count)

# Fetch the next page manually
if page.pagination and page.pagination.next:
    next_page = index.list_namespaces_paginated(
        limit=50,
        pagination_token=page.pagination.next,
    )

Delete all vectors in a namespace¶

delete() with delete_all=True removes every vector in a namespace without deleting the namespace itself:

index.delete(delete_all=True, namespace="catalog-staging")

Alternatively, delete_namespace() removes the namespace and all its vectors:

index.delete_namespace(name="catalog-staging")

Describe a namespace¶

describe_namespace() returns metadata for a single namespace:

ns = index.describe_namespace(name="catalog-us")
print(ns.name)
print(ns.record_count)
print(ns.size_bytes)

Pass __default__ to describe the namespace that requests address when they omit one:

ns = index.describe_namespace(name="__default__")

This operation is rate limited per index, independently of the other namespace operations. To describe more than one namespace, use list_namespaces() instead. It returns the same information for every namespace in a single request and is not subject to that limit. Fanning out describe_namespace calls will raise RateLimitError.

Create a namespace¶

Namespaces are created automatically when you first upsert into them. Use create_namespace() when you need to pre-create one with a custom schema or when you want to configure indexed metadata fields up front:

ns = index.create_namespace(
    name="catalog-us",
    schema={"fields": {"category": {"filterable": True}}},
)
print(ns.name, ns.record_count)

Every field listed in schema["fields"] must set filterable: True; filterable: False is not supported. To leave a field unindexed, omit it from fields entirely.

Omitting schema altogether is not the same as indexing every field. A namespace created without one inherits the index’s own metadata-index configuration, so if the index restricts which fields are indexed, the new namespace carries that restriction too. Supplying schema overrides the inherited configuration for that namespace alone.

Name rules¶

Namespace names must be ASCII, must not contain the NUL character, and must be 1-512 characters long. __default__ is reserved, since it names the namespace requests address when they omit a namespace, so it always exists and create_namespace rejects it. Names that break these rules raise PineconeValueError before any request is sent, so the offending value is reported back to you rather than to the server.