Pinecone Cheatsheet: Indexes, Filters, Namespaces and Hybrid Search

# Python — v5+ client (post-rename from "pinecone-client")
pip install "pinecone>=5"

# Optional integrations
pip install pinecone[grpc]                  # high-throughput gRPC transport
pip install pinecone-text                   # sparse encoders for hybrid

# JS / TS
npm install @pinecone-database/pinecone

# API key — grab from the Pinecone console
export PINECONE_API_KEY=pcsk_...

# Smoke test
python -c "from pinecone import Pinecone; \
  print(Pinecone(api_key='$PINECONE_API_KEY').list_indexes().names())"

from pinecone import Pinecone, ServerlessSpec, PodSpec

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

# Serverless — pay-per-use, autoscales, default for new projects
pc.create_index(
    name="kb",
    dimension=1536,                         # match your embedder
    metric="cosine",                        # cosine | dotproduct | euclidean
    spec=ServerlessSpec(cloud="aws", region="us-east-1"),
    deletion_protection="enabled",          # block accidental drops
)

# Pod-based — fixed capacity, predictable latency (legacy / large workloads)
pc.create_index(
    name="kb-pod",
    dimension=1536, metric="cosine",
    spec=PodSpec(environment="us-west1-gcp", pod_type="p1.x1", pods=1),
)

# Wait until it's ready (status="Ready", host populated)
while not pc.describe_index("kb").status["ready"]:
    time.sleep(1)

# Connect to the index
idx = pc.Index("kb")
idx.describe_index_stats()
# → {'dimension': 1536, 'index_fullness': 0.0,
#    'total_vector_count': 0, 'namespaces': {}}

# Hybrid = dense semantic + sparse lexical (BM25-ish) in one query.
# Requires a dotproduct index (cosine breaks the math).
from pinecone import Pinecone
from pinecone_text.sparse import BM25Encoder

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
idx = pc.Index("kb-hybrid")        # created with metric="dotproduct"

# 1. Fit BM25 once on your corpus, then save its IDF table
bm25 = BM25Encoder()
bm25.fit(["text of doc 1", "text of doc 2", "..."])

# 2. Upsert dense + sparse for every chunk
docs = [{"id": "d1", "text": "..."}, {"id": "d2", "text": "..."}]
idx.upsert(vectors=[{
    "id": d["id"],
    "values": dense_embedder(d["text"]),                 # dense vector
    "sparse_values": bm25.encode_documents(d["text"]),   # {"indices", "values"}
    "metadata": {"text": d["text"]}
} for d in docs])

# 3. Query — alpha trades off dense (1.0) ↔ sparse (0.0)
def weight(dense, sparse, alpha=0.5):
    return ([v * alpha for v in dense],
            {"indices": sparse["indices"],
             "values":  [v * (1 - alpha) for v in sparse["values"]]})

dv = dense_embedder("what is RAG?")
sv = bm25.encode_queries("what is RAG?")
hd, hs = weight(dv, sv, alpha=0.5)
idx.query(vector=hd, sparse_vector=hs, top_k=5, include_metadata=True)

# Minimal Pinecone RAG store — create, upsert, filter, query
import os, time
from pinecone import Pinecone, ServerlessSpec
from openai import OpenAI

pc  = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
oai = OpenAI()

NAME, DIM = "kb", 1536
if NAME not in [i.name for i in pc.list_indexes()]:
    pc.create_index(
        name=NAME, dimension=DIM, metric="cosine",
        spec=ServerlessSpec(cloud="aws", region="us-east-1"),
    )
    while not pc.describe_index(NAME).status["ready"]:
        time.sleep(1)

idx = pc.Index(NAME)

def embed(texts):
    return [d.embedding for d in
            oai.embeddings.create(model="text-embedding-3-small", input=texts).data]

docs = [
    ("d1", "Pinecone is a managed vector DB.",          {"src": "blog"}),
    ("d2", "RAG joins retrieval with generation.",      {"src": "docs"}),
    ("d3", "Namespaces isolate data per tenant.",       {"src": "docs"}),
]
vecs = embed([t for _, t, _ in docs])
idx.upsert(vectors=[(i, v, {**m, "text": t})
                    for (i, t, m), v in zip(docs, vecs)],
           namespace="prod")

q   = embed(["what is RAG?"])[0]
res = idx.query(vector=q, top_k=2, namespace="prod",
                filter={"src": {"$eq": "docs"}}, include_metadata=True)
for m in res["matches"]:
    print(f"{m['score']:.3f}  [{m['metadata']['src']}]  {m['metadata']['text']}")