Managed Vectors with Pinecone

Two engineers run the support assistant for a product with 40 tenants. Postgres holds tickets, Redis holds sessions, and the retrieval layer needs 40 million ticket embeddings that are queried on every agent keystroke and rewritten as new tickets arrive. Nobody on the team wants to carry the pager for vector replication, backup verification, or a shard rebalance at 3 a.m. — so the question Pinecone answers is not how do I store vectors but which operational work disappears.

What disappears: capacity planning, replica placement, backup and restore, index-type tuning, and horizontal resharding. What replaces it: an API with three moving parts — an index, a namespace, and a batched upsert.

import os
from pinecone import Pinecone, ServerlessSpec

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

if "support" not in pc.list_indexes().names():
    pc.create_index(
        name="support",
        dimension=1536,
        metric="cosine",
        spec=ServerlessSpec(cloud="aws", region="us-east-1"),
    )

index = pc.Index("support")
print(index.describe_index_stats())

Output

{'dimension': 1536,
 'index_fullness': 0.0,
 'namespaces': {'tickets': {'vector_count': 40000}},
 'total_vector_count': 40000}

dimension and metric are fixed when the index is created: changing the embedding model means a new index, which is exactly what the migration runbook in Index and Collection Operations is for. index_fullness and the per-namespace counts are the two numbers worth graphing over time.

Writes go in batches, never one vector at a time:

def batches(rows, size=100):          # serverless upserts cap at 100 vectors per request
    for i in range(0, len(rows), size):
        yield rows[i:i + size]

vectors = [
    {"id": f"{tenant}:{ticket_id}",        # tenant in the id: exports stay self-describing
     "values": emb,
     "metadata": {"tenant": tenant, "status": "open", "priority": 2}}
    for tenant, ticket_id, emb in rows
]

for chunk in batches(vectors):
    index.upsert(vectors=chunk, namespace="tickets")

Each upsert is idempotent on id: the same id twice overwrites, so a retried batch cannot duplicate data — but a reused id also silently replaces a vector, a failure mode worth remembering. The two billing models differ in what you are charged for:

For a workload that spikes when a shift changes over, serverless removes the sizing decision entirely — the trade is that cost tracks request volume closely, which is the second half of this topic.

One index, forty tenants: the design choice that decides whether tenant isolation is enforced by the data layer or hoped for in application code. A namespace is a partition inside an index — same dimension, same metric, same bill — and a query always reads exactly one of them.

index: support  (dimension 1536, metric cosine)
├── namespace "tickets"        40,000 vectors   <- writes land here
├── namespace "acme"           1,240,000 vectors
├── namespace "globex"           980,000 vectors
└── namespace "" (default)            12 vectors <- surprise: unscoped writes

The empty default namespace on the last line is how tenant leaks start: an upsert that forgets namespace= writes into "", and a query that forgets it reads "". Both succeed silently.

Scoping is a two-line discipline:

index.upsert(vectors=chunk, namespace=f"tenant:{tenant}")

res = index.query(
    vector=query_embedding,
    top_k=5,
    namespace=f"tenant:{tenant}",           # read side of the same boundary
    filter={"status": {"$in": ["open", "pending"]}},
    include_metadata=True,
)

Input: tenant acme, query vector for duplicate charge on invoice 88

Output

id             score  status  priority
acme:1041      0.873  open    2
acme:1188      0.861  pending 1
acme:0977      0.844  open    3

Offboarding a tenant becomes one call — index.delete(delete_all=True, namespace="tenant:acme") — instead of a filter-matching sweep whose correctness you have to argue for. Three consequences follow from the namespace-is-a-hard-boundary model:

• No cross-tenant query exists. Anything global (product-wide trending, a fusion step like Reciprocal Rank Fusion across sources) must fan out over namespaces and merge results in the application. Budget the fan-out explicitly; forty namespaces means forty queries per global search.
• Metadata still travels with the vector. Namespaces cut the search space; metadata (status, priority, visibility) cuts within it. Use both — namespace for who, filter for what.
• Counts are the leak detector. describe_index_stats() prints vector counts per namespace nightly in a scheduled job; a namespace that grows when a test suite runs, or an unexpected "", is a bug found in minutes instead of in an incident review.

The pairing that fails in practice is one flat namespace plus a tenant metadata filter. It works — until a filter is dropped from one query out of forty, and the only thing standing between that mistake and another tenant's data is a Python argument nobody reviewed.

A free-tier user should not retrieve your customers' private documents, and a revoked document should stop appearing the moment it is revoked. Both are properties of where the permission check runs. Pinecone applies metadata filters server-side, inside the ranked query, so authorization cannot be forgotten at a call site:

res = index.query(
    vector=q,
    top_k=10,
    namespace="kb",
    filter={
        "visibility": {"$in": ["public"]},          # free tier: public only
        "deleted": {"$ne": True},                     # soft-deleted rows stay out
    },
    include_metadata=True,
)
print(res["usage"]["read_units"])

Input: query vector from a free-tier account

Output: three matches from visibility: public, and read_units: 1

read_units is the meter: a query's cost tracks the work it does, so a filter that narrows a huge namespace before ranking is cheaper than a wide scan you post-filter in Python. Revocation works by metadata update — upserting the same id with deleted: true — because re-running a query is free of stale results once the filter runs server-side. Metadata Filtering covers the operator set ($eq, $in, $ne, numeric and date ranges).

Now the write side of the meter. The 40,000-vectors-per-hour backfill from the first chapter looks identical from the product's view under two very different request patterns:

The chatty pattern does not just cost more: it multiplies the blast radius of a retry, and it is the pattern most first drafts ship because for row in rows: index.upsert(...) reads clearly. The failure modes to design against:

• Filter matches nothing. An empty result is a success response, not an error — a typo'd metadata key (status written as Status) returns zero matches forever. Assert non-empty on a canary query after any metadata schema change.
• Namespace typo on write. Data lands in a new namespace; reads still return the old set. The nightly describe_index_stats() count check catches it.
• Reused vector ids. Upsert overwrites silently, so a regeneration job that keeps ids can clobber newer embeddings with older ones. Version the id or gate regeneration on an embedding checksum.
• Post-filtering in Python. Pulling 100 vectors and filtering to 3 wastes read units on rows you were never allowed to show.

When the write volume outgrows this pattern or retention rules start demanding bulk deletes, the operations side is covered in Index and Collection Operations, and the recall cost of the index Pinecone picked for you is covered by Approximate Nearest Neighbor Indexes.