## TL;DR

Pass namespace explicitly on every data-plane call, or define one constant and use it everywhere. 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 use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

## Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

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