Working with Namespaces
1. Understanding Default Namespace
| Property | Behavior |
|---|
| Name | Empty string "" |
| Created | Implicit, always present |
| Used when | namespace param omitted |
2. Creating Implicit Namespaces
Example: Namespace on First Upsert
index.upsert(vectors=[{"id": "1", "values": [...]}],
namespace="tenant-99") # created if missing
| Rule | Detail |
|---|
| No explicit create API | Namespaces appear on first upsert |
| Name constraints | Alphanumeric + -_; max 128 chars |
3. Listing Namespace Statistics
Example: Per-Namespace Counts
stats = index.describe_index_stats()
for ns, info in stats["namespaces"].items():
print(ns or "(default)", info["vector_count"])
4. Querying Specific Namespace
Example: Scoped Query
res = index.query(vector=qv, top_k=5, namespace="tenant-a")
| Behavior | Detail |
|---|
| Default scope | Single namespace per query |
| Cross-namespace | Run N queries, merge client-side |
5. Upserting to Namespace
Example: Multi-Tenant Upsert
for tenant_id, vecs in tenant_data.items():
index.upsert(vectors=vecs, namespace=f"tenant-{tenant_id}")
6. Deleting Namespace Contents
| Goal | API |
|---|
| Empty namespace | index.delete(delete_all=True, namespace="x") |
| Remove namespace | index.delete_namespace("x") (serverless) |
7. Organizing Data with Namespaces
| Pattern | Use Case |
|---|
| Per-tenant | SaaS multi-tenancy; isolate user data |
| Per-language | Localized embeddings |
| Per-version | A/B testing embedding models |
| Per-environment | dev / staging / prod |
8. Managing Namespace Isolation
Warning: Namespaces share the index API key. For strong isolation between untrusted tenants, use separate indexes or projects.
| Concern | Mitigation |
|---|
| Accidental cross-tenant query | Enforce namespace at API gateway |
| Noisy neighbor | Pinecone isolates compute per index, not per namespace |
9. Querying Across Namespaces
Example: Merge Results
matches = []
for ns in ["a", "b", "c"]:
res = index.query(vector=qv, top_k=10, namespace=ns)
matches += res["matches"]
matches.sort(key=lambda m: m["score"], reverse=True)
top10 = matches[:10]
10. Optimizing Namespace Usage
| Tip | Reason |
|---|
| Group small tenants | Avoid 100K+ tiny namespaces |
| Use metadata for sub-grouping | Within a namespace |
| Drop empty namespaces | Reduce admin overhead |