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 {meth}~pinecone.Index.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 {meth}~pinecone.Index.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

{meth}~pinecone.Index.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

{meth}~pinecone.Index.list_namespaces yields one {class}~pinecone.models.ListNamespacesResponse per page, following pagination automatically:

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

Each {class}~pinecone.models.NamespaceDescription has name and record_count fields.

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 {meth}~pinecone.Index.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

{meth}~pinecone.Index.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, {meth}~pinecone.Index.delete_namespace removes the namespace and all its vectors:

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

Describe a namespace

{meth}~pinecone.Index.describe_namespace returns metadata for a single namespace:

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

Create a namespace

Namespaces are created automatically when you first upsert into them. Use {meth}~pinecone.Index.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)

See also

• {doc}/how-to/vectors/upsert-and-query — upsert and query operations
• {class}~pinecone.Index — full data plane client reference
• {class}~pinecone.models.ListNamespacesResponse — list namespaces response model
• {class}~pinecone.models.NamespaceDescription — namespace metadata model