How Pinecone Works

A vector database stores numerical representations of data — called vectors or embeddings — and retrieves the entries most similar to a query vector. Unlike a relational database that matches rows by exact field values, a vector database uses approximate nearest-neighbor algorithms to rank results by geometric closeness in high-dimensional space.

Indexes

An index holds the vectors you store and query. Every index has two required properties:

Dimension — the length of vectors stored in the index. Every vector you upsert must have exactly this many values.
Metric — the similarity function used when ranking query results: cosine, euclidean, or dotproduct.

Pinecone offers two index types:

	Serverless	Pod-based
Capacity	Scales automatically	Fixed by pod type and count
Billing	Pay per operation	Pay per pod-hour
Use case	Variable or unpredictable workloads	Predictable, high-QPS workloads

Create a serverless index:

python

from pinecone import Pinecone, ServerlessSpec

pc = Pinecone()
pc.indexes.create(
    name="movie-recommendations",
    dimension=1536,
    metric="cosine",
    spec=ServerlessSpec(cloud="aws", region="us-east-1"),
)

Namespaces

A namespace is a logical partition within an index. Vectors in different namespaces are completely isolated: upserts, queries, fetches, and deletes in one namespace never touch another.

Common uses for namespaces include separating data by tenant, language, or environment without creating separate indexes:

python

index = pc.index(host="my-index-abc123.svc.pinecone.io")

# Each customer's vectors are isolated in their own namespace
index.upsert(vectors=[("doc-1", [0.1, 0.2, ...])], namespace="customer-acme")
index.upsert(vectors=[("doc-1", [0.4, 0.5, ...])], namespace="customer-globex")

results = index.query(vector=[0.1, 0.2, ...], top_k=5, namespace="customer-acme")

The empty string "" is the default namespace. All operations that omit a namespace target it implicitly.

Vectors

A vector has four components:

Component	Type	Required	Description
`id`	`str`	Yes	Unique identifier within a namespace
`values`	`list[float]`	Yes	Dense embedding values
`sparse_values`	`SparseValues`	No	Sparse representation for hybrid search
`metadata`	`dict[str, Any]`	No	Key-value data for filtering

Upsert vectors by passing tuples or Vector objects:

python

from pinecone import Vector

# Minimal tuple form
index.upsert(vectors=[("article-42", [0.012, -0.087, 0.153, ...])])

# Full object form with metadata
index.upsert(vectors=[
    Vector(
        id="article-42",
        values=[0.012, -0.087, 0.153, ...],
        metadata={"topic": "science", "published": 2024},
    ),
])

Query for similar vectors:

python

results = index.query(
    vector=[0.012, -0.087, 0.153, ...],
    top_k=10,
    filter={"topic": "science"},
)
for match in results.matches:
    print(match.id, match.score)

Records (Integrated Indexes)

Integrated indexes store text or structured data alongside each vector. Pinecone generates the embeddings server-side using a hosted model. You upsert text records; the index handles embedding automatically.

python

from pinecone import Pinecone, ServerlessSpec
from pinecone.models import EmbedConfig

pc = Pinecone()
pc.indexes.create(
    name="article-search",
    spec=ServerlessSpec(cloud="aws", region="us-east-1"),
    spec_embed=EmbedConfig(model="multilingual-e5-large"),
)

index = pc.index(name="article-search")
index.upsert_records(
    namespace="articles-en",
    records=[
        {"id": "article-1", "text": "Quantum computing advances in 2024"},
        {"id": "article-2", "text": "New discoveries in marine biology"},
    ],
)

results = index.search_records(
    namespace="articles-en",
    query={"inputs": {"text": "latest physics research"}, "top_k": 5},
)

Control Plane vs Data Plane

Operations fall into two categories:

Control plane — index lifecycle management: create, list, describe, configure, and delete indexes; manage collections and backups. Control-plane calls are routed through api.pinecone.io. You access them via the Pinecone client.

Data plane — vector operations: upsert, query, fetch, update, delete, and list vectors. Data-plane calls go directly to an index's host URL. You access them via the Index (or AsyncIndex) client.

python

from pinecone import Pinecone

pc = Pinecone()

# Control plane: describe an index to get its host
desc = pc.indexes.describe("movie-recommendations")

# Data plane: connect directly to the index
index = pc.index(host=desc.host)
index.upsert(vectors=[("movie-42", [0.1, 0.2, ...])])

Namespace Pattern in the SDK

The Pinecone client exposes related operations as namespace objects rather than a flat list of methods. This keeps the top-level surface small and groups related functionality together:

Namespace	Operations
`pc.indexes`	Create, list, describe, configure, delete indexes
`pc.collections`	Create, list, describe, delete collections
`pc.inference`	Embed text, rerank results
`pc.assistants`	Manage Pinecone Assistants

python

pc = Pinecone()

# List all indexes
for index_model in pc.indexes.list():
    print(index_model.name, index_model.status.ready)

# Describe one index
desc = pc.indexes.describe("movie-recommendations")

# Delete an index
pc.indexes.delete("movie-recommendations")