# 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).