Implement multitenancy

Implement multitenancy in Pinecone with one namespace per tenant on a serverless index to isolate customer data for SaaS RAG or semantic search apps.

Multitenancy is a software architecture where a single instance of a system serves multiple customers, or tenants, while ensuring data isolation between them for privacy and security.

This page shows you how to implement multitenancy in Pinecone using a document index with one namespace per tenant. For when to use namespaces, metadata filtering, or other approaches, see Design for multitenancy.

​

How it works

In Pinecone, an index is the highest-level organizational unit of data, where you define a schema for the documents stored in the index, such as the dimension and similarity metric of a dense_vector field.

Within an index, documents are stored in namespaces, and all upserts, searches, and other data read and write operations always target one namespace.

This structure makes it easy to implement multitenancy. For example, for an AI-powered SaaS application where you need to isolate the data of each customer, you would assign each customer to a namespace and target their writes and searches to that namespace:

In cases where you have different workload patterns (e.g., RAG and semantic search), you would use a different index for each workload, with one namespace per customer in each index:

​

Benefits

• Tenant isolation: In the serverless architecture, each namespace is stored separately, so using namespaces provides physical isolation of data between tenants. This reduces the risk of application bugs that could search the wrong tenant’s data.

• No noisy neighbors: Reads and writes always target a single namespace, so the behavior of one tenant doesn’t affect other tenants.

• No maintenance effort: Serverless indexes scale automatically based on usage; you don’t configure or manage any compute or storage resources.

• Cost efficiency: Search cost is based on namespace size (1 RU per 1 GB). With 100 tenants of 1 GB each, searching one tenant’s namespace costs 1 RU. Using metadata filtering in a single 100 GB namespace would cost 100 RUs for the same search, because it scans all data regardless of filters.

• Simple tenant offboarding: To offboard a tenant, you just delete the relevant namespace. This is a lightweight and almost instant operation.

Namespaces per serverless index vary by plan (100 on Starter to 1,000,000 on Enterprise). Pinecone can accommodate more for specific use cases. If your application needs a higher limit, contact Support.

​

Set up one namespace per tenant

1. Create a document index

   Serverless indexes separate storage from compute, scale automatically based on usage, and you pay only for the amount of data stored and operations performed. Combined with the isolation of tenant data using namespaces (next step), serverless indexes are ideal for multitenant use cases.

   To create a document index, set the cloud and region where the index should be deployed in deployment, and declare the fields to index in schema. This example declares one dense_vector field, embedding, with 8 dimensions and the cosine metric:

   Python

   from pinecone import Pinecone, SchemaBuilder
   
   pc = Pinecone(api_key="YOUR_API_KEY")
   
   schema = (
       SchemaBuilder()
         .add_dense_vector_field(name="embedding", dimension=8, metric="cosine")
         .build()
   )
   
   pc.indexes.create(
       name="multitenant-app",
       deployment={"deployment_type": "managed", "cloud": "aws", "region": "us-east-1"},
       schema=schema,
   )
   

   Before you upsert, wait for the index to be ready. The Python SDK waits by default.

2. Isolate tenant data

   In a multitenant solution, you need to isolate data between tenants. To achieve this in Pinecone, use one namespace per tenant. In the serverless architecture, each namespace is stored separately, so this approach ensures physical isolation of each tenant’s data.

   To create a namespace for a tenant, specify the namespace when you first upsert the tenant’s documents. For example, the following code upserts documents for tenant1 and tenant2 into the multitenant-app index:

   Python

   from pinecone import Pinecone
   
   pc = Pinecone(api_key="YOUR_API_KEY")
   
   # To get the unique host for an index,
   # see https://docs.pinecone.io/guides/indexes/target-an-index
   index = pc.index(host="INDEX_HOST")
   
   index.documents.upsert(
       namespace="tenant1",
       documents=[
           {"_id": "A", "embedding": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]},
           {"_id": "B", "embedding": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]},
           {"_id": "C", "embedding": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]},
           {"_id": "D", "embedding": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]},
       ],
   )
   
   index.documents.upsert(
       namespace="tenant2",
       documents=[
           {"_id": "E", "embedding": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]},
           {"_id": "F", "embedding": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]},
           {"_id": "G", "embedding": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]},
           {"_id": "H", "embedding": [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8]},
       ],
   )
   

   When upserting additional documents for a tenant, or when updating or deleting documents for a tenant, specify the tenant’s namespace. For example, the following code updates the embedding field of document A in tenant1:

   Python

   from pinecone import Pinecone
   
   pc = Pinecone(api_key="YOUR_API_KEY")
   
   # To get the unique host for an index,
   # see https://docs.pinecone.io/guides/indexes/target-an-index
   index = pc.index(host="INDEX_HOST")
   
   index.documents.update(
       namespace="tenant1",
       documents=[
           {"_id": "A", "embedding": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]},
       ],
   )
   
3. Search tenant data

   In a multitenant solution, you need to ensure that the searches of one tenant don’t affect the experience of other tenants. To achieve this in Pinecone, target each tenant’s searches at the namespace for the tenant.

   For example, the following code searches only tenant2 for the 3 documents that are most similar to an example query vector:

   Python

   from pinecone import Pinecone
   
   pc = Pinecone(api_key="YOUR_API_KEY")
   
   # To get the unique host for an index,
   # see https://docs.pinecone.io/guides/indexes/target-an-index
   index = pc.index(host="INDEX_HOST")
   
   results = index.documents.search(
       namespace="tenant2",
       top_k=3,
       score_by=[
           {
               "type": "dense_vector",
               "fields": ["embedding"],
               "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7],
           }
       ],
   )
   
   for match in results.matches:
       print(match._id, match._score)
   

​

Offboard a tenant

In a multitenant solution, you also need it to be quick and easy to offboard a tenant and delete all of its documents. To achieve this in Pinecone, you just delete the namespace for the specific tenant.

For example, the following code deletes the namespace and all documents for tenant1:

Python

from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

# To get the unique host for an index,
# see https://docs.pinecone.io/guides/indexes/target-an-index
index = pc.index(host="INDEX_HOST")

index.delete_namespace(name="tenant1")

​

Alternative: Metadata filtering

When tenant isolation isn’t a strict requirement, or when you need to search across multiple tenants simultaneously, you can store all documents in a single namespace and use metadata fields to assign documents to tenants. At search time, you can then filter by metadata.

This approach has significant performance and cost tradeoffs compared to using namespaces:

• Higher search costs: Searches scan the entire namespace regardless of filters, so you pay for scanning all tenants’ data even though results are filtered to one tenant.
• Slower performance: Large namespaces increase search latency, and large filters add network overhead on the request side.
• Filter size limits: Each $in or $nin operator is limited to 10,000 values. Exceeding this limit will cause requests to fail. See Metadata filter limits.

Anti-pattern: Avoid filtering by large lists of individual user IDs. Instead, use access control groups (organization, project, role), namespaces, or post-filter client-side (for semantic search).

For detailed guidance on choosing between namespaces and metadata filtering, see Design for multitenancy.

For more background on this approach, see Multitenancy in Vector Databases.