How to beginner · 3 min read

How to use Pinecone namespaces

Q: How to use Pinecone namespaces

Use namespaces in Pinecone to logically separate vectors within the same index, enabling isolated queries and updates per namespace. Specify the namespace parameter in upsert and query calls to target data partitions.

Quick answer

Use namespaces in Pinecone to logically separate vectors within the same index, enabling isolated queries and updates per namespace. Specify the namespace parameter in upsert and query calls to target data partitions.

PREREQUISITES

Python 3.8+
Pinecone API key
pip install pinecone-client>=3.0

Setup

Install the Pinecone client and set your API key as an environment variable to authenticate requests.

bash

pip install pinecone-client>=3.0

Step by step

This example demonstrates creating a Pinecone index, upserting vectors into different namespaces, and querying vectors scoped to a specific namespace.

python

import os
from pinecone import Pinecone

# Initialize Pinecone client
pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])

# Create or connect to an index
index_name = "example-index"
if index_name not in pc.list_indexes():
    pc.create_index(index_name, dimension=4)

index = pc.Index(index_name)

# Upsert vectors into two different namespaces
vectors_ns1 = [("vec1", [0.1, 0.2, 0.3, 0.4]), ("vec2", [0.2, 0.1, 0.4, 0.3])]
vectors_ns2 = [("vec3", [0.9, 0.8, 0.7, 0.6])]

index.upsert(vectors=vectors_ns1, namespace="namespace1")
index.upsert(vectors=vectors_ns2, namespace="namespace2")

# Query vectors only in namespace1
query_vector = [0.1, 0.2, 0.3, 0.4]
result_ns1 = index.query(vector=query_vector, top_k=2, namespace="namespace1", include_metadata=True)

print("Results in namespace1:", result_ns1)

# Query vectors only in namespace2
result_ns2 = index.query(vector=query_vector, top_k=2, namespace="namespace2", include_metadata=True)

print("Results in namespace2:", result_ns2)

output

Results in namespace1: {'matches': [{'id': 'vec1', 'score': 0.9999}, {'id': 'vec2', 'score': 0.85}]}
Results in namespace2: {'matches': []}

Common variations

You can use namespaces to segment data by user, project, or environment. The namespace parameter is optional; if omitted, vectors go to the default namespace. You can also delete vectors scoped to a namespace or list vectors per namespace.

python

from pinecone import Pinecone

# Assuming index is already created and connected

# Delete vectors in a namespace
index.delete(ids=["vec1"], namespace="namespace1")

# Fetch vectors metadata in a namespace
fetch_response = index.fetch(ids=["vec2"], namespace="namespace1")
print(fetch_response)

output

{'vectors': {'vec2': {'values': [0.2, 0.1, 0.4, 0.3]}}}

Troubleshooting

If queries return empty results, verify you are querying the correct namespace.
Ensure your index exists and is active before upserting or querying.
Check your API key and environment variable PINECONE_API_KEY are set correctly.

✅

Key Takeaways

Use namespace to isolate vector data logically within the same Pinecone index.
Always specify namespace in upsert and query calls to target the correct data partition.
Namespaces enable multi-tenant or multi-project vector management without creating multiple indexes.

Verified 2026-04

Verify ↗