Working with Python Client

1. Installing Python SDK

VariantInstallUse Case
RESTpip install pineconeDefault, broadest compat
gRPCpip install "pinecone[grpc]"~30% faster, large batches
Asynciopip install "pinecone[asyncio]" NEWAsync/await native

2. Initializing Pinecone

Example: Init

from pinecone import Pinecone
import os

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

3. Creating Index Instance

Example: Get Index

index = pc.Index("products")
# or specify host explicitly:
index = pc.Index(host="products-xyz.svc.us-east-1-aws.pinecone.io")

4. Using Context Managers

Example: gRPC Context

from pinecone.grpc import PineconeGRPC

with PineconeGRPC(api_key="...").Index("products") as index:
    index.upsert(vectors=batch)
# Connection closed automatically
BenefitDetail
Auto cleanupgRPC channel closed
Exception-safeCleanup on errors

5. Implementing Async Operations

Example: Asyncio Client

from pinecone import PineconeAsyncio
import asyncio

async def main():
    async with PineconeAsyncio(api_key="...") as pc:
        async with pc.IndexAsyncio(name="products") as index:
            await index.upsert(vectors=batch)
            res = await index.query(vector=qv, top_k=10)
            print(res["matches"])

asyncio.run(main())

6. Using Type Hints

Example: Typed Vector

from pinecone import Vector

v: Vector = Vector(
    id="doc1",
    values=[0.1, 0.2, 0.3],
    metadata={"source": "wiki"},
)
index.upsert(vectors=[v])
TypeUse
VectorTyped vector record
SparseValuesTyped sparse values
QueryResponseQuery result

7. Integrating with Pandas

Example: DataFrame to Upsert

import pandas as pd

df = pd.read_parquet("embeddings.parquet")
vectors = [
    {"id": row["id"], "values": row["embedding"],
     "metadata": {"title": row["title"]}}
    for _, row in df.iterrows()
]
for i in range(0, len(vectors), 100):
    index.upsert(vectors=vectors[i:i+100])

8. Implementing Batch Processing

Example: Parallel Batches

from concurrent.futures import ThreadPoolExecutor

def upsert_batch(b):
    return index.upsert(vectors=b)

with ThreadPoolExecutor(max_workers=10) as pool:
    list(pool.map(upsert_batch, batches))

9. Handling Exceptions

Example: Catch Exceptions

from pinecone.exceptions import PineconeApiException, NotFoundException

try:
    index.query(vector=qv, top_k=10)
except NotFoundException:
    # index missing
    pass
except PineconeApiException as e:
    print(e.status, e.reason)
ExceptionCause
PineconeApiExceptionGeneric API error
NotFoundExceptionIndex/collection missing
UnauthorizedExceptionBad API key
ServiceException5xx server error

10. Optimizing Python Performance

TipEffect
Use gRPC client~30% faster batched ops
Reuse client instanceConnection pool reuse
ThreadPoolExecutorParallel network I/O
Numpy vectorsConvert to list before upsert