Operates Pinecone serverless indexes via pinecone-client: batch upsert, metadata filters, namespaces, and dense-plus-sparse hybrid queries. Use when production RAG, semantic search, or recommendations need a managed auto-scaling vector store. Not for local Chroma, FAISS-only kNN, or self-hosted Weaviate.
Operates Pinecone serverless indexes via pinecone-client: batch upsert, metadata filters, namespaces, and dense-plus-sparse hybrid queries. Use when production RAG, semantic search, or recommendations need a managed auto-scaling vector store. Not for local Chroma, FAISS-only kNN, or self-hosted Weaviate.
Pinecone is a fully managed, auto-scaling vector database with hybrid search (dense + sparse), metadata filtering, and namespaces. p95 latency <100ms. Use for production RAG, recommendation systems, or semantic search at scale.
When to Use
Use Pinecone when:
You need a managed, serverless vector database without infrastructure overhead
Building production RAG applications requiring <100ms p95 query latency
Auto-scaling to billions of vectors is required
You need hybrid search (dense + sparse vectors) in a single query
Multi-tenant isolation via namespaces is needed
99.9% uptime SLA is a requirement
Use alternatives instead:
Chroma: Self-hosted, open-source, local development
FAISS: Offline, pure similarity search, no metadata filtering
Weaviate: Self-hosted with more features (graph relationships, modules)
# Upsert into a namespace
index.upsert(
vectors=[{"id": "vec1", "values": [0.1, 0.2]}],
namespace="user-123"
)
# Query a specific namespace
results = index.query(
vector=[0.1, 0.2],
namespace="user-123",
top_k=5
)
# List all namespaces and their stats
stats = index.describe_index_stats()
print(stats['namespaces'])
# Delete by ID
index.delete(ids=["vec1", "vec2"])
# Delete by filter
index.delete(filter={"category": "old"})
# Delete all vectors in a namespace
index.delete(delete_all=True, namespace="test")
# Delete all vectors in the index
index.delete(delete_all=True)
10. Index management
# List all indices
indexes = pc.list_indexes()
# Describe a specific index
index_info = pc.describe_index("my-index")
print(index_info)
# Get index statistics
stats = index.describe_index_stats()
print(f"Total vectors: {stats['total_vector_count']}")
print(f"Namespaces: {stats['namespaces']}")
# Delete an index (irreversible)
pc.delete_index("my-index")
11. LangChain integration
from langchain_pinecone import PineconeVectorStore
from langchain_openai import OpenAIEmbeddings
# Create vector store from documents
vectorstore = PineconeVectorStore.from_documents(
documents=docs,
embedding=OpenAIEmbeddings(),
index_name="my-index"
)
# Similarity search
results = vectorstore.similarity_search("query", k=5)
# With metadata filter
results = vectorstore.similarity_search(
"query",
k=5,
filter={"category": "tutorial"}
)
# As a retriever
retriever = vectorstore.as_retriever(search_kwargs={"k": 10})
12. LlamaIndex integration
from llama_index.vector_stores.pinecone import PineconeVectorStore
from llama_index.core import StorageContext, VectorStoreIndex
# Connect to Pinecone
pc = Pinecone(api_key="YOUR_KEY")
pinecone_index = pc.Index("my-index")
# Create vector store
vector_store = PineconeVectorStore(pinecone_index=pinecone_index)
# Use in LlamaIndex
storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)
Examples
Full RAG pipeline (minimal)
from pinecone import Pinecone, ServerlessSpec
pc = Pinecone(api_key="YOUR_KEY")
# Create index if it doesn't existif"rag-index"notin [i.name for i in pc.list_indexes()]:
pc.create_index(
name="rag-index",
dimension=1536,
metric="cosine",
spec=ServerlessSpec(cloud="aws", region="us-east-1")
)
index = pc.Index("rag-index")
# Upsert documents
index.upsert(vectors=[
{"id": "doc1", "values": [0.1]*1536, "metadata": {"text": "Hello world", "source": "intro"}},
{"id": "doc2", "values": [0.2]*1536, "metadata": {"text": "Goodbye world", "source": "outro"}},
])
# Query
results = index.query(
vector=[0.15]*1536,
top_k=2,
include_metadata=True,
filter={"source": {"$in": ["intro", "outro"]}}
)
formatchin results["matches"]:
print(f"{match['id']}: {match['metadata']['text']} (score: {match['score']:.4f})")
Pitfalls
Dimension mismatch — The dimension parameter at index creation MUST match your embedding model's output. OpenAI text-embedding-ada-002 and text-embedding-3-small produce 1536 dimensions. text-embedding-3-large produces 3072. You cannot change dimension after creation — you must delete and recreate the index.
Metric is immutable — Once an index is created with cosine, euclidean, or dotproduct, you cannot change it without deleting the index. Choose carefully based on your embedding model's training.
Batch size limits — Upserting more than ~200 vectors per batch can cause timeouts. Stick to 100–200 per batch for reliability.
Namespace deletion is irreversible — index.delete(delete_all=True, namespace="test") removes all vectors in that namespace. There is no undo.
delete_index is permanent — pc.delete_index("my-index") destroys the index and all data. Always export/backup important data before deletion.
Free tier limits — The free tier allows only 1 serverless index and 100K vectors (at 1536 dimensions). Exceeding this requires a paid plan.
Metadata filter overhead — Metadata filtering adds ~10–20ms to query latency. Index frequently filtered fields for better performance.
Sparse vector indices must be unique — In sparse_values, the indices array must contain unique integers. Duplicates will cause errors.
API key exposure — Never hardcode API keys in source files. Use environment variables (PINECONE_API_KEY) or a secrets manager.
Serverless vs Pod-based — Serverless auto-scales but may have cold start variability. Pod-based provides consistent performance but requires capacity planning. Choose based on your latency requirements.
Verification
Verify installation
pip show pinecone-client
Expected output includes the package name and version.
Verify client connection
from pinecone import Pinecone
pc = Pinecone(api_key="YOUR_KEY")
print(pc.list_indexes())
Should return a list of index names (empty list if none created).
