Working with Python Client
1. Installing Python SDK
| Variant | Install | Use Case |
|---|---|---|
| REST | pip install pinecone | Default, broadest compat |
| gRPC | pip install "pinecone[grpc]" | ~30% faster, large batches |
| Asyncio | pip install "pinecone[asyncio]" NEW | Async/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
| Benefit | Detail |
|---|---|
| Auto cleanup | gRPC channel closed |
| Exception-safe | Cleanup 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])
| Type | Use |
|---|---|
Vector | Typed vector record |
SparseValues | Typed sparse values |
QueryResponse | Query 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)
| Exception | Cause |
|---|---|
PineconeApiException | Generic API error |
NotFoundException | Index/collection missing |
UnauthorizedException | Bad API key |
ServiceException | 5xx server error |
10. Optimizing Python Performance
| Tip | Effect |
|---|---|
| Use gRPC client | ~30% faster batched ops |
| Reuse client instance | Connection pool reuse |
| ThreadPoolExecutor | Parallel network I/O |
| Numpy vectors | Convert to list before upsert |