Pinecone namespaces partition one index; they are not separate indexes

Namespaces: partitions, not indexes

What they are

A namespace is a partition of vectors inside one index. All vectors in an index share its dimension and metric; namespaces just scope operations. They are created automatically the first time you upsert with a namespace value. There is no create-namespace call.

index.upsert(vectors=[...], namespace="tenant-acme")
results = index.query(vector=[...], top_k=5, namespace="tenant-acme")

Querying without a namespace searches only the default (empty-string) namespace, not all namespaces. This is the number-one "my data disappeared" report: the vectors are there, in a namespace you are not querying.

When to use them

• Multitenancy. One index, one namespace per tenant. Same dimension for everyone, isolated reads and deletes.
• Versioning. docs-v1, docs-v2 during a re-embed; flip readers to the new namespace when it is fully populated, then delete the old one.
• Environment separation. dev, staging, prod in one index instead of three indexes (and three bills).

When not to

• Different embedding models or dimensions per tenant: namespaces share the index's dimension, so this needs separate indexes.
• Wildly different scale per tenant where you want per-tenant capacity: that is a pods conversation.

Rules for agents

1. Pass namespace explicitly on every data-plane call, or define one constant and use it everywhere. Implicit default-namespace behavior is how reads and writes silently miss each other.
2. delete(delete_all=True, namespace="tenant-acme") wipes one tenant without touching others. Double-check the namespace string; there is no undo.
3. describe_index_stats() breaks counts down per namespace; use it to confirm an ingest landed where you think it did.
4. Listing namespaces needs a recent API version (2025-10 or later on the list endpoint).

Pinecone's manage-namespaces guide states namespaces are created automatically as you upsert and that listing them requires the 2025-10 API version or later. The describe-index-stats pattern per namespace is documented in the same guide. Verified against live docs 2026-09-26.