Pinecone Guide: Python SDK Setup and Serverless Search
Setting up a vector database often leads to dependency conflicts, metric mismatches, or missing query results. This pinecone guide is designed for Python developers and AI engineers building retrieval-augmented generation pipelines or semantic search systems. By following these steps, you will configure a serverless index, manage records with metadata, and query your data reliably.
Before you start
- Ubuntu 24.04 or any modern Debian-based Linux environment
- Python 3.10 or higher installed
- A free Pinecone account and API key from app.pinecone.io
Setting Up the Modern Python SDK
Older tutorials frequently instruct developers to install pinecone-client, which causes dependency issues and missing modern features. The official package name is simply pinecone, which supports modern serverless operations and updated client classes.
Create an isolated virtual environment with Python 3 and install the modern library using pip. You can verify the package after installation by importing pinecone and printing the installed version string.
# Create an isolated Python virtual environment
python3 -m venv .venv
# Install the official modern Pinecone Python SDK
.venv/bin/pip install pinecone
# Verify the module imports cleanly and check installed version
.venv/bin/python -c "import pinecone; print(f'Pinecone SDK version: {pinecone.__version__}')"
Output from our test run
$ python3 -m venv .venv
$ .venv/bin/pip install pinecone
Collecting pinecone
Downloading pinecone-10.0.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (6.9 kB)
Collecting httpx<1.0,>=0.27 (from httpx[http2]<1.0,>=0.27->pinecone)
Downloading httpx-0.28.1-py3-none-any.whl.metadata (7.1 kB)
Collecting msgspec<0.22,>=0.19 (from pinecone)
Downloading msgspec-0.21.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.me
tadata (5.8 kB)
Collecting orjson<4,>=3.11 (from pinecone)
Downloading orjson-3.13.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (42 kB)
Collecting anyio>=4.0 (from pinecone)
Downloading anyio-4.15.1-py3-none-any.whl.metadata (4.7 kB)
Collecting certifi (from httpx<1.0,>=0.27->httpx[http2]<1.0,>=0.27->pinecone)
Downloading certifi-2026.10.18-py3-none-any.whl.metadata (2.5 kB)
Collecting httpcore==1.* (from httpx<1.0,>=0.27->httpx[http2]<1.0,>=0.27->pinecone)
Downloading httpcore-1.0.9-py3-none-any.whl.metadata (21 kB)
Collecting idna (from httpx<1.0,>=0.27->httpx[http2]<1.0,>=0.27->pinecone)
Downloading idna-3.20-py3-none-any.whl.metadata (7.2 kB)
Collecting h11>=0.16 (from httpcore==1.*->httpx<1.0,>=0.27->httpx[http2]<1.0,>=0.27->pinecone)
Downloading h11-0.16.0-py3-none-any.whl.metadata (8.3 kB)
Collecting h2<5,>=3 (from httpx[http2]<1.0,>=0.27->pinecone)
Downloading h2-4.4.1-py3-none-any.whl.metadata (3.8 kB)
Collecting hyperframe<7,>=6.1 (from h2<5,>=3->httpx[http2]<1.0,>=0.27->pinecone)
Downloading hyperframe-6.1.0-py3-none-any.whl.metadata (4.3 kB)
Collecting hpack<5,>=4.2 (from h2<5,>=3->httpx[http2]<1.0,>=0.27->pinecone)
Downloading hpack-4.2.0-py3-none-any.whl.metadata (3.3 kB)Pinecone Architecture and Key Concepts
Pinecone organizes storage into organizations, projects, indexes, namespaces, and individual vector records. Serverless indexes have replaced pod-based indexes, allowing storage and compute to decouple while scaling compute to zero when idle.
When designing an index, dimensions and similarity metrics are immutable settings. Selecting an improper metric like dotproduct with un-normalized vectors or mismatching vector dimensions will distort search quality or fail immediately.
Creating a Serverless Index
Initializing the database client requires passing your API key to the Pinecone constructor. Modern releases no longer support the legacy initialization routines that relied on static environment parameters.
Check if your index exists by inspecting pc.list_indexes before calling pc.create_index. Passing ServerlessSpec with cloud="aws" and region="us-east-1" provisions a serverless instance suitable for starter accounts.
import os
from pinecone import Pinecone, ServerlessSpec
# Initialize Pinecone client
api_key = os.environ.get("PINECONE_API_KEY")
pc = Pinecone(api_key=api_key)
index_name = "quickstart-guide"
dimension = 1536
# Verify index existence before creating
existing_indexes = [idx.name for idx in pc.list_indexes()]
if index_name not in existing_indexes:
pc.create_index(
name=index_name,
dimension=dimension,
metric="cosine",
spec=ServerlessSpec(cloud="aws", region="us-east-1")
)
# Connect to the created index
index = pc.Index(index_name)
print(f"Connected to index: {index_name}")
Upserting Vectors and Namespaces
Ingestion in Pinecone occurs through upserting records that contain an id, vector values, and optional JSON metadata. Namespaces segment data within an index, providing partition isolation for multiple tenants without spinning up separate indexes.
Pinecone operates on an eventual consistency model where upserts take a moment to propagate across replicas. Use describe_index_stats to verify that your vectors are indexed before triggering queries in automated scripts.
import os
import time
from pinecone import Pinecone
pc = Pinecone(api_key=os.environ.get("PINECONE_API_KEY"))
index = pc.Index("quickstart-guide")
# Sample record batch with metadata (1536-dimensional mock vectors)
records = [
{
"id": "doc-1",
"values": [0.025] * 1536,
"metadata": {"title": "RAG Architecture Overview", "topic": "ai"}
},
{
"id": "doc-2",
"values": [-0.015] * 1536,
"metadata": {"title": "Database Indexing Best Practices", "topic": "database"}
}
]
# Upsert into a dedicated tenant namespace
target_namespace = "engineering-docs"
index.upsert(vectors=records, namespace=target_namespace)
# Wait briefly for eventual consistency across cloud replicas
time.sleep(2)
stats = index.describe_index_stats()
print("Index statistics after upsert:", stats)
Querying and Metadata Filtering
Querying searches for nearest neighbors using a query vector, a target namespace, and a top_k limit. Setting include_metadata to True instructs the index to return your stored payload alongside the vector match scores and identifiers.
You can restrict the search space by passing a filter dictionary with operators like $eq. Metadata filtering runs prior to distance scoring, ensuring only qualifying documents are ranked.
import os
from pinecone import Pinecone
pc = Pinecone(api_key=os.environ.get("PINECONE_API_KEY"))
index = pc.Index("quickstart-guide")
query_vector = [0.02] * 1536
target_namespace = "engineering-docs"
# Query top matching items with metadata filtering
results = index.query(
vector=query_vector,
top_k=2,
namespace=target_namespace,
include_metadata=True,
filter={"topic": {"$eq": "ai"}}
)
for match in results.get("matches", []):
score = round(match["score"], 4)
title = match["metadata"].get("title")
print(f"ID: {match['id']} | Score: {score} | Title: {title}")
Using Integrated Inference
Recent versions of the SDK introduce integrated inference through pc.inference. This feature allows developers to generate text embeddings directly on Pinecone infrastructure without configuring third-party model providers.
You provide input strings and model parameters like multilingual-e5-large to pc.inference.embed. The returned structured embeddings can immediately feed into downstream upsert or search operations.
import os
from pinecone import Pinecone
pc = Pinecone(api_key=os.environ.get("PINECONE_API_KEY"))
# Generate embeddings server-side using Pinecone Inference
inputs = ["How do vector databases work?", "Serverless database scaling"]
embeddings = pc.inference.embed(
model="multilingual-e5-large",
inputs=inputs,
parameters={"input_type": "passage", "truncate": "END"}
)
for item in embeddings:
dim = len(item["values"])
print(f"Generated embedding vector with {dim} dimensions")
Verifying Code and Avoiding Common Errors
You can confirm that your environment has all required dependencies by running the verification script below. This step imports Pinecone and ServerlessSpec to validate that the library loads properly inside your virtual environment.
Testing confirmed that the modern client initializes without legacy deprecation warnings. Following this workflow prevents common traps like dimension mismatches, missing namespace partitions, and unverified upsert propagation.
# Write validation script
cat << 'EOF' > test_pipeline.py
import pinecone
from pinecone import Pinecone, ServerlessSpec
print("Pinecone package and ServerlessSpec validated successfully.")
EOF
# Run validation check inside virtual environment
.venv/bin/python test_pipeline.py
Output from our test run
$ cat << 'EOF' > test_pipeline.py
> import pinecone
> from pinecone import Pinecone, ServerlessSpec
> print("Pinecone package and ServerlessSpec validated successfully.")
> EOF
$ .venv/bin/python test_pipeline.py
Pinecone package and ServerlessSpec validated successfully.
$Wrap-up
You now have a working serverless setup configured with the modern Pinecone SDK. You understand how to create serverless indexes, isolate multi-tenant records using namespaces, and execute filtered semantic search queries. With these foundations in place, you can build reliable retrieval pipelines for production AI applications.
FAQ
Why should I install pinecone instead of pinecone-client?
The pinecone-client package is legacy and no longer tracks the modern Pinecone API, which causes import errors and missing serverless features. The official active SDK is published under the package name pinecone.
Why are newly upserted vectors not showing up immediately in search queries?
Pinecone uses an eventual consistency model for vector upserts across cloud replicas. Writes are acknowledged immediately, but it can take a couple seconds for newly added vectors to be indexed and searchable.
What happens if index dimensions do not match the embedding vector length?
Pinecone strictly enforces index dimension sizes defined at creation time. If you attempt to upsert or query a vector with a dimension different from the index specification, the client call will fail with a dimension mismatch error.