The Complete Pinecone Guide

This is part one of three. It takes you from never having touched Pinecone to a working semantic search that you built, queried, filtered, and cleaned up yourself. By the end you can create an index, load records into it, search it by meaning, narrow results with filters, read the common error messages, and explain to a colleague why a search you just wrote returned nothing for the first few seconds. Mid-level and Senior take the same topics further; nothing here is thrown away.

Each section ends with a Try it task. Do them as you go. Vector databases feel abstract until you have watched your own sentence find a similar sentence, and that moment takes only a few minutes of work.

This guide was checked against the Pinecone API version 2026-07 and the Python SDK 10.0, the current releases at the time of writing. Pinecone moves fast: it ships a new stable API version every quarter, and the SDK major version follows it. Where something changed recently and old tutorials still show the old form, this guide says so and shows the current one.

What Pinecone is, and the problem it solves

Pinecone is a managed database for searching by meaning. You give it pieces of content (a paragraph, a product description, a support ticket) and it stores them in a form that lets you later ask, "which stored items are most like this one?" You do not run servers, tune memory, or patch anything. You call an API and Pinecone does the rest.

To see why that is useful, start with what came before. A classic database or search box matches words. If your help centre has an article titled "How to reset your password" and a user searches "I can't log in", a word-matching system finds nothing, because the two texts share no important words. A person sees at once that they are about the same thing. Teaching a computer that is the problem semantic search solves.

The trick is the embedding. An embedding model is a neural network that turns a piece of text (or an image, or audio) into a list of numbers, called a vector. The model is trained so that texts with similar meaning end up with similar lists of numbers. "Reset my password" and "I can't log in" land close together; "quarterly sales report" lands far away. Once everything is a list of numbers, "similar in meaning" becomes "close in space", and closeness is something a computer can calculate quickly.

The diagram is the whole idea. Everything else in this guide is detail about the third box.

Finding the closest vectors out of a few hundred is trivial; you can compare against all of them. Finding the closest out of a hundred million, in a few dozen milliseconds, is hard. Specialised data structures do it by being approximate: they find the nearest neighbours very reliably, but without checking every single vector. Pinecone's job is to build and run those structures for you, keep them updated as you add data, and keep them fast as you grow.

Two consequences of that design explain a lot of what follows. Notice them now.

Pinecone stores and searches vectors; it does not create meaning by itself. Something has to produce the vectors. You can bring your own from any embedding model, or you can let Pinecone host the embedding model and call it for you. Both paths are shown below.

The search is approximate and the database is eventually consistent. An approximate search can occasionally miss a neighbour that an exhaustive search would have found. And a record you just wrote may take a short while before it appears in search results. Neither is a bug. Both are trade-offs that buy speed and scale, and knowing about them saves hours of confusion.

What people use it for:

Pinecone is one of several vector databases. Others in this catalogue include Qdrant, Weaviate, Milvus and Chroma, plus the library FAISS and the Postgres extension pgvector. Pinecone's particular position is that it is fully managed and serverless: there is nothing to deploy. That is a real advantage when your team is small and a real limitation when your data must stay inside infrastructure you control. We return to that trade-off near the end.

The core mental model: five nouns

Pinecone has a small vocabulary. Learn these five nouns and the documentation becomes readable.

An organization is the account at the top. It groups projects that share billing, and it holds the people and the roles. A project belongs to exactly one organization and contains your indexes. API keys are scoped to a project, which means a key created in one project cannot see indexes in another. Beginners often create a key, then cannot find their index, because the index lives in a different project from the key's project.

An index is the container that actually holds your data. When you create one you choose a cloud (AWS, GCP or Azure) and a region, and that choice cannot be changed later. If you later need the data somewhere else, you create a new index and load it again. For a vector index you also choose the dimension, the length of the vectors it stores, and the metric, the way similarity is measured. Both are fixed at creation too.

A namespace is a partition inside an index. Every read and every write targets exactly one namespace, and a search only looks inside the namespace you name. You do not have to create namespaces in advance: the first time you write into a name that does not exist, Pinecone creates it. Namespaces are how you keep customers apart (one namespace per customer) or keep environments apart (one for staging data, one for production data) without paying for many indexes. If you do not name a namespace, you are using the default one, whose name is the empty string, which newer API versions display as __default__.

A record is one stored item. It has an id (a string you choose, up to 512 ASCII characters), the values (the dense vector), and optionally metadata, a small JSON object of facts about the item such as its category, year or source URL. Metadata does two jobs: you can filter by it at search time, and you can return it with the results so your application knows what the match was.

A few more words come up everywhere.

• Dense vector: the ordinary kind of embedding, a fixed-length list of decimal numbers such as 1,024 of them. It captures meaning.
• Sparse vector: a list of mostly zeros, stored as pairs of position and weight. It captures which specific words appear, and is used for keyword-style matching.
• Similarity metric: cosine, dotproduct or euclidean. For text embeddings, cosine is the usual choice, and the embedding model's documentation tells you which one it was trained for. With euclidean the returned score is a squared distance, so lower is better; with the other two, higher is better.
• Top-k: how many nearest matches you ask for. top_k=5 means "give me the five closest".
• Upsert: "update or insert". If a record with that ID exists, it is replaced; if not, it is created. There is no separate "insert" call.

On the current API version there are three kinds of index, chosen when you create it, and each kind speaks to its own set of data calls.

The kind is fixed for the life of the index, and a request of the wrong style is refused with an error that names the right one. You cannot convert an existing index from one kind to another; you create a new index and load the data again. This guide's first project uses the integrated kind because it lets you start with plain text and no embedding model of your own. Later sections show the classic and document kinds so you recognise them in other people's code.

Installing the tools and checking the setup

You need three things: an account with an API key, a client library, and optionally the command-line tool.

The account and the key. Sign up at pinecone.io. The Starter plan is free and needs no card, which is plenty for everything in this guide. In the console, open your project and choose API keys, then create a key. The key is shown once. Copy it immediately and store it somewhere safe. If you lose it, you delete it and create another.

Treat the key like a password. Never paste it into source code that you commit, and never put it in JavaScript that runs in a browser. Put it in an environment variable instead. On macOS or Linux:

export PINECONE_API_KEY="paste-your-key-here"

On Windows PowerShell the same thing is:

$env:PINECONE_API_KEY="paste-your-key-here"

The variable lasts only for that terminal window. To make it permanent, add the line to your shell profile or use your operating system's environment settings, and make sure no file containing the key is tracked by Git.

The Python client. The official Python package is called pinecone. It needs Python 3.10 or newer. Create a clean virtual environment so the install does not disturb anything else:

python -m venv .venv
source .venv/bin/activate        # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install --upgrade pinecone

Verify it:

python -c "import pinecone; print(pinecone.__version__)"

This guide targets version 10. If you see a lower major version, upgrade; the code below will not match older releases. Some tutorials mention pip install "pinecone[grpc]" or the old package name pinecone-client. Ignore them. The old name stopped receiving updates, and from version 9 onward the faster gRPC transport is built into the normal package, so no extras are needed. Pip may even warn you about unknown extras if you ask for them.

Now check that the library can reach Pinecone with your key:

from pinecone import Pinecone

pc = Pinecone()              # reads PINECONE_API_KEY from the environment
print(pc.list_indexes())     # an empty listing on a fresh project

On a new project this prints an empty result and that is a success: it proves the key is valid and the network path works. If the variable is missing, the constructor stops with PineconeValueError: No API key provided. Pass api_key='...' or set the PINECONE_API_KEY environment variable. Export the variable in the same terminal you run Python from; a variable set in another window is invisible here.

The command-line tool (optional). Pinecone has a CLI called pc. On macOS or Linux with Homebrew:

brew tap pinecone-io/tap
brew install pinecone-io/tap/pinecone

Or use the install script from the official site:

curl -fsSL https://pinecone.io/install.sh | sh

On Windows, download the prebuilt binary from the releases page of the pinecone-io/cli repository on GitHub and put it on your PATH. Then check it and sign in:

pc version
pc auth login
pc auth status
pc index list

pc auth login opens your browser. The CLI is handy for inspecting what your code created, but everything in this guide can be done from Python, so skip it if you prefer.

Your first index and your first search

Now the real thing. The goal is a small semantic search over six sentences, created from scratch. We use an integrated-embedding index, so Pinecone embeds the text for us and you never handle a vector.

Create a file called first_search.py. Start with the index:

from pinecone import Pinecone

pc = Pinecone()
index_name = "quickstart-demo"

if not pc.has_index(index_name):
    pc.create_index_for_model(
        name=index_name,
        cloud="aws",
        region="us-east-1",
        embed={
            "model": "llama-text-embed-v2",
            "field_map": {"text": "chunk_text"},
        },
    )

index = pc.index(index_name)

Read it slowly, because every line carries an idea.

pc.has_index checks whether the name is taken, so running the script twice does not crash on an "already exists" error. create_index_for_model creates an index tied to a hosted embedding model. The model is llama-text-embed-v2, one of the models Pinecone runs for you. The field_map says which field in your records holds the text to embed: here, a field named chunk_text. The cloud and region (aws and us-east-1) are fixed forever. On the free Starter plan us-east-1 is the only region available, so that is what we use.

In the current SDK, creating an index waits until the index is ready before it returns, so the next line can use it straight away. Older tutorials add a polling loop; you do not need it any more. The last line, pc.index(index_name), gives you a handle for reading and writing data. In production you point at an index by its host address instead of its name, which saves a lookup, but the name is fine while you learn.

Index names follow rules: lowercase letters, digits and hyphens only, at most 45 characters, and they cannot start or end with a hyphen. No dots, no underscores, no capitals.

Now add data. Each record carries an ID, the text in the field we mapped, and some metadata. Notice that there are no vectors anywhere:

records = [
    {"_id": "r1", "chunk_text": "To reset your password, open Settings and choose Security.", "topic": "account"},
    {"_id": "r2", "chunk_text": "Refunds are issued to the original payment method within five days.", "topic": "billing"},
    {"_id": "r3", "chunk_text": "Our mobile app supports Arabic and English interfaces.", "topic": "product"},
    {"_id": "r4", "chunk_text": "You can change the email address linked to your account in Profile.", "topic": "account"},
    {"_id": "r5", "chunk_text": "Invoices are emailed on the first day of every month.", "topic": "billing"},
    {"_id": "r6", "chunk_text": "Dark mode can be switched on from the Appearance menu.", "topic": "product"},
]

index.upsert_records("demo", records)

upsert_records("demo", records) writes the records into the namespace called demo, creating it if needed. In records for this kind of index, the ID goes in the _id field and everything else is either the text field you mapped or metadata. Pinecone embeds each chunk_text with the hosted model and stores the resulting vectors next to the metadata.

Here is the step that surprises almost every beginner. If you search immediately after the upsert, you may see no results at all. Pinecone acknowledges a write as soon as it is safely recorded, but making it searchable takes a moment, because the system is eventually consistent. Wait a few seconds before searching:

import time
time.sleep(10)

results = index.search(
    namespace="demo",
    query={"inputs": {"text": "I can't log in to my account"}, "top_k": 3},
    fields=["chunk_text", "topic"],
)

for hit in results['result']['hits']:
    print(hit["_id"], round(hit["_score"], 3), hit["fields"]["chunk_text"])

Run it with python first_search.py. You should see the password and email-address records near the top, even though your query contained neither "password" nor "reset". Exact scores depend on the hosted model, so read the ordering rather than the numbers: higher is a closer match for a cosine index. Compare the order with the ranking you made by gut in the previous section. Where they agree, the embedding model understood the sentences the way you did.

The query object has two parts. inputs holds the search text, which Pinecone embeds with the same model that embedded your records; that sameness is essential, because vectors from different models cannot be compared. top_k is how many hits you want. fields lists which stored fields to return; fields you do not list are left out, which keeps responses small.

When you are finished experimenting, delete what you created, because the free plan allows only a handful of indexes:

pc.delete_index("quickstart-demo")

Deletion is immediate and cannot be undone. In a real project you protect important indexes with deletion protection, which makes the delete call fail until you switch it off on purpose.

Bringing your own vectors: the classic index

The integrated index is the shortest path, but most existing code, and most tutorials you will meet, use the classic vector index, where you compute the embeddings yourself with whatever model you like (a Hugging Face model, an API from an AI provider, or your own). It is worth learning because it shows precisely what Pinecone stores.

Creating one requires the two decisions we mentioned: dimension and metric. The dimension must equal the length of the vectors your model produces, and it cannot be changed later. A model that outputs 1,536 numbers needs a 1,536-dimension index. Pinecone allows up to 20,000. For a learning exercise we use tiny three-number vectors, so you can see every value:

from pinecone import Pinecone, ServerlessSpec

pc = Pinecone()
name = "classic-demo"

if not pc.has_index(name):
    pc.create_index(
        name=name,
        dimension=3,
        metric="cosine",
        spec=ServerlessSpec(cloud="aws", region="us-east-1"),
    )

index = pc.index(name)

On the newest SDK the dimension, metric and spec arguments are treated as a convenience form that still works; the SDK's native form describes the index with a schema, which the next section shows. Both create the same kind of index. You will meet the spec=ServerlessSpec(...) form in a huge amount of existing code, so it is good to recognise it. The word serverless means you do not choose machine sizes: capacity grows and shrinks with your data and traffic, and you pay for what you store and use.

Now write three records. Each has an ID, a vector of exactly three numbers, and metadata:

index.upsert(
    namespace="shapes",
    vectors=[
        {"id": "a", "values": [1.0, 0.0, 0.0], "metadata": {"genre": "red"}},
        {"id": "b", "values": [0.9, 0.1, 0.0], "metadata": {"genre": "red"}},
        {"id": "c", "values": [0.0, 0.0, 1.0], "metadata": {"genre": "blue"}},
    ],
)

And ask for the neighbours of a vector that points mostly in the first direction:

import time
time.sleep(10)

res = index.query(
    namespace="shapes",
    vector=[0.95, 0.05, 0.0],
    top_k=2,
    include_metadata=True,
    include_values=False,
)
for match in res["matches"]:
    print(match["id"], match["score"], match["metadata"])

You should get a and b, both with scores very close to 1.0 (cosine similarity of 1.0 means identical direction), and not c, which points somewhere else entirely. That is the entire mechanism of semantic search, scaled down. A real embedding model simply produces longer vectors in which each direction encodes some aspect of meaning.

Notice the arguments to query. include_values=False tells Pinecone not to send the vectors back; you almost never need them and they make the response heavy. include_metadata=True returns the facts you stored. The limits worth remembering: top_k can be at most 10,000, a response can be at most 4 MB, and a single upsert request is capped at 1,000 records or 2 MB, whichever you hit first. Big loads are therefore sent in batches.

The document index: the newest style

With API version 2026-07, Pinecone introduced a third kind of index, the document index, and its Documents API. Instead of a record with a vector and a metadata blob, you store a JSON document: an object with a required _id, fields that Pinecone ranks on, and any other fields, which are stored and indexed automatically as filterable metadata. The same index can hold a dense vector, a sparse vector and text fields that support keyword search (BM25, the classic ranking formula used by search engines), all described by a schema you declare when you create the index.

Here is the beginner path in Python:

from pinecone import Pinecone, SchemaBuilder, DenseVectorQuery

pc = Pinecone()

schema = (
    SchemaBuilder()
    .add_dense_vector_field("embedding", dimension=3, metric="cosine")
    .add_string_field("body", full_text_search={"language": "en"})
    .build()
)

pc.indexes.create(
    name="articles",
    schema=schema,
    deployment={"deployment_type": "managed", "cloud": "aws", "region": "us-east-1"},
)

index = pc.index("articles")
index.documents.upsert(
    namespace="ns1",
    documents=[
        {"_id": "doc1", "embedding": [1.0, 0.0, 0.0], "body": "Intro to vector search", "year": 2024},
        {"_id": "doc2", "embedding": [0.0, 1.0, 0.0], "body": "Cooking with lentils", "year": 2022},
    ],
)

The schema is the new idea. add_dense_vector_field declares a field named embedding holding vectors of three numbers. add_string_field with full_text_search declares a text field that supports keyword search. The deployment says where the index lives; managed is the serverless kind. The field year is not in the schema, yet it works as a filterable field automatically, because every undeclared field is stored as metadata. That is a major simplification compared with the classic style.

Searching combines a scoring method and optional filters:

import time
time.sleep(10)

by_meaning = index.documents.search(
    namespace="ns1",
    top_k=2,
    score_by=[DenseVectorQuery(field="embedding", values=[0.9, 0.1, 0.0])],
    filter={"year": {"$gte": 2024}},
    include_fields=["body"],
)
for m in by_meaning.matches:
    print(m.id, m.score)

by_words = index.documents.search(
    namespace="ns1",
    top_k=2,
    score_by=[{"type": "text", "fields": ["body"], "query": "vector search"}],
    include_fields=["body"],
)

Each document search uses one scoring method: dense vector, sparse vector, text, or a query-string. By default, only _id and _score come back; include_fields=["*"] returns every stored field. If you want meaning and keywords combined, you run two searches and merge the lists in your own code; that is a topic for the Mid-level guide.

Know the limits before you commit to this style. The schema cannot be changed after creation; it declares ranking fields only, and declaring a metadata-only field is rejected with a 400. A document index has no conversion path from an older index, so adopting it means creating a new index and loading your data again. Document-schema indexes are also not covered by Pinecone's backup feature. And as of the day of writing, the command-line tool has no flag for creating a document index; use Python, TypeScript or the REST API.

For a first course, our recommendation is plain. Start with the integrated index to learn the ideas, learn the classic index because most code uses it, and keep the document index in mind for new projects that need keyword and vector search in one place.

Embeddings: where vectors come from

Until now the vectors were tiny numbers we invented, or Pinecone made them silently. In real projects you must understand this step, because the quality of your search is mostly the quality of your embeddings, not the database.

Pinecone hosts embedding models you can call directly. Calling one yourself, without an integrated index, looks like this:

from pinecone import Pinecone

pc = Pinecone()
out = pc.inference.embed(
    model="llama-text-embed-v2",
    inputs=["Reset my password", "Quarterly sales report"],
    parameters={"input_type": "passage"},
)
print(len(out[0]["values"]))     # 1024 by default

The hosted models you will see most often are these. llama-text-embed-v2 is a dense model that produces 1,024-number vectors by default (it also offers 2,048, 768, 512 and 384) and reads up to 2,048 tokens per input. multilingual-e5-large produces 1,024 dimensions and reads up to 507 tokens, and is a natural choice when your content mixes languages, for example Arabic and English. pinecone-sparse-english-v0 produces sparse vectors for keyword-style matching. A token is a chunk of text, roughly a short word or word fragment; models have a maximum number of tokens per input, and anything longer must be split first. Batches are limited to 96 inputs per call.

The input_type parameter is required and must be passage or query. These models are trained so that the text you store and the text people ask are embedded slightly differently, and mixing them up quietly lowers the quality of results. Use passage for the content you store and query for the user's question. An integrated index does this for you.

Whichever model you use, three rules prevent most embedding mistakes.

1. Use the same model for documents and queries. Vectors from different models live in different spaces; comparing them is meaningless, and if the lengths differ you get a dimension error.
2. Set the index dimension to the model's output length. Check the model card, not your memory.
3. Use the metric the model was trained for. For most text models that is cosine.

Chunking is the step people skip and regret. A model has a token limit, and a single vector for a 30-page document blurs everything into one average meaning. So you split documents into passages, often a few hundred words each, and store each passage as its own record. Give related chunks IDs that share a prefix, such as handbook#chunk_0, handbook#chunk_1; the prefix lets you list and delete a whole document later. This is a design choice with no single right answer, and it is the main lever you will tune.

When your content is Arabic, check that the model you choose is documented to support it; a model trained mostly on English text will return poor results for Arabic even though the database works perfectly. The multilingual model above exists for exactly this reason.

Frameworks hide much of this plumbing. LangChain and LlamaIndex both have Pinecone integrations that embed, chunk and upsert for you. Learn the raw calls first so that when the framework misbehaves, you know which layer to inspect.

Metadata and filtering

Similarity finds things that are alike. Filters find things that satisfy a rule. Real applications need both: "the five most relevant policy paragraphs, but only for the Egypt office and only from this year".

You attach metadata when you upsert, and you pass a filter when you search. Metadata is a flat JSON object. Allowed value types are strings, numbers, booleans and lists of strings. Nested objects and null values are not supported, and a whole record's filterable metadata may not exceed 40 KB. Flatten structures yourself: instead of {"office": {"country": "EG"}} store {"office_country": "EG"}.

A filter is a small JSON expression using operators that start with a dollar sign:

On a classic index the filter goes straight into query:

res = index.query(
    namespace="demo",
    vector=query_vector,
    top_k=5,
    filter={"$and": [{"topic": {"$eq": "billing"}}, {"year": {"$gte": 2024}}]},
    include_metadata=True,
)

On an integrated index the filter goes inside the query object of search, as "filter": {...} next to top_k.

Filters are applied as part of the search, not after it. That matters: you ask for the top five and get five that satisfy the rule, rather than the top five overall with some removed. If fewer than five records pass the filter, you simply get fewer.

Some practical limits and habits:

• A single $in or $nin can list at most 10,000 values. Longer lists return a 400.
• Writing filter={} (an empty filter) is rejected by the new Python SDK before the request is even sent. Omit the argument when there is nothing to filter.
• Do not put huge or free-text values in metadata. Keep metadata to the short facts you will filter on or display, and keep your full documents in your own database or object storage, storing only an ID that points back to them.

Everyday operations: fetch, update, delete, list and count

Search is the headline feature, but day-to-day work is mostly maintenance: looking at a record, correcting it, removing it, and counting what you have. These calls are grouped by what you are trying to do. The examples use a classic index handle called index; the integrated and document styles have their own equivalents, which the official reference lists.

Look at specific records. fetch retrieves records by ID. It is exact, unlike search, and you can ask for up to 1,000 IDs at once:

got = index.fetch(ids=["a", "b"], namespace="shapes")
print(got.vectors["a"].metadata)

Change a record. upsert with an existing ID replaces the whole record. If you only want to alter a part, update changes the fields you name and leaves the rest:

index.update(id="a", set_metadata={"genre": "crimson"}, namespace="shapes")

You can also update many records at once by describing them with a metadata filter rather than listing IDs. That is a bulk operation with its own, lower rate limit, so reserve it for real bulk changes.

Remove records. delete takes IDs (up to 1,000 per call), a metadata filter, or a request to clear a whole namespace:

index.delete(ids=["c"], namespace="shapes")
index.delete(delete_all=True, namespace="shapes")

Deleting everything in a namespace is how you reset a tenant or a test. Deleting a namespace itself is also possible and is cheap. All deletes are permanent; there is no recycle bin.

List IDs. If you use structured IDs such as handbook#chunk_0, list returns IDs that start with a prefix, up to 100 per page:

for page in index.list(prefix="handbook#", namespace="docs"):
    print(page)

This is how you remove every chunk of one document: list by its prefix, then delete those IDs. It is the main reason to design IDs with a prefix on day one.

Count what you have. describe_index_stats reports the number of records per namespace and the total:

print(index.describe_index_stats())

Use it to confirm an upload worked: the count in the namespace should equal the number of records you sent. During the first seconds after a write the count may lag behind, for the same eventual-consistency reason as before.

Namespaces as a daily tool. To see which namespaces exist, call index.list_namespaces(). To create one before any data arrives, index.create_namespace(name="customer-42"). To remove one with all its records, index.delete_namespace(namespace="customer-42"). Namespace names can be up to 512 ASCII characters. Because a search only reads one namespace, a namespace per customer both isolates customers and keeps each customer's searches cheap and fast. Per-tenant indexes are the wrong tool: plans cap the number of indexes per project, while namespaces are plentiful.

Loading lots of data. A single upsert accepts at most 1,000 records or 2 MB, so large loads go in batches. The Python SDK can do the batching for you:

index.upsert(vectors=big_list, namespace="docs", batch_size=200)

On the current SDK, a bulk call keeps going when some batches fail and reports them rather than raising, so always inspect the result for failures after a large load: the response carries upserted_count, failed_item_count and errors. If you use the dataframe helper upsert_from_dataframe, install pandas yourself because it is not a dependency, and pass on_error="raise" if you prefer an exception to a quiet partial failure.

Using Pinecone from the command line, JavaScript and REST

Python is the most common choice, but Pinecone is an HTTP service and the other doors are worth knowing.

The CLI is good for quick inspection and for scripts. After pc auth login, you set a target organization and project, then work with indexes:

pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1
pc index list
pc index describe -i my-index
pc index stats -i my-index
pc index delete -i my-index

Notice the flags. -n names a new resource, -i points at an existing index, -d is the dimension, -m the metric, -c the cloud and -r the region. Add -j to get JSON output that another program can read. Since version 1.0, delete commands ask for confirmation, which will make a script hang in CI; pass --skip-confirmation (or --json) in automation. Old tutorials use top-level commands such as pc backup or pc collection; these now live under pc index backup and pc index collection.

JavaScript and TypeScript have an official package, @pinecone-database/pinecone. Version 9 requires Node.js 22 or newer, and the old docs page that says Node 18 is out of date. You install it with npm install @pinecone-database/pinecone, build the client with new Pinecone() (it reads the same PINECONE_API_KEY), and do server-side work only: never call Pinecone from browser code, which would expose your key and also fail with a cross-origin (CORS) error. REST is what every SDK calls underneath, which is useful for debugging. Two headers matter: Api-Key carries your key and X-Pinecone-Api-Version selects the API version. Always send the version header. If you omit it, the request quietly uses the oldest supported version, and when that version is retired your calls silently move to the next one, sometimes with breaking changes.

curl "https://api.pinecone.io/indexes" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2026-07"

This is the control plane: the global endpoint at api.pinecone.io that creates, lists and deletes indexes. Reading and writing data goes through the data plane, which is a different address: the host of your particular index, for instance articles-abc123.svc.us-east-1.pinecone.io. You can read the host from pc index describe or from the console. This split explains a common confusion: your index "exists" according to the control plane, but your data call fails because you sent it to the wrong host.

Plans, limits and what things cost

Pinecone bills for what you store and what you do, so a beginner should understand the shape of the bill even on the free plan. These figures come from the official documentation at the time of writing and change; check the pricing page before relying on them.

The plans are Starter (free), Builder (a flat monthly fee, with operations blocked at quota rather than billed beyond it), Standard and Enterprise (monthly minimums, pay-as-you-go beyond that). The plans differ in how many projects, indexes, namespaces and users you can have, and in monthly allowances. On Starter you get one project, a handful of serverless indexes, a small storage allowance, and, importantly, only the us-east-1 region on AWS. Other regions need a paid plan. If a data-residency rule requires your data to stay in a particular geography, the region list matters: check which regions the docs currently offer before you design around them, because the Gulf and Egypt are not necessarily covered. For regulated data, ask your legal team before you create the index, since the region cannot be changed afterwards.

Billing uses three units. A read unit (RU) is charged for each query, scaled to the size of the namespace being searched. A write unit (WU) is charged for upserts, updates and deletes, scaled to the size of the data written. Storage is charged per gigabyte per month. There is also a charge for egress, the data your reads send back to you, above a monthly allowance.

Some consequences are worth absorbing now:

• A search costs more in a bigger namespace, because Pinecone reads more data. Splitting data into per-tenant namespaces lowers the cost of each search.
• Asking for top_k=10 or top_k=1000 costs the same number of read units, but returning more data, especially with include_values=True or heavy metadata, increases egress.
• Idle indexes cost almost nothing beyond storage, but they still count towards your index limit. Delete the ones you do not need.

Pinecone also enforces rate limits, which matter in loops. Each namespace accepts about 100 requests per second for queries, upserts, updates and deletes. Above that you get a 429 response, covered in the error section below. And there are hard size limits that are easy to hit by accident: a record ID of at most 512 characters, filterable metadata of at most 40 KB, a dense dimension of at most 20,000, and a top_k of at most 10,000.

Configuration and security basics

There is not much to configure in Pinecone itself, which is part of its appeal, but a few settings decide whether your first project is safe and stable.

Credentials. Everything starts with the API key. Keys belong to a project and are shown once. Give each application its own key and delete keys you no longer use; deleting is immediate and irreversible, so anything still using that key stops working at once. On the paid plans you can restrict what a key may do (for example, read-only access to data), which is the right default for a service that only searches. Never commit keys, never log them, and never send them to a browser.

The Python client can take the key as an argument (Pinecone(api_key="...")), but reading it from the environment is better because your code then contains no secret. Other environment variables exist for advanced setups, and explicit arguments always win over them.

Version pinning. Pinecone's SDK versions are tied to API versions: Python 10 targets 2026-07, and upgrading the package is how you move to a new API version. In a real project pin the major version in your requirements file, for example pinecone>=10,<11, so that a surprise upgrade cannot change behaviour overnight. Read the migration notes when you do upgrade; the jump from version 8 to 9 and from 9 to 10 each removed or renamed several things.

Deletion protection. When you create an important index, turn it on:

pc.indexes.configure("articles", deletion_protection="enabled")

A delete on a protected index is refused with a 403 until you disable it. It is a seatbelt against the script that cleans up the wrong index.

Reading errors: the common ones and what they mean

Errors from Pinecone are informative if you read the whole message. Below are the ones beginners actually meet, grouped by symptom.

Old code on a new library. Tutorials from 2023 start with pinecone.init(api_key=..., environment=...). That function was removed long ago, and you see AttributeError: module 'pinecone' has no attribute 'init'. The fix: from pinecone import Pinecone, then pc = Pinecone(api_key=...). There is no environment any more. Similarly, ImportError: cannot import name 'Pinecone' from 'pinecone' means an ancient installed version, or the old pinecone-client package. Run pip uninstall pinecone-client, then pip install --upgrade pinecone. If a message mentions a host like controller.us-west-2.pinecone.io, your library predates serverless; upgrade it.

Keyword mistakes from older versions. TypeError: Pinecone() got unexpected keyword arguments: ['retries'] means you used a retry keyword from version 8; the current form is retry_config=RetryConfig(...). TypeError: Pinecone.create_index() missing 1 required positional argument: 'spec' comes from versions that need a spec; pass spec=ServerlessSpec(...), or on version 10 use a schema and deployment.

HTTP status codes. The API replies with standard codes, and the SDK turns them into exceptions.

A 429 has several causes, and the message tells you which. "You've reached the query QPS limit for namespace..." is the per-second rate limit; pace your queries. "You've reached your read unit limit for the current month" is a plan quota that waits for the month to turn over or an upgrade.

Data that "is not there". The most frequent scare is empty search results right after a write. As covered, writes become searchable after a short delay. Run describe_index_stats to see whether the record count has caught up. A second cause is the wrong namespace: you wrote to demo and searched the default. A third is a metadata filter that is too strict. Remove the filter and see whether results appear.

Connection errors. Handshake read failed indicates a network, firewall, proxy or TLS problem. Test from another network, set ssl_ca_certs if your company intercepts TLS, and never disable verification. A browser console message about a missing Access-Control-Allow-Origin header means you called Pinecone from browser JavaScript; move the call to a backend.

Putting it all together: a small support-answer finder

Now combine everything into one small project: a helper that loads a handful of help-centre passages and answers questions by returning the best passage, restricted to a topic when the user asks. It is the retrieval half of a RAG system. Pairing it with a language model is the natural next step, and a web wrapper built with FastAPI would make it a service.

Plan before you code. The data is passages with a topic. We want a namespace per language so Arabic and English content never compete, an integrated index so we do not manage embeddings, meaningful IDs, and a cleanup step. Write support_finder.py:

import sys
import time
from pinecone import Pinecone

INDEX = "support-finder"
pc = Pinecone()

def ensure_index():
    if not pc.has_index(INDEX):
        pc.create_index_for_model(
            name=INDEX, cloud="aws", region="us-east-1",
            embed={"model": "multilingual-e5-large",
                   "field_map": {"text": "chunk_text"}},
        )
    return pc.index(INDEX)

def load(index):
    en = [
        {"_id": "en#0", "chunk_text": "Reset your password from Settings, then Security.", "topic": "account"},
        {"_id": "en#1", "chunk_text": "Refunds reach your card within five days.", "topic": "billing"},
        {"_id": "en#2", "chunk_text": "Invoices are emailed monthly.", "topic": "billing"},
    ]
    index.upsert_records("en", en)

def ask(index, question, topic=None):
    query = {"inputs": {"text": question}, "top_k": 2}
    if topic:
        query["filter"] = {"topic": {"$eq": topic}}
    res = index.search(namespace="en", query=query,
                       fields=["chunk_text", "topic"])
    return res["result"]["hits"]

if __name__ == "__main__":
    idx = ensure_index()
    if "--load" in sys.argv:
        load(idx)
        time.sleep(10)
    for hit in ask(idx, "when do I get my money back?", topic="billing"):
        print(round(hit["_score"], 3), hit["fields"]["chunk_text"])
    if "--cleanup" in sys.argv:
        pc.delete_index(INDEX)

Run it in stages: python support_finder.py --load first, then python support_finder.py for a second query without reloading, then python support_finder.py --cleanup to delete the index. Here the model is multilingual-e5-large, so the same index could hold an ar namespace of Arabic passages searched exactly the same way, with no changes except the namespace name. Notice how each section's ideas appear: a namespace keeps a language apart, the ID prefix names the language and chunk, metadata powers the filter, and the delay after writing is handled explicitly.

What you can now do, and what comes next

You can now explain what Pinecone is for, name its five nouns, and describe the difference between a classic vector index, an integrated-embedding index and a document index. You can create an index, load records, wait for them to become searchable, search by meaning, filter on metadata, fetch, update, delete and count records, and read the common errors. You know that the cloud and region are permanent, that the dimension must match the model, that writes are eventually consistent, that API keys are secrets scoped to a project, and that you should send the API version header and pin the SDK.

Equally important, you know where this guide stops. Production questions are the next level: how to check that a write is visible, how to combine keyword and meaning search, how to use rerankers, how to batch and parallelise large loads, how to monitor usage, and how to design namespaces for many tenants. Beyond that sit the platform questions of backups, access control, private networking, cost control and when Pinecone is the wrong choice. Those appear in the Mid-level and Senior parts of this guide.

Meanwhile, a sensible practice path: build the support finder over your own documents; try the same data in Qdrant or Chroma to see how another vector database differs; pair retrieval with a framework such as LangChain; and later learn to measure retrieval quality with RAGAS, because a search that returns something is not the same as a search that returns the right thing.

Sources

• Pinecone documentation home
• Quickstart
• Key terms
• Create an index
• Adopt the Documents API
• Upsert data
• Semantic search
• Filter by metadata
• Manage namespaces
• Fetch, update and delete data
• Understanding cost
• API versioning
• Errors
• Database limits
• Models overview
• Python SDK installation
• Python SDK v10 migration
• CLI quickstart
• Local development with Pinecone Local

This is the interview companion to the beginner guide. It assumes you have read that guide and built the small projects in it. The goal here is different: to help you explain Pinecone out loud, under time pressure, to someone who may know vector databases better than you do. Interviewers at the junior and entry level are rarely hunting for obscure trivia. They want to hear that you understand the model, that you have actually run the commands, and that you know the traps that bite newcomers and why they happen.

Read each answer, then close the page and say it in your own words. An answer you can only recognise is not yet an answer you can give.

The thirty-second answer

Pinecone is a fully managed, serverless vector database. You turn your content into embeddings, which are lists of numbers that capture meaning, store them in an index, and later ask for the stored items closest in meaning to a query. It is used for semantic search, recommendations and the retrieval step of retrieval-augmented generation, and because it is managed you never operate servers.

If you get a follow-up, the next sentence is the trade-off: Pinecone removes operational work, in exchange for less control over where and how the data runs, and the search is approximate and eventually consistent rather than exact and instant.

The model to hold in your head

Interviewers often test whether you have a clean mental model, so state it in order. The hierarchy is organization, project, index, namespace and record.

• The organization owns billing and people.
• The project holds indexes, and API keys belong to a project.
• The index lives in one cloud and region chosen at creation and never changeable. For a classic vector index it also fixes the dimension and metric.
• A namespace partitions an index. Every read and write targets one namespace, and a search scans only that one. Namespaces appear the first time you write to them.
• A record has an ID, a dense vector, optional sparse values and flat metadata. In a document index the unit is a document with a required _id.

Then add the three kinds of index: a classic vector index where you bring your own vectors, an integrated-embedding index where Pinecone embeds your text with a hosted model, and a document index, new in API 2026-07, defined by a schema. Mention that the kind is fixed at creation and each kind has its own data calls, and that you cannot convert one into another. That detail signals real experience.

Finally, the system properties. Search is approximate nearest neighbour: very accurate, but it does not compare against every vector. Writes are eventually consistent: acknowledged quickly, searchable shortly after. Billing is by read units, write units and storage.

Commands and calls to have ready

You should be able to write these from memory, or at least describe each one precisely.

from pinecone import Pinecone
pc = Pinecone()                                  # key from PINECONE_API_KEY
pc.create_index_for_model(name="docs", cloud="aws", region="us-east-1",
    embed={"model": "llama-text-embed-v2", "field_map": {"text": "chunk_text"}})
index = pc.index("docs")
index.upsert_records("ns1", [{"_id": "r1", "chunk_text": "hello world", "topic": "demo"}])
index.search(namespace="ns1",
             query={"inputs": {"text": "greeting"}, "top_k": 3},
             fields=["chunk_text"])

And the classic calls:

index.upsert(vectors=[{"id": "v1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "x"}}], namespace="ns1")
index.query(namespace="ns1", vector=[0.1, 0.2, 0.3], top_k=5, include_metadata=True,
            filter={"genre": {"$eq": "x"}})
index.fetch(ids=["v1"], namespace="ns1")
index.delete(ids=["v1"], namespace="ns1")
index.describe_index_stats()

From the shell: pip install pinecone, export PINECONE_API_KEY=..., and with the CLI pc auth login, pc index list, pc index describe -i NAME, pc index create -n NAME -d 1536 -m cosine -c aws -r us-east-1.

For REST, the two headers are Api-Key and X-Pinecone-Api-Version.

The classic traps and why they happen

These are the mistakes behind most beginner failures. Each has a cause worth being able to explain, because the cause is what proves understanding.

Search finds nothing right after an upsert. Cause: eventual consistency. A write is durably logged and acknowledged, then becomes visible to search after it is processed. The fix is to wait, or to check that the stats show the records, rather than assuming data was lost.

Dimension mismatch. Cause: the dimension is fixed when a classic index is created and every vector must match it. Models produce vectors of different lengths, so using a different model for the index than for the query yields an error or, worse, meaningless scores. The rule: one embedding model for both stored content and queries, and an index dimension equal to its output length.

Wrong namespace. Cause: namespaces are isolated, and omitting the argument means the default namespace. Data written to demo is invisible to a search that names nothing. Deletes can therefore also hit or miss the wrong partition.

Looking in the wrong project. Cause: API keys are project-scoped. A key from project A cannot see indexes in project B, and the console shows only the project you are viewing.

Outdated tutorial code. Cause: Pinecone has changed shape a lot. pinecone.init(api_key=..., environment=...) no longer exists; use Pinecone(api_key=...). The old package pinecone-client is no longer the right one; the package is pinecone. Extras like pinecone[grpc] were needed in old versions but are not in the current one. Older code also builds pod-based indexes, a legacy kind that newer organizations cannot create.

Choosing the region carelessly. Cause: cloud and region are permanent. The free plan allows only us-east-1 on AWS, so data-residency needs must be checked before building.

Putting the key in the browser. Cause: a key in front-end code is visible to anyone, and calling Pinecone from a browser also hits a CORS error. Call it from a backend.

Metadata mistakes. Cause: metadata must be flat, without nulls or nested objects, and capped at 40 KB per record. Stuffing full documents in metadata is slow and costly.

Expecting exact results. Cause: search is approximate. Query by an ID's vector may not return that ID first. For an exact lookup use fetch.

Forgetting the API version. Cause: with no version header on raw REST, the oldest supported version is used. Retirement of that version later changes behaviour silently. Always send X-Pinecone-Api-Version.

Common interview questions

What problem does a vector database solve that a normal database does not?

A normal database matches exact values or words. A vector database matches by similarity of meaning. An embedding model converts content into vectors so that similar meanings are close together, and the database finds the nearest ones quickly even among millions. The practical result is a search that finds "I can't log in" when the article is titled "Reset your password".

What is an embedding?

A list of numbers produced by a model that represents the meaning of an input such as text. Its length is the dimension. Inputs with similar meaning have vectors that are close under a metric such as cosine similarity. An embedding is only meaningful relative to the model that produced it, so you cannot mix vectors from different models.

Explain cosine, dot product and Euclidean.

They are ways to measure similarity or distance between vectors. Cosine looks at the angle and ignores length, which suits most text embeddings. Dot product multiplies and sums, and is also what sparse and hybrid indexes use. Euclidean measures straight-line distance, and Pinecone returns the squared distance, so lower is better, unlike the other two where higher is better. You choose the metric your embedding model was trained for.

What is a namespace and when would you use one?

A partition inside an index. Every operation targets one namespace, and a search scans only that one. I would use one per tenant or customer, for isolation and for cost, because a search over a small namespace reads less data. Separate indexes per tenant are the wrong approach because plans cap the number of indexes while namespaces are plentiful.

What are the three kinds of index on the current API?

A classic vector index with a chosen dimension and metric, where I supply the vectors; an integrated-embedding index, where I supply text and Pinecone embeds it with a hosted model; and a document index, introduced in API 2026-07, which is created from a schema and holds JSON documents with dense vector, sparse vector and full-text fields. The kind is fixed at creation, each has its own data calls, and moving from one to another means creating a new index and re-loading data.

What does serverless mean here?

I do not pick machine sizes or manage clusters. Storage and compute scale with my data and traffic, reads and writes scale independently, and I pay per read unit, write unit and storage. The index lives in object storage and Pinecone handles caching and compaction behind the API.

Why can a search return nothing right after I upsert?

Eventual consistency. The write is acknowledged once it is durably recorded, but it takes a short time to become searchable. I would wait, or confirm the record count, before concluding anything is wrong. In production code I would check freshness rather than rely on a sleep.

Is Pinecone search exact?

No, it is approximate nearest neighbour search. It trades a small chance of missing a true neighbour for speed. For an exact lookup by ID I use fetch.

How do you combine similarity with rules such as "only this year"?

Metadata filters. I store flat metadata on each record and pass a filter with operators like $eq, $gte, $in and $and at query time. The filter is applied during the search, so I still get up to top_k results that satisfy it, as long as enough matching records exist.

What would you do if you needed to find all chunks of one document and delete them?

I would design IDs with a prefix like handbook#chunk_0, list IDs by prefix, then delete those IDs. If I had not, I would need a metadata field for the document and a delete by filter.

What are chunks, and why chunk at all?

Embedding models have a token limit, and one vector for a long document averages everything into one blurry meaning. Splitting into passages gives each vector a focused meaning that matches questions better. Chunk size is a tuning decision, and I would measure retrieval quality rather than guess.

How do you keep an API key safe?

Store it in an environment variable or secrets manager, never in the repository or in browser code. Give each application its own key, delete unused keys, and on paid plans restrict a key to the permissions it needs, for example read-only for a search service.

How would you handle Arabic content?

Pick an embedding model documented to support Arabic, such as the hosted multilingual-e5-large, and keep Arabic and English in separate namespaces if I do not want them to compete. I would test with real Arabic queries, because a model trained mostly on English quietly gives poor results while the database itself works fine.

What changed recently that old tutorials get wrong?

pinecone.init and the environment argument are gone; the package is pinecone, not pinecone-client; creating an index waits until ready; the Python SDK groups calls such as pc.indexes.create; and API 2026-07 added document indexes with the Documents API. SDK versions are tied to API versions, so upgrading the package changes the API version.

When would you not use Pinecone?

When data must stay inside infrastructure I control and my plan cannot use a supported region or private option; when the dataset is tiny and a library such as FAISS or an extension like pgvector inside an existing Postgres would be simpler; or when I need an exact search. Pinecone's value is removing operations at scale, so when that is not the constraint, simpler tools can win.

A search works in development and returns a 429 in a loop. Why?

Rate limits. Each namespace accepts about 100 requests per second for queries and writes, and there are monthly quotas on the free plan. I would add backoff, spread load across namespaces, batch writes, and check whether the message names a per-second or monthly limit.

What does a 403 mean on delete?

Most likely deletion protection is on, or a plan quota. Deletion protection exists to stop accidental deletes; I would disable it deliberately if I really mean to delete.

Scenario questions you may be given

Even at the beginner level, interviewers like a small scenario, because it shows how you think rather than what you memorised. Practise these.

"Your colleague says the new index is broken: searches return nothing, but the console shows records. What do you check?" Start with the cheap, common causes in order. First, whether the colleague is searching the same namespace that the data was written to, because the default namespace is a different place from a named one. Second, whether the data is fresh, since a write may not be searchable for a short time. Third, whether a metadata filter is excluding everything; I would remove it and search again. Fourth, whether the same embedding model produced the stored vectors and the query. Only after those would I suspect something deeper.

"We want search over our Arabic and English help articles. How would you start?" I would choose an embedding model documented to support both languages, check that the index region satisfies our residency rules before creating it, and use an integrated-embedding index for a first version so we do not run our own embedding pipeline. I would split articles into passages, give them IDs like article-12#3, store language and topic as flat metadata, and use one namespace per language or one shared namespace with a language filter, depending on whether we ever want cross-language results. Then I would write ten real questions and check the top results by hand before building anything else.

"A teammate wants to put the Pinecone key in the web page so the browser can search directly. What do you say?" No. A key in front-end code is public, and browsers cannot call Pinecone directly anyway because of cross-origin rules. I would build a small backend endpoint that holds the key, accepts the user's question, queries Pinecone and returns only what the user is allowed to see.

"We have ten thousand customers and each should see only their own documents. Index per customer?" No. Plans limit the number of indexes, and many indexes cost more. One index with a namespace per customer gives isolation and cheaper searches, because each search reads only that customer's namespace.

How to answer when you are unsure

Honesty works better than bluffing. If you are asked about a feature you have not used, such as backups or private networking, say what you do know, name what you would check in the documentation, and describe how you would test it safely. Interviewers read that as maturity. A good line is: "I haven't run that in production. I'd check the current docs for the limits, because Pinecone's versions change quickly, and I'd try it on a throwaway index first."

A second habit that scores well is to mention versions. Saying "on the current Python SDK, version 10, creating an index blocks until it is ready" shows you did not learn from a three-year-old blog post.

Sixty-second self-test

Answer each one aloud without looking.

1. What are the five nouns in order, from the top of the hierarchy to the bottom?
2. What is fixed forever when you create an index, and what do you do if it was wrong?
3. Why does a classic index have a dimension, and what must it equal?
4. What is the difference between an integrated-embedding index and a classic one?
5. Why might a search return nothing right after an upsert?
6. What happens if you forget the namespace argument?
7. Which headers do you send over REST, and what happens if you omit the version header?
8. What kind of values can metadata hold, and what is not allowed?
9. Name two reasons to prefer a namespace over a new index.
10. Where does the API key belong, and where must it never appear?

If you could answer eight or more without hesitating, you are ready for a beginner-level conversation. If not, return to the sections of the beginner guide on the mental model and on reading errors, then try again tomorrow.

This is the practical companion to the beginner guide. It collects the mistakes that new Pinecone users genuinely make, each with the symptom you will see, the cause, and the fix. Then it lists habits worth adopting on day one, and ends with a short checklist you can run before you call any first project finished.

The mistakes beginners actually make

1. The search returns nothing right after writing

Symptom. You upsert records, immediately search, and get an empty list. You conclude the upsert failed and write it again.

Cause. Pinecone is eventually consistent. A write is acknowledged once it is durably recorded, but it becomes searchable a little later. There is no failure to fix.

Fix. Wait a few seconds in a tutorial, and check describe_index_stats to see whether the record count has caught up. In real code, do not rely on fixed sleeps; learn the freshness check at the next level. The wrong response is to retry writes in a loop, which only wastes write units, though upsert is safe to repeat because the same ID simply replaces itself.

2. Writing to one namespace and reading from another

Symptom. The index stats show records, but your search returns nothing, or a delete seems to have no effect.

Cause. Every read and write targets exactly one namespace. If you wrote into demo and searched without a namespace, you searched the default one, which is empty.

Fix. Pass namespace= on every call. Better, define it once, for example as a constant or a function argument, so that writing and reading cannot drift apart. When debugging, print the stats: they list record counts per namespace and show immediately where your data went.

3. A dimension mismatch

Symptom. A 400 error complaining that the vector dimension does not match the index.

Cause. A classic index fixes its dimension at creation. Your embedding model produces vectors of a different length, or you switched models between loading and querying.

Fix. Print len(vector) and compare it with the model's documented output size. Use one model for storing and querying. If the index was created with the wrong dimension, it cannot be edited: create a new index and load the data again. To avoid this, choose the index settings from the model's documentation, not from memory.

4. Mixing up query and passage embeddings

Symptom. Results are mediocre, with no error at all.

Cause. Pinecone's hosted embedding models require an input_type of passage for stored content and query for the user's question, and the two are embedded slightly differently. Using passage everywhere, or guessing, lowers quality quietly.

Fix. When you call pc.inference.embed yourself, pass the right input_type. If you use an integrated-embedding index, Pinecone sets it for you, which is one reason the integrated path is a good place to start.

5. Following a tutorial from 2023

Symptom. AttributeError: module 'pinecone' has no attribute 'init', or ImportError: cannot import name 'Pinecone', or an error mentioning a controller...pinecone.io address.

Cause. The tutorial uses a removed interface. pinecone.init with an environment name belonged to pod-era versions. The old package pinecone-client is also the wrong name.

Fix. Uninstall the old package with pip uninstall pinecone-client, then pip install --upgrade pinecone, and write pc = Pinecone(api_key=...). Before copying any snippet, look at its date and the version it mentions. If it requires an environment, it is outdated.

6. Copying the pinecone[grpc] install line

Symptom. A warning from pip about unknown extras, or confusion about whether gRPC is installed.

Cause. Older versions needed extras for the faster gRPC transport and for asyncio. Since version 9 they are built into the normal package.

Fix. Use plain pip install pinecone. If you later want gRPC, you ask for it when you open the index, with pc.index("name", grpc=True).

7. Hard-coding the API key

Symptom. None, until a leaked key shows up in a repository, or a billing alert arrives.

Cause. The key was pasted into a script for convenience and then committed.

Fix. Read it from the environment, add any file that contains it to .gitignore, and rotate it at once if it was ever committed: create a new key, switch your code to it, delete the old one. Deleting a key is immediate and cannot be undone, which is exactly what you want after a leak.

8. Calling Pinecone from front-end code

Symptom. A browser error about a missing Access-Control-Allow-Origin header.

Cause. You are calling the API from JavaScript in the page. Pinecone does not allow that, and doing it would expose your key even if it worked.

Fix. Put a small backend between the browser and Pinecone. The backend holds the key, calls Pinecone, and returns only the results the user may see.

9. Choosing the region without thinking

Symptom. Later, a legal or latency requirement says the data must be elsewhere, and you cannot move the index.

Cause. Cloud and region are fixed at creation. The free plan offers only AWS us-east-1.

Fix. Before you load real data, write down where it is allowed to live and compare it against the regions the documentation lists for your plan. For employers in the Gulf or Egypt with residency rules, make this the first question, not the last. For learning with public or fake data, the free region is fine.

10. Putting too much into metadata

Symptom. Slow responses, large bills for returned data, or a rejection about metadata size.

Cause. Metadata is capped at 40 KB per record, must be flat, and travels back with results when you include it. Teams paste entire documents or nested structures into it.

Fix. Keep metadata to short facts you filter on or display, such as topic, year and language. Store the full text in your own database or storage and keep an ID that points to it. Never use null values or nested objects; flatten them first.

11. Treating search as exact

Symptom. You query with a stored vector and the same record is not the first result, or numbers read back differ in the last decimals.

Cause. Search is approximate, and vectors are stored as 32-bit floats.

Fix. Use fetch when you need a specific record. Use search only for similarity. Accept tiny numeric differences as normal.

12. Forgetting the namespace on delete

Symptom. You delete everything and your data is still there, or you delete the default namespace's data and find it was the data you wanted.

Cause. delete_all=True applies to the namespace you pass, and with no argument it means the default one.

Fix. Always spell out the namespace on destructive calls. Turn on deletion protection for any index that matters, and keep a habit of printing the stats before and after a delete.

13. One index per customer

Symptom. A 403 quota error telling you the project has reached its maximum number of indexes.

Cause. Plans cap the indexes per project. Creating an index for every user does not scale and costs more.

Fix. Use one index with one namespace per customer. It isolates tenants, keeps each search small and cheap, and avoids the cap.

14. Uploading one record at a time

Symptom. A load of 50,000 records takes forever, or you hit 429 rate errors.

Cause. Each request has overhead, and each namespace allows about 100 requests per second. A single-record loop wastes both.

Fix. Send batches. A request accepts at most 1,000 records or 2 MB, so batches of a few hundred are reasonable. Let the SDK batch for you with the batch_size argument, and check the response for failures after a big upload instead of assuming success.

15. Ignoring the API version

Symptom. Code that worked last quarter behaves differently, with no change on your side.

Cause. Raw REST calls without the X-Pinecone-Api-Version header use the oldest supported version, and when that is retired, they silently move to the next. The SDK is pinned to a version, so an unpinned upgrade of the package changes it too.

Fix. Always send the header on REST, pin the SDK major version in your requirements, and read the migration notes before upgrading.

Habits worth adopting on day one

Create indexes in code, behind a check. A script that calls pc.has_index(name) first can run any number of times without a "409 already exists" error. Scripts you can re-run are scripts you can trust.

Make IDs meaningful. Use a scheme like {source}#{chunk}. It lets you list a document's chunks by prefix, delete them in one pass, and spot a bad record by eye. A random UUID gives you none of that.

Name things so you can find them. Index names allow only lowercase letters, digits and hyphens, up to 45 characters. Pick a pattern such as team-purpose-env and stick to it, so you can tell a test index from a real one at a glance.

Clean up after every experiment. The free plan allows few indexes, and old ones clutter the console. End each exercise with pc.delete_index(name). Think of the cleanup as part of the exercise, not an afterthought.

Learn the raw calls before the framework. LangChain and LlamaIndex will upsert and search for you, but when something breaks you must know whether the fault is in chunking, embedding, the index or the framework. Write one project with the plain SDK first.

Keep a tiny test set. Write ten questions and the passage that should answer each. After any change to chunking, models or filters, run them and look at the top results. This costs an hour and saves weeks of guessing; the RAGAS guide shows how to measure it properly later.

Print the response before trusting it. Call print(results) once to see the shape and the scores. Many beginners write code against a response structure they never looked at.

Watch the usage page. In your first week, check how many read and write units a session consumed, so the units become concrete before you scale up.

Pin and note versions. Put pinecone>=10,<11 in your requirements file and note the API version in the README. When someone else clones the project in six months, they will know what the code assumed.

Think about the region before the data. It takes two minutes at the start and saves a rebuild.

Keep notes on what you tried. Record the model, the dimension, the metric, the chunk size and the result of your ten-question test in a short file next to your code. Vector search has many dials, and a note of which settings produced which results is the only way to improve systematically instead of by memory.

Three small exercises to lock the habits in

Reading advice does not change habits; doing things does. These three exercises take about an hour in total and each one targets a mistake from this page.

Break it on purpose. Create a tiny classic index with a dimension of three. Upsert a vector with four numbers and read the error. Upsert to a namespace called a, then search a namespace called b and see the empty result. Search immediately after a write with no pause. Every one of these failures will happen to you eventually; meeting them on purpose, with nothing at stake, turns a confusing afternoon into a thirty-second recognition later. Write the exact error text in your notes next to the cause.

Make a script re-runnable. Take the script from the first project and run it three times in a row. If it crashes on the second run with an "already exists" error, add the has_index guard. If it duplicates data, check that your IDs are stable: upserting the same ID twice should leave one record, not two. A script that is safe to run again is also safe to run in a scheduled job or a deployment pipeline, which is where beginner scripts usually end up.

Hand your project to someone else. Write a README with four lines: the Python version, the install command with the pinned version, the environment variable the script needs, and the command to run it. Ask a friend to clone it and run it from nothing. Every place they get stuck is a mistake you made implicitly, such as an unpinned version, an unmentioned variable or an index that must exist already. Fix each one. This exercise is the best preparation for working in a team, and it quietly rehearses the checklist above.

Reading the documentation without getting lost

The official documentation is large and changes often, so a few reading habits help. Start from the quickstart for your language, and check the page for which API version and SDK version it describes. Pages about the SDK overview sometimes lag behind the releases, so when two pages disagree, trust the SDK's own reference and the release notes on GitHub, and treat install lines that mention extras or older Python versions with suspicion. When a page shows REST, a Python tab and a JavaScript tab, run the language you actually use. And when a tutorial's output looks different from yours, check the version before you blame yourself: a differently shaped response nearly always means a different SDK generation.

A short debugging routine

When a search gives bad or empty results, work through the same order every time, and change one thing at a time.

1. Is the data there? Run describe_index_stats and check the count for your namespace.
2. Is it the right namespace? Compare the namespace in your write with the one in your search.
3. Is it fresh? Wait and retry; compare the count to what you sent.
4. Is a filter hiding it? Remove the filter and search again.
5. Do the vectors match? Check the dimension and that the same model embedded stored content and queries.
6. Is the chunking sensible? Read the top results as a human. If a good answer is split across two chunks, the problem is your chunking, not Pinecone.
7. Read the error text. Pinecone's messages name the limit hit or the endpoint you should have used.

The routine is deliberately boring. Almost every beginner problem is solved in the first three steps.

A tiny checklist

Run through this before you call a first Pinecone project finished.

• The API key comes from an environment variable and is not in Git.
• I know which cloud and region the index uses, and why.
• The index kind (integrated, classic or document) was chosen on purpose.
• For a classic index, the dimension and metric match my embedding model.
• Stored content and queries use the same model, with the right input_type.
• Every read and write names its namespace.
• Records have meaningful IDs and flat, small metadata.
• Big loads are batched and I check the response for failures.
• The script waits for, or checks, freshness before searching.
• Index creation is guarded by has_index, and important indexes have deletion protection.
• The SDK version is pinned and, for REST, the version header is sent.
• I have a small test set of questions and expected passages.
• I deleted the demo indexes when I finished.

If every box is ticked, you have avoided the problems that account for most beginner support questions. The Mid-level guide builds on exactly this foundation.

This is part two of three. It assumes you already create indexes, upsert records and run queries, and that your application talks to Pinecone in production or is about to. Beginner showed you how to make the calls. This level explains why they behave as they do, so you can predict a stale read, a 429 or a surprising invoice before it happens.

Where this picks up

Each section states the problem first and finishes with a Try it you can run against a scratch project.

Three kinds of index, three data planes

Pinecone looks like one product but, on the current API version (2026-07), an index is one of three kinds, and the kind is decided when you create it. Knowing which you have explains most "why does this call fail" questions.

A vector index is the classic kind. You declare a dimension and a metric, and it stores records: an id, a dense values array, optional sparse_values, and flat metadata. You talk to it with the Vectors API (upsert, query, fetch, update, delete, list, describe_index_stats). An integrated-embedding index is created with create_index_for_model, names a hosted embedding model and a field_map, and stores text records that Pinecone embeds for you. You use the Records API (upsert_records and search). A document index is new in 2026-07. You create it with a schema, it stores documents (JSON objects with a required _id), and you use the Documents API (index.documents.*).

Each index has exactly one data plane, fixed at creation. If you send vector calls to a document index, or document calls to a vector index, the request is refused with an ApiError whose message names the endpoint you should have used. You cannot convert an existing index to a schema index. Moving means creating a new index and re-ingesting. That is a planning fact, not a bug: existing vector indexes keep working unchanged.

There is a second split that matters in production: the control plane and the data plane. The control plane is global at https://api.pinecone.io and handles index, collection and backup management. The data plane is regional and lives on each index's own host, something like articles-abc123.svc.us-east-1.pinecone.io. Reads and writes go there. When you call pc.index("articles") by name, the SDK first has to ask the control plane for the host, which costs a describe call. In a long-lived service, resolve the host once (at deploy time or at startup) and target by host:

from pinecone import Pinecone

pc = Pinecone()                                  # reads PINECONE_API_KEY
host = pc.indexes.describe("articles").host      # control plane, once
index = pc.Index(host=host)                      # data plane, reused

Pinecone's own guidance is to target by host in production, and a private endpoint setup requires the private host. Store the host in configuration rather than discovering it on every cold start.

One more orientation point. The hierarchy is organization, project, index, namespace, record or document. API keys are scoped to a project, so a key for project A cannot see project B's indexes. That is the first thing to check when a 404 follows a copy-pasted key.

How a write becomes searchable

Pinecone is eventually consistent, and the reason is the storage design. Understanding it lets you reason about freshness instead of sprinkling sleep(5) calls through tests.

A serverless index keeps its data as immutable files called slabs in object storage. A write does not modify a slab. It is appended to a request log and tagged with a log sequence number (LSN), and as soon as it is durably logged you receive a 200. The record then sits in an in-memory structure called the memtable. In the background, memtable contents are flushed into small slabs, and small slabs are merged by compaction into larger ones. Small slabs get cheap indexing. Larger merged slabs get more sophisticated indexing. Reads are served by a query router that fans out to executors over slabs cached in memory or on SSD (cold slabs are fetched from object storage), and the results are merged with whatever the memtable holds. Read and write paths scale independently.

Two consequences follow. First, a 200 means your write is durable, not that every future query sees it. Second, because reads also consult the memtable, most writes become visible quickly. New documents can still take up to about a minute to become searchable, and full-text search is the usual place you notice the delay.

The documented way to check freshness precisely is the LSN pair. Every write response carries an x-pinecone-request-lsn header. Every query response carries x-pinecone-max-indexed-lsn. When the second number is at least the first, the query ran against a state that includes your write. A read-your-writes helper can compare them, and an integration test can wait on the comparison rather than on a fixed sleep. A simpler, coarser approach is to poll describe_index_stats until the record count reflects your upload.

This also explains two behaviours people report as bugs. Querying by a record's own vector does not necessarily return that record at rank one, because approximate nearest-neighbour search is approximate. If you need an exact lookup, use fetch by ID. And values you read back can differ from what you sent in the last decimal places, because vectors are stored as 32-bit floats.

Versions: the API header, the SDK and what v9 and v10 changed

Pinecone versions its REST API by month (2026-07 is the current stable version, preceded by 2026-04, 2025-10, and so on). A new stable version and a release candidate arrive quarterly, and each stable version is supported for at least twelve months. The version is chosen with the X-Pinecone-Api-Version header.

The sharp edge is what happens when you omit the header: requests default to the oldest supported stable version. When that version is retired, your requests silently move to the next-oldest, and that move can contain breaking changes. If you call REST directly with curl or a generic HTTP client, always send the header. With an official SDK you get the pin for free, because each SDK major is built for one API version. Python 10 targets 2026-07, Node 9 targets 2026-07, Go 7 targets 2026-07, and the Java line (6.x) still targets 2025-10. Upgrading the SDK is how you change API version. You can override the header with additional_headers, but that does not restore the old SDK's types or serializers, so it is a diagnostic tool, not a migration strategy.

curl "https://api.pinecone.io/indexes" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2026-07"

On 2026-07 the create-index request is schema-only: the top-level dimension, metric, vector_type and spec are replaced by a required schema, with an optional deployment and read_capacity. For a classic vector index over raw REST you declare a schema containing only the reserved fields _values (dense) and _sparse_values (sparse), or pin 2026-04 instead. Responses from describe_index and list_indexes likewise return schema and deployment rather than the old top-level fields.

The Python SDK has had two big releases in a row, and both matter if you maintain older code.

Version 9 was a rewrite. Control-plane calls are grouped by resource (pc.indexes.create, pc.indexes.describe, pc.collections, pc.backups, pc.inference). create and delete block until done by default; pass timeout=-1 to return immediately. The async client is now AsyncPinecone. The HTTP layer moved from urllib3 to httpx, so the old retries= argument raises a TypeError and retries are configured with retry_config=RetryConfig(...). gRPC is a compiled extension inside the wheel, so there is no [grpc] extra: use pc.index("name", grpc=True). Responses are msgspec.Struct objects, so dict(idx) fails and you call idx.to_dict().

Version 10 targets 2026-07. It removes pinecone.preview entirely, so pc.preview.indexes becomes pc.indexes and SchemaBuilder is imported from pinecone. AsyncPinecone.index() is now a coroutine you must await. IndexModel is built from schema and deployment, .created_at is gone, and .dimension, .metric, .spec and similar are deprecated computed views. Teach yourself the schema path, such as idx.schema.fields["embedding"].dimension, because the documentation sources disagree on whether the legacy attributes raise or merely warn. pc.indexes.list() returns a paginator with no .names(); pc.list_indexes() is unchanged. Bulk upsert defaults changed (max_concurrency from 4 to 8, plus a total_timeout), and upsert_from_dataframe on the gRPC index no longer raises on partial failure unless you pass on_error="raise".

Another v10 change deserves a handler in your service. Client-side validation now raises before the request leaves your process: top_k outside 1 to 10,000, IDs longer than 512 characters, filter={}, mutually exclusive arguments, and malformed namespace names. These raise PineconeValueError or PineconeTypeError, neither of which is an ApiError. Code that only catches ApiError will let them through. Catch the base PineconeError.

Node has an equivalent step. Version 9 requires Node.js 22 or later, because Node 20 reached end of life in April 2026. The pc.preview surface is gone, with documents reached through pc.index(name).namespace(ns).documents, and legacy getters on index descriptions can throw PineconeIndexPropertyError. Pin majors in both ecosystems (pinecone>=10,<11 in Python), and keep a note of which API version each service ends up on.

Data modeling: IDs, metadata and chunk design

Most retrieval-quality and cost problems start in the data model, not in the query. Four constraints shape it, and they are worth memorising.

A record ID is at most 512 ASCII characters. Metadata is a flat JSON object holding strings, numbers, booleans or lists of strings. Nested objects and null values are not supported. Filterable metadata is capped at 40 KB per record or document (text in full-text-search fields is excluded from that cap). A dense vector holds at most 20,000 dimensions, and a sparse vector at most 2,048 non-zero values.

Use structured IDs. Because list accepts a prefix and returns up to 100 IDs per page, an ID like doc42#chunk_007 lets you enumerate and delete every chunk of a source document without storing a separate mapping:

# delete every chunk belonging to one source document
for page in index.list(prefix="doc42#", namespace="tenant-a"):
    index.delete(ids=page, namespace="tenant-a")

That pattern matters because re-ingesting a changed document is a delete of the old chunks plus an upsert of the new ones. If you upsert only the new chunk set and the new version has fewer chunks, the stale tail remains and keeps appearing in results.

Choose metadata for filtering and display, not as a copy of your database. Store small fields you filter on (tenant, language, document type, year, a coarse access group) and a pointer back to the source, and fetch bulky text from your own store when you need it. Large metadata inflates storage, raises write cost (an upsert costs one write unit per KB of the request, with a minimum of 5), and inflates egress when queries return it.

The filter language is the familiar set: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $and, $or and $not. $in and $nin accept at most 10,000 values, and exceeding that returns a 400. If you catch yourself building a filter with thousands of user IDs, you are modelling access wrongly: filter by a group ID (organization, project or role) instead, or give each tenant a namespace. An empty filter (filter={}) is rejected by the Python 10 client before it is sent, so omit the argument rather than passing an empty object.

Chunk size interacts with the limits too. The hosted embedding models cap input tokens (llama-text-embed-v2 at 2,048 tokens, multilingual-e5-large at 507), and top_k results are returned with their metadata under a 4 MB response limit. Smaller chunks with a short text excerpt in metadata keep responses small. Arabic and other right-to-left content deserves a deliberate choice of model: multilingual-e5-large is a hosted multilingual option, and you should evaluate retrieval on your own Arabic and English queries before choosing, using a harness like the one in the RAGAS guide.

Namespaces, multitenancy and aliases

A namespace is a partition inside an index. Every read and write targets exactly one, and a query scans only that namespace. Namespaces are created implicitly on the first upsert, or explicitly with create_namespace. The default namespace is the empty string, shown as __default__ on newer API versions.

Namespaces are the recommended multitenancy unit, and the reason is concrete rather than stylistic. Isolation is physical: a query for tenant A cannot touch tenant B's data, so there is no filter to forget. Cost follows namespace size, because a query costs one read unit per GB of the namespace searched (minimum 0.25). Querying a 1 GB tenant namespace costs 1 RU, where filtering the same tenant out of a shared 100 GB namespace costs 100 RU. And latency tracks the namespace you scan.

Three shapes cover most products:

• One namespace per tenant inside one index. Simple, cheap, and the default recommendation. Plan limits on namespaces per index apply (100 on Starter, 1,000 on Builder, 100,000 on Standard, 1,000,000 on Enterprise).
• One index per very large tenant, with namespaces for that tenant's own sub-groups.
• One shared namespace filtered by group ID when documents are shared across many viewers. Filter on a role or group, never on a long list of user IDs.

When you need results across several namespaces, Python's query_namespaces fans the query out and merges the results. Remember that each fan-out leg is a query against a namespace, so cost and the per-namespace rate limit apply per leg.

results = index.query_namespaces(
    vector=query_vec,
    namespaces=["tenant-a", "tenant-a-archive"],
    metric="cosine",
    top_k=10,
    include_metadata=True,
)

Do not create an index per tenant. Index counts are limited per project (5, 10, 20 or 200 by plan), and the failure arrives as a 403 quota error at the moment your product signs up its sixth customer.

Namespace aliases (new in late September 2026, REST on 2026-07 and later, under /namespace-aliases) solve a different problem: reindexing without downtime. An alias is a stable, repointable name for a namespace in the same index. Reads can go through an alias; writes cannot. The cutover pattern is to ingest the new corpus into ns-v2 by writing to its real name, validate it, and atomically repoint the alias that readers use from ns-v1 to ns-v2. Your application keeps querying the alias name and never learns that the data changed. An index can have up to 1,000 aliases, they cost nothing, and they do not carry over when you restore an index from a backup. Audit logs, which are an Enterprise feature, do not include alias changes, so record cutovers in your own deploy log.

Deleting a whole namespace is the cheapest way to remove a tenant: it costs a flat 5 write units, where deleting records individually costs more and takes longer. That makes it a good fit for a "delete my data" request.

Querying well: filters, hybrid search and reranking

A query in a vector index takes a vector, a top_k, an optional namespace, an optional filter, and two flags that matter more than they look: include_values and include_metadata. Neither changes the read-unit cost, but both change egress and response size, so turn include_values off unless you truly need the vectors back.

res = index.query(
    namespace="tenant-a",
    vector=query_vec,
    top_k=20,
    filter={"$and": [{"lang": {"$eq": "ar"}}, {"year": {"$gte": 2024}}]},
    include_metadata=True,
    include_values=False,
)

Metric choice affects how you read scores. For cosine and dotproduct a higher score is closer. For euclidean the score is the squared distance and lower is better, which catches people who set a similarity threshold the wrong way round. Sparse indexes use dotproduct, and a hybrid query that carries both a dense and a sparse part needs a dotproduct index.

Hybrid search

Hybrid retrieval combines semantic similarity with keyword matching, and it helps when users search for exact identifiers, product codes or rare names that embeddings blur. There are two supported routes. On the classic Vectors API, a single query can carry both vector and sparse_vector on a dotproduct index. On a document index, score_by selects one scoring method per search: text (BM25), query_string (Lucene syntax), dense_vector or sparse_vector. To combine dense and keyword scoring there, you run two searches and fuse the lists client-side, for instance with reciprocal rank fusion:

def rrf(result_lists, k=60):
    scores = {}
    for results in result_lists:
        for rank, m in enumerate(results, start=1):
            scores[m.id] = scores.get(m.id, 0.0) + 1.0 / (k + rank)
    return sorted(scores, key=scores.get, reverse=True)

Reciprocal rank fusion works on ranks rather than raw scores, which is useful because BM25 scores and cosine scores are not on comparable scales.

Full-text search

Full-text fields on a document index use BM25 with Lucene query_string syntax: AND, OR, NOT, quoted phrases, fuzzy matching with term~N (N from 0 to 2) and ^ boosts. Per-field options cover language, stemming, stop words and n-grams (n-grams cannot be combined with stemming or stop words). There is no synonym expansion, so a search for "car" will not find "automobile" unless your text contains both. The filter operators $match_phrase, $match_all and $match_any apply on those fields. A document search returns only _id and _score by default, so pass include_fields (or ["*"]) when you want content back.

Reranking

A reranker re-scores a short candidate list using a model that reads the query and each candidate together, which is more accurate than vector distance but too slow to run over the whole index. The standard shape is retrieve about 50 to 100 candidates cheaply, rerank to the best handful, and send only those to the language model:

ranked = pc.inference.rerank(
    model="bge-reranker-v2-m3",
    query="how do I rotate an API key",
    documents=[{"id": m.id, "chunk_text": m.metadata["chunk_text"]} for m in res.matches],
    top_n=5,
    rank_fields=["chunk_text"],
    return_documents=True,
)

Rerank models change. cohere-rerank-3.5 was deprecated, and since 31 August 2026 its requests are served by cohere-rerank-4-fast. Scores differ between models, so if you apply a score threshold, re-tune it after any model change. cohere-rerank-4-fast is available on Standard and Enterprise plans only.

Whatever you choose, measure it. Build a small set of real questions with known good source chunks, record hit rate at your top_k, and compare configurations. The RAGAS and Langfuse guides cover evaluation and tracing, and the LangChain and LlamaIndex guides show how their Pinecone integrations (PineconeVectorStore in langchain-pinecone) wrap the calls above.

Loading data at scale

Single upserts are fine for a prototype. A production load needs batching, concurrency, error accounting and, for large corpora, a different mechanism entirely.

The request limits are firm. A vector upsert accepts at most 1,000 records or 2 MB, text upserts for integrated indexes accept 96 records, and document upserts accept 1,000 documents or 2 MB. Hosted embedding models also batch at 96 inputs. The Python SDK batches for you when you pass a large list:

resp = index.upsert(
    vectors=records,            # thousands of dicts
    namespace="tenant-a",
    batch_size=200,
    max_concurrency=16,
    total_timeout=1800,
)
print(resp.upserted_count, resp.failed_item_count)
for err in resp.errors:
    print(err)

The part people miss is the last two lines. A large batched upsert can partly succeed. In SDK 10 the call reports failed_item_count and errors rather than raising for every failure, so a loader that ignores the response will quietly lose records. Treat a non-zero failure count as a failed job, log the errors, and retry only the failed items. Writes are idempotent for a given ID, so retrying the same record is safe.

The write limits to design around are 100 requests per second and 50 MB per second per namespace for upserts, and a 100 requests per second per namespace cap for query, update and delete too. Hitting them returns a 429. Spreading ingestion across namespaces, rather than hammering one, is the natural way to scale a multi-tenant load.

Retries. The Python SDK from version 9 retries for you: three retries (four attempts) over REST and five over gRPC, on status codes 408, 429, 500, 502, 503 and 504 plus transport errors, with jittered exponential backoff and respect for a Retry-After header. All methods, including POST, are retried because data-plane writes are idempotent. gRPC DEADLINE_EXCEEDED is not retried. RetryConfig passed to the constructor reaches the control plane and gRPC but not data-plane REST, so do not assume that a configured retry count governs every call. Layer your own bounded retry and circuit breaker around the job rather than relying on SDK defaults alone.

gRPC is the throughput option for heavy upsert and query loads: pc.index("name", grpc=True) in v9 and later. Not everything moves with it: upsert_records, search and the import methods still go over REST. If your gRPC channel sits inside a private network without TLS, such as a local emulator, the scheme setting matters, and PINECONE_GRPC_SCHEME=http against a public host sends your key in cleartext, which SDK 10 warns about.

Bulk import

For initial loads and large re-ingests, do not push records through the API at all. Bulk import reads Parquet files (for vector indexes) or JSONL (for document indexes) directly from S3, GCS or Azure Blob storage, and Pinecone recommends it for datasets of ten million records or more. It is available on Standard and Enterprise plans, costs $0.25 per GB (billed even for rows that fail), and has limits you should know: at most 10,000 namespaces, 100,000 files, 10 GB per file and 1 TB per import on on-demand indexes.

from pinecone import ImportErrorMode

op = index.start_import(
    uri="s3://my-bucket/embeddings/",
    integration_id="INTEGRATION_ID",
    error_mode=ImportErrorMode.CONTINUE,
)

describe_import, list_imports and cancel_import complete the lifecycle, and the CLI mirrors them as pc index import start|list|describe|cancel. Choose CONTINUE when a few bad rows should not abort a multi-hour load, and check the import's status afterwards rather than assuming completion.

Cost from first principles

Serverless pricing is a function of storage, reads, writes and egress, and it is predictable once you know the units. Predicting it before launch is a mid-level responsibility, because the architecture choices that move it (namespaces, chunking, metadata size) are made early.

Read units (RU). A query costs one RU per GB of the namespace it searches, with a minimum of 0.25 RU. top_k and the include flags do not change it. A document search costs the same as a query. A fetch costs 1 RU per 10 records (minimum 1). A list call costs 1 RU per call, up to 100 IDs.

Write units (WU). An upsert costs 1 WU per KB of the request plus, for an existing record, the size of the record it replaces, with a minimum of 5 per request. Updates and deletes follow the same model. Dropping a namespace costs 5 WU flat.

Storage is billed per GB-month. Size is roughly the sum, over records, of the ID, 4 bytes times the dimension, 8 bytes times the sparse non-zero count, and the metadata. A million 1,536-dimension records with 1 KB of metadata each comes to about 7.15 GB.

Egress counts the GB of record data returned by reads. Monthly allowances are 1 GB (Starter), 10 GB (Builder) and 100 GB (Standard and Enterprise), with per-GB overage on the paid tiers, and on Starter and Builder egress beyond the allowance returns a RESOURCE_EXHAUSTED 429. Because include_values and metadata inflate what you return, egress is where sloppy response shapes show up on the bill.

The levers, in rough order of impact:

1. Namespace per tenant, so a query reads only the data it needs.
2. Bulk import for initial loads, instead of paying per-KB write units through the API.
3. Dedicated read nodes for steady high query rates, which are exempt from read-unit and per-second read limits (egress still applies).
4. include_values=False and lean metadata.
5. Deleting idle indexes. An idle serverless index costs only storage.

Limits, 429s and dedicated read nodes

Pinecone applies limits per namespace, per index and per project, and knowing which one you hit tells you the fix. Since January 2026, query, upsert, update and delete are limited to 100 requests per second per namespace on every plan. Queries are also capped at 2,000 RU per second per index. Fetch is 100 requests per second per index, list 200, and describe_index_stats 100. Update-by-metadata and delete-by-metadata are limited to 5 requests per second per namespace. Inference is 100 requests per second and 2,000 per minute per project. Many limits can be raised through Support.

A 429 therefore has several possible meanings, and the message text tells you which:

Handle 429 with backoff and jitter, not with an immediate retry loop, and put a bounded budget on total retry time so a throttled dependency cannot hold your request threads forever. The SDK already retries 429s a few times, so the useful application-level behaviour is what you do after those retries fail: degrade (return fewer results, serve a cached answer) rather than error.

When a single namespace needs more than 100 queries per second, you have two honest options: shard the data across namespaces if the access pattern allows, or move the index to dedicated read nodes (DRN), generally available since April 2026 on Standard and Enterprise. DRN replaces on-demand read billing with provisioned capacity and is exempt from read-unit and per-second read limits.

pc.indexes.configure(
    "articles",
    read_capacity={
        "mode": "Dedicated",
        "dedicated": {
            "node_type": "t1",
            "scaling": "Manual",
            "manual": {"shards": 2, "replicas": 2},
        },
    },
)

Node types are b1 (balanced) and t1 (about four times the compute and memory at about three times the cost). Capacity is 250 GB per shard, and nodes equal shards times replicas, spread across up to three availability zones. Pinecone's recommendation is n+1 replicas so a single failure does not take reads down. Changes apply asynchronously, and read_capacity.status.state moves through Ready, Scaling, Migrating and Error, so poll it rather than assuming the call finishing means the change finished. Watch index fullness: when it reaches 1.0, writes are blocked while reads continue. Alert well before that, at around 0.8.

Keys, roles and the CLI in a team setting

Beginner told you to keep the API key out of your code. At work the questions are who holds which key, what it can do, and how you rotate it.

API keys are project-scoped. A key is shown once at creation, and deleting it is immediate and irreversible. On Starter and Builder plans keys must have "All" permissions. Custom roles on keys need Standard or Enterprise. The access roles you can bind are ProjectEditor, ProjectViewer, ControlPlaneEditor, ControlPlaneViewer, DataPlaneEditor and DataPlaneViewer. Effective permissions are the union of every role bound to a principal. API keys cannot hold the membership roles (ProjectOwner, ProjectManager, ProjectMember).

Least privilege falls out of that list. The service that serves user queries should have a key with DataPlaneViewer. The ingestion job gets DataPlaneEditor. Nothing at runtime needs control-plane rights, because indexes are created by your infrastructure code, not by the application. A leaked query key then lets an attacker read, not write or delete, and cannot delete an index. Note the 2026 RBAC rename: the old User role is now Manager (OrgManager, ProjectManager), with OrgMember and ProjectMember added beneath it.

For humans and automation that manage organisations and projects, use service accounts and the Admin API, which authenticates with OAuth client credentials rather than an API key. An API key cannot call the Admin API, and that is a frequent source of a confusing 401.

from pinecone import Admin

admin = Admin()    # PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET
key = admin.api_keys.create(project_id="PROJECT_ID", name="query-service")

Keep the secrets where your other secrets live. If your platform uses Vault, issue the keys from there and inject them as environment variables at start time. Never ship a Pinecone key to browser JavaScript: besides the exposure, browsers will fail on the missing CORS header, and the correct design is a thin backend that holds the key and exposes only the search you intend.

The CLI deserves a note because it holds credentials too. pc auth login opens a browser flow, and local state lives in ~/.config/pinecone/ with restrictive permissions (secrets.yaml, state.yaml, config.yaml). A browser or service-account login auto-creates managed keys named pinecone-cli-{id}, and pc auth logout does not delete them on the Pinecone side. Run pc auth local-keys prune before logging out if you want them cleaned up. When several credentials exist, the CLI prefers the API key (environment variable first), then the user token, then the service account for control and data planes.

CLI 1.0 also changed behaviours that bite scripts. Delete commands now prompt for confirmation, so unattended jobs need --skip-confirmation or --json. pc index record search requires --top-k. Backup, restore and collection commands moved under pc index, and --index-name/-i names an existing index while --name/-n names a new resource.

For enterprise needs, the platform offers SSO, audit logs written to S3 roughly every 30 minutes, customer-managed encryption keys (AWS KMS), and private endpoints through AWS PrivateLink or Azure Private Link, all on Enterprise. Data is encrypted at rest with AES-256 and in transit with TLS 1.2. If your employer is in the Gulf or Egypt and has residency requirements, check the regions list before you design: managed regions include AWS eu-west-1 and eu-central-1 and GCP europe-west4, and there is no region in the Middle East in the documented table. Where that is a blocker, the bring-your-own-cloud option runs the data plane inside your own AWS, GCP or Azure account, and it is generally available on Enterprise.

Observability: metrics, alerts and tracing

You cannot operate a managed service from its dashboard alone. Pinecone exposes Prometheus metrics for serverless indexes on Builder plans and above, through HTTP service discovery, so a scrape job needs only your project ID and a key:

scrape_configs:
  - job_name: 'pinecone-serverless-metrics'
    http_sd_configs:
      - url: https://api.pinecone.io/prometheus/projects/PROJECT_ID/metrics/discovery
        refresh_interval: 1m
        authorization:
          type: Bearer
          credentials: API_KEY
    authorization:
      type: Bearer
      credentials: API_KEY

The metrics worth charting are pinecone_db_record_total and pinecone_db_storage_size_bytes for volume, the per-operation counts and duration sums such as pinecone_db_op_query_count and pinecone_db_op_query_duration_sum (milliseconds), and pinecone_db_read_unit_count and pinecone_db_write_unit_count for usage. For dedicated read nodes add pinecone_db_drn_cpu_usage_percent and the fullness gauges pinecone_db_index_fullness, pinecone_db_index_memory_fullness and pinecone_db_index_storage_fullness. pinecone_db_scheduled_backup_failure_total tells you a scheduled backup did not run. Labels include index_name, cloud, region, capacity_mode and, for dedicated nodes, shard_id. Datadog has a first-party integration, and New Relic works through the Prometheus route. Build the dashboards in Grafana and store the alert rules next to the application code, as covered in the Prometheus guide.

Client-side metrics matter just as much, because they are what your users experience. Record latency and outcome of every Pinecone call from your own service, as a histogram with the operation name and namespace class as labels. Server duration sums miss network time, retries and your own serialization. OpenTelemetry spans around retrieval calls are the way to see retrieval time inside a larger request, and Langfuse can hold the retrieved chunks with each generation so you can later answer "what did the model actually see".

Also subscribe to status.pinecone.io, and make your runbook say what to do first when it shows an incident: which of your features degrade gracefully, and which return errors.

Testing, local development and infrastructure as code

Tests that call a real Pinecone project are slow, cost money and share state. Pinecone offers Pinecone Local, a Docker emulator for development and CI, and the discipline is to use it for logic and a real project for the things it cannot model.

docker run -d --name pinecone-local \
  -e PORT=5080 -e PINECONE_HOST=localhost \
  -p 5080-5090:5080-5090 --platform linux/amd64 \
  ghcr.io/pinecone-io/pinecone-local:latest

Know its boundaries. It is in-memory with no persistence, it ignores API keys (examples use api_key="pclocal"), and it holds at most 100,000 records per index. It speaks API 2025-01, and has no import, backups, collections, namespace management, Inference or Assistant. Because current SDKs default to 2026-07, compatibility with the emulator's surface is not guaranteed, so test the classic vector path with it and treat it as a smoke test for query and upsert logic. Over gRPC you need a non-TLS channel. In CI, start it as a service container in your GitHub Actions job, wait until it answers, and tear it down after.

Keep three layers of tests:

1. Unit tests with the Pinecone client faked or mocked, which prove your chunking, ID scheme, filter building and error handling.
2. Emulator tests for the upsert, query and delete round trip.
3. A nightly or pre-release test against a real project, in a dedicated namespace that the test creates and deletes, that checks the things the emulator cannot: the current API version, namespaces, hosted embeddings and rerank, and real freshness behaviour.

Isolate real tests by namespace and clean up in a finally block; deleting a namespace is cheap. Use the LSN comparison rather than sleeps.

Create indexes with code, not by clicking. The Terraform provider (pinecone-io/pinecone, version 4) manages indexes, collections, projects, API keys, service accounts and role bindings. Pin it as ~> 4.0. It authenticates with PINECONE_API_KEY for index and collection resources and with PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET for organisation-level resources. The Terraform guide covers state, review and module structure, and the same rules apply: index region, dimension and schema are immutable, so a change forces replacement, and replacement of a production index means data loss unless you planned a reload. Turn on deletion protection for anything that matters.

pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1

The CLI does not currently expose a document-schema create flag, so create document indexes through the SDK, REST or Terraform. Note too that the name rules are strict: lowercase letters, digits and hyphens, at most 45 characters, no leading or trailing hyphen, and no dots.

Backups protect against your own mistakes. A backup is a static, non-queryable copy of a serverless index, in the same project, cloud and region, and it contains only records present at least fifteen minutes before it was taken. You can schedule them (daily, weekly or monthly, with retention; one schedule per index), restore into a new index, and, within the same cloud, restore across regions through the unstable API over REST. Document-schema indexes are not supported by backups, so for those your own re-ingestion path is the recovery plan, which is one more reason to keep your source data and chunking pipeline reproducible.

pc.backup_schedules.create(
    index_name="articles",
    name="daily",
    frequency="daily",
    retention_days=90,
)

Rehearse restore. A backup you have never restored is a hypothesis.

A debugging playbook

When retrieval misbehaves, resist guessing and work down a fixed order. Most incidents land in one of five buckets.

1. The call fails. Read the exception class first. PineconeValueError and PineconeTypeError came from client-side validation and never reached the server. ApiError subclasses map to statuses: UnauthorizedError (401, wrong key or wrong project), ForbiddenError (403, a plan limit or deletion protection), NotFoundError (404, wrong index name or host), ConflictError (409, creating something that exists), FailedPreconditionError (412, the index is not in a valid state yet). A message that names a different endpoint means you called the wrong data plane for that index.

2. The call works but results are missing. Suspect freshness first (compare LSNs), then the namespace (a surprisingly common cause is querying the default namespace while the data went into a named one), then the filter (a metadata key that does not exist matches nothing, and types must match: "2024" the string does not equal 2024 the number).

3. Results exist but are bad. Check that the query and the stored vectors came from the same model and dimension, that you used input_type of passage for documents and query for questions where the model needs it, and that the metric suits the embedding. Then look at chunking: if the right answer is split across two chunks, no ranking will fix it.

4. Latency rose. Separate network and client time from server time using your own histogram and the server's duration metric. Check whether top_k or the include flags grew, whether you target by name (an extra describe call) rather than by host, whether a namespace has grown large, and whether you are being throttled and retried.

5. The bill rose. Look at read units first, since they scale with namespace size and query volume, then egress, then write units from re-upserting unchanged data, then storage from metadata bloat.

Here is a first-response script worth keeping handy:

pc auth status
pc target --show
pc index list
pc index describe -i my-index
pc index stats -i my-index

Those commands answer "which account, which project, which index, how many records and in which namespaces" in a few seconds, and that is the answer to a surprising number of questions. Add -j for machine-readable output.

Putting it all together

Imagine a support-search feature for a multi-tenant product, launching to customers in several countries. Here is how the pieces from this part combine into one design.

Start with data placement. Choose the cloud and region against your customers' residency needs, and accept that it is permanent. Create one index with Terraform, with deletion protection on, then decide whether it is a vector index or a document index. If you need keyword and semantic ranking in one place and are happy to re-ingest to adopt it, a document index with a dense field and a full-text field fits. If you already have a classic index, keep it.

Model each knowledge-base article as chunks with IDs like article-318#chunk_004, a lean metadata object (language, product area, access group, a source URL, a short excerpt), and one namespace per customer. Ingest the first corpus with bulk import and later changes through batched upserts that check failed_item_count, delete stale chunks by ID prefix before writing a re-chunked article, and finish every job with a count reconciliation.

Serve queries from a service holding a DataPlaneViewer key and the index host in configuration. Query one namespace, fetch 50 candidates with include_values=False, rerank to five, and pass those to the language model through a framework such as LangChain. Wrap each call with a latency histogram and bounded retries, and degrade gracefully on 429 by returning fewer results or a cached answer.

Operate it with Prometheus scraping the usage and latency metrics, alerts on 429 rate, read-unit burn and backup failures, and a scheduled daily backup. Reindexing becomes a namespace-alias move. CI runs unit tests, the emulator round trip, and a nightly real-project test that uses the LSN check. The SDK and API versions are pinned and recorded, upgrades go through the migration guide, and a grep for deprecated arguments runs in the pipeline.

Where you are now

You can now explain why a write is durable before it is searchable and measure the gap, tell the three index kinds apart and say which data plane each uses, pin API and SDK versions on purpose, and design IDs, metadata and namespaces so that cost and isolation follow from the model. You can load data at scale without losing records silently, handle 429s and know when dedicated read nodes beat on-demand, scope keys by role, watch the service with metrics, test against an emulator and a real project, and work through a retrieval incident in a fixed order.

The next level treats Pinecone as a platform you run for other teams: architecture and failure modes, which component breaks first at scale, bring-your-own-cloud, multi-tenant governance, upgrade and migration programmes, and when another store is the better choice. For a comparison point on the other side of that decision, read the pgvector, Qdrant and FAISS guides.

Sources

• Pinecone documentation
• API versioning
• 2026 release notes
• Key terms
• Architecture
• Data modeling
• Upsert data
• Import data
• Check data freshness
• Dedicated Read Nodes
• Adopt the Documents API
• Filter by metadata
• Rerank results
• Manage namespaces
• Namespace aliases
• Backups overview
• Understanding cost
• Database limits
• Error handling
• Monitoring
• Manage RBAC
• Local development
• CLI command reference
• Python SDK v10 migration

Part two of three. Interviewers at this level assume you can call the API. They want to know whether you can reason about a running system: why a result is stale, why a bill grew, how you would design tenancy, and what you would change before launch. This file is organised around scenario questions, trade-off questions, and what separates a strong answer from a weak one.

Where this picks up

The sixty-second refresher

Pinecone is a managed vector and document database. The hierarchy is organization, project, index, namespace, record or document. An index lives in one cloud and region for life. A namespace partitions an index, and every read or write targets exactly one. Serverless storage is immutable slabs in object storage, with a log and memtable in front, which is why the system is eventually consistent. Reads cost read units that scale with the size of the namespace searched, writes cost write units that scale with the kilobytes written, and egress is metered separately. API keys belong to a project.

Hold on to one sentence for the opening of many answers: "It depends on the namespace size, the access pattern, and whether the data is shared." Most good answers are variations on it.

Scenario questions

"Users say a document they just uploaded does not appear in search. What do you check?"

Start with what you know about the system rather than with guesses. A 200 on upsert means the write is durable in the request log, not that every query sees it. Pinecone is eventually consistent, and new data can take up to about a minute to become searchable, with full-text search being the typical place it shows.

So the first check is timing: compare the x-pinecone-request-lsn header on the write response with the x-pinecone-max-indexed-lsn on a query response. If the indexed LSN has caught up and the record is still missing, it is not freshness. Then check the namespace (written to one, queried another, or the default namespace), the filter (a key that does not exist matches nothing, and a string "2024" does not equal the number 2024), and whether the upsert call actually succeeded: in the current Python SDK a large batched upsert reports failed_item_count and errors instead of raising, so an ignored response can hide a partial failure.

A strong answer names the LSN mechanism and the partial-failure behaviour. A weak answer says "wait a few seconds and retry" or "re-upload it".

"The monthly bill doubled but traffic did not. Where do you look?"

Reads scale with namespace size, not only with query count. A query costs one read unit per GB of the namespace it searches, with a minimum of 0.25. So the likely suspects are a namespace that grew (a tenant's corpus, or a shared namespace that absorbed more tenants), a change that moved queries from small namespaces to a big one, or a feature that fans out across more namespaces. Then egress: if someone turned on include_values or added bulky metadata, the data returned per query grew, and egress is metered separately with monthly allowances. After that, write units: re-upserting unchanged data on every sync job costs a write unit per kilobyte each time. Finally storage, from metadata bloat.

The strong answer uses the metrics and the usage dashboard to find which of those moved, instead of theorising, and mentions that the read units reported in responses are rounded up so precise numbers come from metrics. It then proposes the structural fix: one namespace per tenant, lean metadata, include_values=False, and incremental syncs that skip unchanged records.

"You are intermittently getting 429s under load. What do you do?"

Ask which 429 it is. The message text distinguishes a per-namespace query rate limit (100 requests per second per namespace on all plans), a monthly read or write unit cap on a capped plan, an embedding or inference token limit, and an egress allowance (RESOURCE_EXHAUSTED) on Starter and Builder.

For the namespace limit, the SDK already retries 429s a few times with jittered backoff. What matters is the behaviour afterwards: a bounded total retry budget, graceful degradation (fewer results, a cached answer), and a circuit breaker so you are not hammering a throttled dependency. Structurally, if the load concentrates on one namespace, either shard the data across namespaces if the access pattern allows, or move to dedicated read nodes, which are exempt from read-unit and per-second read limits. For a monthly cap the answer is a plan change or reducing waste.

A weak answer is "add a retry loop". A strong answer distinguishes the limits, cites the numbers, and chooses between sharding and dedicated nodes with a reason.

"Design the data model for a multi-tenant knowledge-base search."

Namespace per tenant inside a shared index is the default. The reasons are isolation (no filter to forget), cost (a query reads only that tenant's namespace) and latency. Very large tenants can get their own index with namespaces for sub-groups. Shared content visible to many users uses one namespace with a filter on a group, role or organization ID, never a thousand user IDs, because $in is capped at 10,000 values and the filter gets unwieldy anyway.

Then the record shape: structured IDs such as article-318#chunk_004, so you can list by prefix and delete a source's chunks when it is re-chunked; lean metadata (language, product area, access group, source URL, a short excerpt) well under the 40 KB cap; chunk sizes that fit the embedding model's input limit. Check plan limits on namespaces per index (100, 1,000, 100,000 or 1,000,000 by plan), and do not create an index per tenant because indexes per project are capped at 5, 10, 20 or 200.

Add operations: bulk import for the first load, batched upserts afterwards, an alias for zero-downtime reindexing, and deleting a whole namespace for a "delete my data" request, which costs a flat 5 write units.

"How would you re-embed the whole corpus with a new model with no downtime?"

A new model usually means a new dimension or at least a different vector space, so you cannot mix old and new vectors in one namespace. Write the new embeddings into a fresh namespace (or a new index, if the dimension differs), keeping the old one live. Validate retrieval quality against your evaluation set. Then cut over. Namespace aliases make the cutover a pointer move: readers query the alias name, and you repoint it from the old namespace to the new one atomically. Rollback is the reverse move, and you delete the old namespace only after you are confident.

If the new model needs a different dimension, remember that an index's dimension is fixed, so it is a new index, and the alias (which only points within an index) does not help. In that case the cutover happens at your application's configuration: a setting that names the index host to use. Mention cost: bulk import is the cheap way to load a large corpus, at $0.25 per GB, and you pay storage for both copies during the overlap.

"A service that worked last month throws errors after a dependency update. How do you diagnose it?"

Version drift. Check the SDK major first. Python 9 changed the retry argument, the async class name and the gRPC packaging. Python 10 removed pinecone.preview, made AsyncPinecone.index() a coroutine, and added client-side validation that raises exceptions which are not ApiError. Node 9 requires Node 22. The right move is to read the migration guide for the version you landed on, not to patch around the error.

Then explain prevention: pin SDK majors, record which API version each service speaks (the SDK's major determines it), and grep for deprecated arguments in CI. The detail that impresses is that several Python 10 deprecations emit no warning, so a warning-based safety net will not catch them. Also note that if you call REST by hand and omit X-Pinecone-Api-Version, you get the oldest supported stable version, which will change under you when it is retired.

Trade-off questions

Serverless on-demand versus dedicated read nodes

On-demand bills per read unit, scales automatically, and suits spiky or modest traffic. Dedicated read nodes give provisioned capacity (a b1 balanced or t1 high-compute node type, with shards of 250 GB and replicas for availability), remove read-unit and per-second read limits, and suit steady high query rates and tight latency targets. The price is commitment and capacity planning: you size shards and replicas, watch index fullness (writes block at 1.0 while reads continue), and recommend n+1 replicas. The break-even depends on query volume and namespace size. A confident answer says you would measure read-unit spend and the 429 rate before choosing, and that on-demand is the right place to start.

One index per tenant versus namespaces

Namespaces win on cost, quota headroom and operational simplicity, and one index per tenant hits the per-project index cap quickly. An index per tenant buys stronger separation of settings: different region, different read capacity, deletion protection per customer. Choose it only for a few large, contractually distinct tenants. The common compromise is namespaces for most tenants and a dedicated index for the biggest.

Hybrid search on the classic API versus a document index

A classic vector index can answer a hybrid query in a single call, with a dense vector and a sparse vector on a dotproduct index. A document index scores by one method per search (BM25 text, a Lucene query string, dense or sparse), so combining them means two searches and a client-side fusion such as reciprocal rank fusion. The document index brings full-text features (phrases, fuzzy matching, boosts, n-grams) and a schema, at the cost of immutability: the schema is fixed at creation, only ranking fields are declared, and you cannot convert an existing index. If your product mostly needs semantic search, stay with what you have. If you need keyword precision and are building new, evaluate the document index.

Integrated embedding versus bringing your own vectors

Integrated embedding removes an embedding service from your architecture, since Pinecone embeds on write and on search, with hosted models such as llama-text-embed-v2 and multilingual-e5-large. It is quick to build and has fewer moving parts. Bringing your own vectors gives you freedom of model, control over batching and cost, and the ability to use the same embeddings elsewhere. It also makes you own the model upgrades. For multilingual content, such as Arabic and English together, test the candidate models on your real queries before deciding, because that matters more than the integration style.

Pinecone versus pgvector or a self-hosted store

Pinecone offers managed operations, namespaces as a first-class tenancy concept, and elastic scale, at the price of a separate service, a cost model tied to usage and regions limited to the published list. A database extension such as pgvector keeps vectors next to your relational data and transactions, which is attractive for modest scale and strong consistency needs. A self-hosted engine such as Qdrant gives control over placement and tuning, which can matter for data-residency rules, with the operational burden on your team. A balanced answer picks based on scale, consistency requirements, residency constraints and who will carry the pager.

What strong answers cover that weak ones miss

Across all these questions the pattern is the same.

A weak answer states a feature ("use namespaces") and stops. A strong answer states the mechanism and the number: "a query costs one read unit per GB of the namespace, so tenant namespaces make each query proportional to the tenant's size." Numbers you should be able to produce from memory are the 100 requests per second per namespace limit, the 1,000-record or 2 MB upsert batch, the 40 KB metadata cap, the 10,000-value $in limit, the 512-character ID limit and the top_k ceiling of 10,000.

A weak answer treats freshness as a nuisance. A strong answer treats it as a property to test, with the LSN headers.

A weak answer reaches for a bigger plan. A strong answer first finds which limit or unit is responsible.

A weak answer ignores failure. A strong answer says what the system does when Pinecone is slow or throttled: timeouts, bounded retries, caching, fallbacks, and a user-facing degraded mode.

A weak answer forgets versions. A strong answer mentions pinning the SDK and the API version and knows that deprecated arguments in Python 10 do not warn.

A weak answer hard-codes a key. A strong answer has separate keys for querying and ingestion with narrow roles, keeps them in a secrets manager, and never sends them to a browser.

A weak answer cannot say how it knows retrieval is good. A strong answer has an evaluation set of real questions and measures hit rate before and after each change, which you can extend with the RAGAS guide.

Quick-fire questions

Why is querying by a record's own vector not guaranteed to return it first? Nearest-neighbour search is approximate. Use fetch for exact ID lookup.

Why might upserted values differ slightly when read back? They are stored as 32-bit floats.

What happens to your requests if you omit the API version header? They go to the oldest supported stable version, and move silently when it retires.

What does euclidean score mean? The squared distance, where lower is better, unlike cosine and dot product.

Can you write through a namespace alias? No, aliases are for reads. You write to the real namespace name.

Why call describe_index_stats in a loader? To reconcile what you sent with what the namespace holds once the data is queryable.

What does deletion protection do? It makes a delete request on that index fail with a 403 until you disable it.

Where do you create a document-schema index from the CLI? You cannot. The CLI has no document-schema flag, so use the SDK, REST or Terraform.

What is the safe way to create indexes in a team? Infrastructure as code with the Terraform provider, with deletion protection on, reviewed like any other change. See the Terraform guide.

Why not call Pinecone from browser code? It would expose the API key, and browsers will also fail on the missing CORS header. Put a backend in front.

How to practise

Rehearse out loud, because the failure mode in interviews is not ignorance but unstructured answers. For each scenario above, practise a three-part reply: the mechanism, the check you would run, and the structural fix. Keep a small project where you can show real numbers: a namespace of a few thousand chunks, a hit-rate measurement, and a latency histogram. Being able to say "I measured this" beats any amount of recited documentation.

If the interviewer pushes into platform topics such as dedicated node sizing across teams, bring-your-own-cloud, governance and migration programmes, say honestly that you have seen the shape of them and then describe how you would find out. The next level covers those in depth.

Sixty-second self-test

Answer each aloud without notes, then check yourself.

1. Name the three index kinds and say which API each uses.
2. What does a 200 on upsert guarantee, and what does it not?
3. How do you check that a query reflects a particular write?
4. What is the read-unit cost of a query, and what does top_k change?
5. Why are namespaces preferred over a filter for tenancy?
6. Which limit is 100 per second per namespace, and what do you do when you hit it?
7. What does a large batched upsert return when part of it fails?
8. What happens when you omit the API version header on a REST call?
9. Which roles would you give an ingestion key and a query key?
10. How would you cut over to a re-embedded corpus without downtime?

If you stalled on more than two, reread the matching section of the detailed file and try again tomorrow.

Part two of three. At this level your first queries work, so the problems change. They look like "results are missing", "the bill grew", "it worked until we upgraded" and "we hit a limit at launch". Start with the error table, then the practices ranked by leverage, then practice cards and operational recipes you can paste into a runbook.

Common errors at this level

Beginner's errors still apply. These are the ones that appear once things mostly work.

The pattern in that table is worth naming. Almost none of these are Pinecone failures. They are mismatches between what the code assumed and what the system guarantees: consistency, namespaces, types, versions and limits. When you debug, ask first "which assumption did I make", and the answer is usually in one of those five.

The practices that pay off most, in order of leverage

Ranked by how much trouble each prevents for the effort it takes.

1. One namespace per tenant, decided on day one

This single choice sets your isolation, your read-unit cost and your latency. A query reads only the namespace it targets, so a tenant's queries cost in proportion to the tenant's data, not the whole index. Retrofitting namespaces later means re-ingesting everything, so make the decision before the first production upsert. Check the namespace limit for your plan and, if you will exceed it, raise it with Support early. Do not create an index per tenant, because project index caps are low.

2. Pin versions on purpose

Pin the SDK major (pinecone>=10,<11 for Python), record which API version that implies, and send X-Pinecone-Api-Version explicitly on any raw REST call. Omitting the header means the oldest supported stable version, which moves under you when it retires. Add a CI step that greps for deprecated arguments (dimension=, spec=, pinecone.preview, PineconeAsyncio, retries=), because several Python 10 deprecations emit no warning. Upgrade deliberately, with the migration guide open, in a branch, with the nightly real-project test green.

3. Make every write path report its failures

The most expensive silent bug in vector systems is a loader that loses records and says nothing. Inspect failed_item_count and errors after every batched upsert. End each job by reconciling the number of records you meant to write with the namespace record count once the data is queryable. Make jobs idempotent: with stable IDs a retry just rewrites the same records. Use structured IDs (source#chunk_n) so a re-chunked source is deleted by prefix before its new chunks are written, otherwise stale tails keep surfacing in results.

4. Measure retrieval, not just latency

Keep a small evaluation set of real questions with the source chunks that should be returned. Track hit rate at your top_k before and after every change to chunking, embedding model, filters or reranking. Without it, every tuning discussion is opinion. The RAGAS guide shows how to extend this to answer quality, and Langfuse helps you keep the retrieved context attached to each production answer.

5. Keep metadata lean and responses small

Metadata drives write cost (one write unit per KB of the request), storage and egress. Store what you filter on and a pointer to the source, plus a short excerpt if you need one for display. Turn include_values off unless you need the vectors. Both choices shrink responses, which lowers egress and helps latency.

6. Target indexes by host and reuse the client

Resolve the index host once, put it in configuration, and construct the client once per process. Targeting by name costs a describe call, and creating a client per request throws away connection reuse. Private endpoints require the private host anyway.

7. Separate keys by job, with narrow roles

A query service gets a key with a data-plane viewer role. An ingestion job gets a data-plane editor role. Neither gets control-plane rights, because index creation belongs in infrastructure code. Keys live in a secrets manager and are injected at start. This limits the damage of any single leak to one capability.

8. Bound your retries and plan degradation

The SDK retries transient failures and 429s for you. Add what it cannot: a total deadline per user request, a circuit breaker, and a fallback (fewer results, cached results, or a clear "search is slow" state). A throttled dependency should slow a feature down, not take the application down with it.

9. Alert on the things that run out

Alert on 429 rate, 5xx rate, p95 latency, read-unit burn against the monthly cap on capped plans, index fullness above 0.8 on dedicated read nodes, and scheduled backup failures. The metrics are available through Prometheus on Builder plans and above, and the Prometheus and Grafana guides cover collecting and charting them.

10. Create infrastructure in code and rehearse recovery

Manage indexes with the Terraform provider, with deletion protection on. Schedule backups and restore one into a scratch index to confirm the procedure works. Keep your source data and chunking pipeline reproducible, since document-schema indexes are not covered by backups and re-ingestion is their recovery path.

Practice cards

Short exercises. Each takes ten to twenty minutes on a scratch project.

Operational recipes

Recipes you can paste into a runbook and adapt.

Recipe: first response to a retrieval incident

pc auth status
pc target --show
pc index list
pc index describe -i my-index
pc index stats -i my-index

Those answer which account, which project, which index, how many records and which namespaces. Add -j for JSON you can store in the incident record. Then check the status page, then your own latency and error metrics, then work down the order: did the call fail, are results missing, are results bad, did latency rise, did the bill rise.

Recipe: a read-your-writes helper for tests

The idea, not a full library: after a write, record the x-pinecone-request-lsn value, then query repeatedly until the response header x-pinecone-max-indexed-lsn is at least that value, with a deadline. Fail the test with a message showing both numbers if the deadline passes. This replaces fixed sleeps, which are both slower and flakier.

Recipe: re-ingest a changed document safely

def replace_document(index, namespace, doc_id, new_records):
    # remove old chunks first, so a shorter new version leaves no stale tail
    for page in index.list(prefix=f"{doc_id}#", namespace=namespace):
        index.delete(ids=page, namespace=namespace)
    resp = index.upsert(vectors=new_records, namespace=namespace)
    if resp.failed_item_count:
        raise RuntimeError(f"{resp.failed_item_count} chunks failed: {resp.errors[:3]}")

Consider the window between the delete and the upsert: for a document that must never disappear from search, write the new chunks first under a version-bearing ID, then delete the old version, then keep a version field in metadata.

Recipe: zero-downtime reindex with an alias

1. Ingest the new corpus into tenant-a-v2 by writing to its real name.
2. Run your evaluation set against tenant-a-v2 and compare hit rate with the live namespace.
3. Repoint the alias your readers use from tenant-a-v1 to tenant-a-v2 through the alias API.
4. Watch error rate and latency. To roll back, repoint the alias to tenant-a-v1.
5. After the soak period, delete the old namespace.

Aliases are read-only pointers inside one index, they are not carried through a backup restore, and alias changes are not in audit logs, so log each cutover yourself.

Recipe: scheduled backups and a restore drill

pc.backup_schedules.create(
    index_name="articles",
    name="daily",
    frequency="daily",
    retention_days=90,
)

On a calendar reminder, restore the latest backup into a new scratch index, compare record counts with the source, and run your evaluation set against it. Then delete the scratch index. Remember that backups include only records at least fifteen minutes old at the time of the backup, and that document-schema indexes are not supported.

Recipe: a pre-launch checklist

Work through this list a week before launch.

• Region chosen against residency requirements, and recorded.
• Plan limits checked against projected indexes, namespaces, storage and monthly read and write units.
• Index created by Terraform, with deletion protection on.
• Host stored in configuration, client constructed once.
• API version and SDK major pinned, and written in the service's README.
• Separate ingestion and query keys, narrow roles, secrets manager.
• Loader reports failures and reconciles counts.
• Retry budget, circuit breaker and fallback tested with a 429 drill.
• Prometheus or Datadog metrics wired in, with alerts for 429, 5xx, p95, read-unit burn and backups.
• Backup schedule created and a restore rehearsed.
• Evaluation set committed with a baseline hit rate.
• Runbook contains the first-response commands.

Recipe: cleaning up the CLI on a shared laptop

Run pc auth local-keys list to see the managed keys the CLI created, then pc auth local-keys prune before logging out. pc auth logout alone does not delete those keys on the Pinecone side, so old CLI keys would keep working until you remove them.

Recipe: a quick cost review

Once a month, list your namespaces with their sizes and ask five questions. Which namespaces are largest, and is any shared across tenants that could be split? Did average response size change, which would indicate metadata growth or an include_values flag turned on? Are jobs re-upserting unchanged records? Are any indexes idle and deletable? Is a steady high-volume workload now large enough to price against dedicated read nodes? Record the answers so you can see the trend rather than a single month.

Design mistakes that look fine until traffic arrives

These are choices that pass every test on a laptop and then show up as incidents or invoices.

Treating the shared namespace as free. Putting every tenant in one namespace and filtering by a tenant field works functionally. It also means every query is billed for, and scans, the entire namespace. The cost is invisible while the data is small and enormous when it is not. If you inherited this layout, plan a migration to namespace per tenant using bulk import, and use an alias-style cutover in your application configuration so the move is reversible.

Building access control out of giant filters. A filter that lists every document a user may see will eventually exceed the 10,000-value limit on $in, and long before that it makes requests heavy and hard to reason about. Model access as groups, and store the group on each record. Keep the user-to-group mapping in your own database, where it is easy to change, and compute the small list of groups at query time.

Storing the document body in metadata. It feels convenient because a query returns everything in one call. It inflates write units, storage and egress, and it runs into the 40 KB per-record cap for long texts. Store a short excerpt and an ID that points to your own store, and fetch the full text in a second step only for the handful of results you show.

Re-embedding on every sync. A nightly job that recomputes embeddings and upserts every record pays for inference tokens, write units and time, even when nothing changed. Keep a content hash per chunk in your own database (or in metadata), skip unchanged chunks, and only embed and write the differences.

Assuming approximate search is exact. If a test asserts that a record queried by its own vector is rank one, it will eventually fail, and the failure is not a bug. Test retrieval quality statistically, with a hit rate over a question set, and use fetch for exact lookups.

Ignoring the response size ceiling. A large top_k with values and rich metadata can exceed the 4 MB result limit. Ask for fewer results, leave values off, and keep metadata small. If you need a very large candidate pool, rethink the design: a reranker works best on tens to a hundred candidates, not thousands.

Letting the loader and the server disagree about types. A year stored as a string by one pipeline and a number by another will split your data into two sets that no single filter matches. Validate metadata types at write time, in one shared function used by every ingestion path.

Building on the emulator's behaviour. Pinecone Local is useful, but it speaks an older API version, holds a limited number of records, ignores keys and lacks namespaces management, backups and inference. A green emulator suite does not prove that a real project will behave the same, so keep a periodic test against a real one.

Reading error messages like an operator

Pinecone's errors are informative if you read them completely. Three habits make the difference between a thirty-second diagnosis and an afternoon.

First, read the exception class before the text. Local validation errors (PineconeValueError, PineconeTypeError) mean the request never left your process, so the fault is in your arguments. ApiError subclasses mean the server answered, and the class tells you the status family: unauthorized, forbidden, not found, conflict, failed precondition, or a server-side problem. A payment-required error is a billing issue, not a code issue.

Second, read the whole message. The documented 429 messages say which limit you hit: the per-namespace query rate with the namespace name in the text, a monthly read-unit limit, an embedding-token limit naming the model and input type, or an egress allowance. A wrong-data-plane error names the endpoint you should have called. A 400 about a schema names the field. Copy the full message into the ticket instead of paraphrasing it.

Third, check the version before the code. If a call that worked last month now fails with an attribute, argument or import error, compare the installed SDK major against the one the code was written for. The fix is almost always in the migration guide for that major. Search it for the exact name in the error.

When you cannot tell whether the fault is yours or the service's, reduce the problem. Make the smallest call that fails, with a tiny scratch namespace and one record, from a clean environment with the minimum SDK. If that works, the difference between it and your application is the cause. If it fails, you have a clean reproduction to send to Support, and Support can resolve a request faster when it includes the index name, the namespace, the approximate time, the API version, the SDK version and the full error text.

Habits worth keeping

Write the namespace, index host and API version into the first line of every incident ticket. Keep a scratch namespace for experiments and delete it when you finish. Read the release notes when you upgrade, since limits, pricing and models have all changed during 2026. When documentation pages disagree, as the SDK overview pages and the current SDK release notes sometimes do after a major release, trust the package's own release notes and your own tests over a page that mentions older install instructions. And whenever you add a feature, ask what it does to read units, write units, egress and your retry budget before asking what it does to quality, because both answers decide whether it survives its first month in production.

If you are reaching the point where other teams depend on your Pinecone setup, the next part covers running it as a platform: failure modes, multi-tenant governance, bring-your-own-cloud, upgrade programmes and when another store is the better answer. For comparison while you think about it, the pgvector and Qdrant guides show the same problems solved differently.

Where this picks up

Beginner got you a working index and a first query. Mid-level taught you namespaces, metadata filters, batching, hosted models and the habit of targeting an index by host. Senior is a different job. You are no longer the person who calls query; you are the person other teams depend on when their retrieval layer misbehaves at two in the morning, when the invoice doubles, or when a security reviewer asks who can read which tenant's vectors. Pinecone is a managed service, so you do not run its servers, but you still own everything around them: the shape of the indexes, the identity model, the limits you can and cannot raise, the upgrade path, the cost curve and the incident response.

This guide is written against the stable API version 2026-07 and the SDKs that target it: Python 10, Node.js 9 and Go 7. Where the official documentation disagrees with itself, I say so, because a platform owner must know which page to trust. Most of the disagreements come from the SDK overview pages lagging behind the release notes, and the habit of checking the release notes first is itself a senior skill.

The architecture, and what it implies about failure

You cannot reason about failure modes without a picture of the machine. Pinecone separates a global control plane from regional data planes. The control plane lives at https://api.pinecone.io. It owns organizations, projects, index definitions, backups, billing and users, and it keeps its own metadata database. The data plane is regional and lives on each index's own host name, something like articles-abc123.svc.us-east-1.pinecone.io. That host handles every read and write of your vectors. The two planes fail independently, and that is the first useful fact: a control-plane incident can stop you creating, configuring or deleting an index while queries against existing indexes keep working, and the reverse is possible too. Your runbooks should say which plane a symptom belongs to.

Inside the data plane, a write is appended to a request log and assigned a log sequence number, an LSN. Once that append is durable the API answers 200. The record then lands in an in-memory structure called the memtable, and is later flushed into an immutable file called a slab in object storage. Small slabs are indexed cheaply; background merging produces larger slabs with more sophisticated indexing. A read goes through a query router to executors that scan slabs cached in memory or on SSD, fetch cold slabs from object storage when needed, and merge those results with whatever is still in the memtable.

Three operational consequences follow. First, a 200 on write means durable, not searchable. Pinecone is eventually consistent, and new documents can take up to about a minute to become searchable, particularly for full-text search. Second, the first query against a cold slab is slower than the hundredth; latency percentiles on a rarely queried namespace look different from a hot one, and averaging them hides the tail. Third, because storage is in object storage, there is no node to fail and no rebalancing to babysit on an on-demand index. The failure modes you own are therefore at the edges: limits, consistency, identity, cost and your own client behaviour.

Read-your-writes is the guarantee teams most often assume and Pinecone does not give. The write response carries the header x-pinecone-request-lsn, and a query response carries x-pinecone-max-indexed-lsn. When the second number reaches the first, the write is visible to that query. For a user-facing flow, such as a document the user has just uploaded and immediately asks about, a platform should expose a helper that either waits on that comparison with a bounded timeout or tells the caller honestly that indexing is still in progress. Polling describe_index_stats is the cruder alternative. Letting every team rediscover this independently is how a retrieval feature gets a reputation for "forgetting" documents.

Three index kinds and the one-way door

On API version 2026-07 there are three kinds of index, and the kind is chosen at creation and cannot be changed afterwards. This is the single most consequential design fact in the current product, and it deserves its own section because it determines how you build a platform around it.

A vector index, the classic kind, is created with a dimension, a metric and a vector type. It stores records and exposes the Vectors API: upsert, query, fetch, update, delete, list and describe_index_stats. An integrated-embedding index is created with create_index_for_model and an embed block naming a hosted model and a field map. It stores text that Pinecone embeds for you and exposes the Records API: upsert_records and search. A document index is new in 2026-07. It is created with a schema, stores documents and exposes the Documents API through index.documents.*. A schema may declare at most one dense vector field, at most one sparse vector field and up to 100 string fields with full-text search turned on. The schema declares ranking fields only: every other field in a document is stored and indexed automatically as filterable metadata, and declaring a metadata-only field in the schema is rejected with a 400. The schema cannot be changed after creation.

Each index has exactly one data plane. A request sent to the wrong one is refused, and the error names the right one. There is no conversion path: you cannot turn an existing vector index into a schema index. You create a new index and re-ingest. Existing vector indexes are unaffected, which means a platform will run mixed estates for a long time.

Why does this matter to a platform owner rather than an application developer? Because the data plane decides the client code. A shared internal library that wraps Pinecone has to know which kind of index it is talking to, and the temptation is to hide the difference behind one search() function. Resist the leak in the other direction: do not let each team pick a kind ad hoc. Offer a small number of blessed patterns, record the kind in an index tag so tooling can discover it (tags allow at most 20 per index), and write the decision rule down. A reasonable rule is that new text-heavy workloads that need lexical and semantic ranking start on a document index, while an existing estate, or a workload that needs the Vectors API's single hybrid query, stays on a vector index.

Two details catch people. The first is hybrid search. On a document index, score_by selects exactly one scoring method per search: text, query_string, dense_vector or sparse_vector. Hybrid retrieval there means running two searches and fusing the results client-side, typically with reciprocal rank fusion, which is a rank-combination method that avoids having to make different score scales comparable. The classic Vectors API still supports a single hybrid query with both a sparse and a dense component, on a dotproduct index. The second is that the CLI creates classic, integrated, BYOC, Dedicated Read Node and pod indexes but has no flag for creating a document-schema index; its --schema flag is a metadata-indexing schema, not the new kind. A platform whose automation is built on the CLI will not provision document indexes. Use the SDK, the REST API or the Terraform provider.

Scaling: which limit breaks first

On a managed serverless index there is no node count to tune, so scaling is about limits. The honest way to plan capacity is to list the limits, ask which one your workload approaches first, and know which are fixed and which Support can raise. Most can be raised through Support; the ones that shape architecture are worth memorising.

The per-namespace limits are the ones that surprise teams. For all plans, query, upsert, update and delete are each limited to 100 requests per second per namespace. Upsert is also capped at 50 MB per second per namespace. Exceeding a rate limit returns 429. That ceiling arrived in January 2026, so older sizing documents that assume namespace throughput is bounded only by the index are out of date. Queries are additionally limited to 2,000 read units per second per index. Update-by-metadata and delete-by-metadata are far tighter, at 5 requests per second per namespace and 500 per index, and fetch-by-metadata is also 5 per second per namespace. Anything that loops over tenants issuing metadata-filtered bulk operations hits these quickly.

Think of the ceilings in layers. A single hot namespace is bound at 100 queries per second. The index as a whole is bound by read units per second, and because a query costs read units in proportion to the size of the namespace it scans, a few large namespaces consume that budget much faster than many small ones. The organisation is bound by plan quotas on projects, indexes per project and namespaces per index. Then there are monthly ceilings on Starter and Builder, where read and write units or egress run out and operations are blocked rather than billed.

Where does a request-rate 429 come from, and what should clients do? Pinecone's Python SDK from version 9 retries on its own. REST makes three retries, four attempts in all; gRPC makes five. Retried statuses are 408, 429, 500, 502, 503 and 504 plus transport errors, with jittered backoff, a cap of 60 seconds, respect for Retry-After and a per-host retry budget. All methods are retried, including POST, because data-plane writes are idempotent. A gRPC DEADLINE_EXCEEDED is not retried. And the trap: Pinecone(retry_config=RetryConfig(max_retries=5)) configures the control plane and gRPC but does not reach data-plane REST. A platform that tells teams "retries are configured" must test that claim on the transport actually in use.

Dedicated Read Nodes

On-demand reads are billed per read unit and share Pinecone-managed capacity, which is why per-second ceilings exist. Dedicated Read Nodes, generally available since April 2026 on Standard and Enterprise, change the model: you provision nodes for an index and pay for capacity rather than per read. Reads on such an index are exempt from read-unit and per-second read limits, though egress is still charged. Node types are b1, balanced, and t1, which has roughly four times the compute and memory at about three times the cost. A shard holds 250 GB. The node count is shards multiplied by replicas, and replicas are spread across up to three availability zones, so the usual advice of provisioning n plus one replicas is the availability rule, not a luxury.

read_capacity = {
    "mode": "Dedicated",
    "dedicated": {
        "node_type": "t1",
        "scaling": "Manual",
        "manual": {"shards": 2, "replicas": 2},
    },
}
# Pass it to pc.indexes.create(...) or pc.indexes.configure(...)

Changes apply asynchronously, and read_capacity.status.state moves through Ready, Scaling, Migrating and Error. Automation that reconfigures capacity must wait for Ready, not assume the call's return means the change is live. In the CLI the equivalents are --read-mode dedicated --read-node-type b1|t1 --read-shards N --read-replicas N.

When do dedicated nodes pay off? When the workload has steady, high query volume where per-read billing would exceed provisioned capacity, when you keep hitting the 100 requests per second per namespace error message that itself recommends dedicated nodes, or when you need predictable latency without sharing. They are the wrong choice for spiky or low-volume indexes, where on-demand's pay-for-what-you-read billing wins because an idle on-demand index costs only storage. A useful way to decide is to compute the monthly read-unit spend of an index from your metrics, compare it with the price of the smallest provisioned configuration that survives your peak with a spare replica, and revisit the decision quarterly.

A dedicated index introduces failure modes that on-demand does not have. When indexFullness reaches 1.0, writes are blocked while reads continue. That is a capacity incident of a kind you cannot have on-demand, and the metrics pinecone_db_index_fullness, pinecone_db_index_memory_fullness and pinecone_db_index_storage_fullness exist so you alert before it happens; the guidance in this guide is to alert above 0.8. CPU is tracked by pinecone_db_drn_cpu_usage_percent. Setting replicas to 0 disables the index while keeping its data, which is a deliberate way to park an index, and a dangerous thing to leave in a script. Restoring a backup can take a read capacity argument, so a restored index need not come back on-demand.

Security: the trust model

Pinecone's security posture is a set of layers, and a platform owner has to know which are on by default and which you must configure. Data is encrypted with AES-256 at rest and with TLS 1.2 in transit, over both HTTPS and gRPC. Enterprise adds customer-managed encryption keys, using AWS KMS and configured per project. Beyond that, the questions are about identity and network.

Identity has three kinds of principal: users, service accounts and API keys. A role is bound to a resource, an organisation or a project, and a principal's effective permissions are the union of every role bound to it. Organisation roles are OrgOwner, OrgManager, OrgMember and OrgBillingAdmin. Project membership roles are ProjectOwner, ProjectManager and ProjectMember. Project access roles are ProjectEditor, ProjectViewer, ControlPlaneEditor, ControlPlaneViewer, DataPlaneEditor and DataPlaneViewer. In July 2026 the old User role was renamed Manager, with OrgMember and ProjectMember added, so documentation written before then uses different names.

The point of this vocabulary is least privilege expressed as a pattern. An ingestion pipeline's key gets DataPlaneEditor. A query service's key gets DataPlaneViewer. A key that Terraform or an ops tool uses for index lifecycle gets ControlPlaneEditor. API keys cannot hold ProjectOwner, ProjectManager or ProjectMember, which is a useful guardrail: a leaked key cannot add members. Custom roles on keys need Standard or Enterprise; on Starter and Builder, keys must have all permissions, which is a reason for any regulated workload to be on a plan that supports separation.

Keys are project-scoped, shown only once at creation, and deletion is immediate and irreversible, so rotation is a two-step operation you have to plan: create the new key, roll it out, confirm the old one has no traffic, then delete. Because a key is scoped to a project, project boundaries are your blast-radius boundaries. Put production, staging and each sensitive team in separate projects rather than relying on naming. Projects per organisation are limited by plan, so that design interacts with the earlier limits table.

Administration has its own identity. The Admin API, which manages organisations, projects, API keys, service accounts and role bindings, does not accept an API key. It uses OAuth client credentials from a service account, via PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET, and an API key can't call it. In Python, Admin() exposes api_keys, service_accounts, role_bindings and invites. This separation is deliberate: it means the credential that serves queries cannot mint other credentials.

Network controls are on Enterprise. Private endpoints use AWS PrivateLink or Azure Private Link, are configured per project, and allow up to ten per project. Using one means using the private DNS host for the index. There is no private endpoint for managed indexes on GCP; BYOC on GCP uses Private Service Connect. The practical consequence for a Gulf or Egyptian employer on AWS is that PrivateLink to a supported region keeps retrieval traffic off the public internet, but you must choose a region on the supported list at index creation, because an index's cloud and region cannot be changed later. Check data-residency requirements before the region decision, not after, because the available serverless regions are AWS us-east-1, us-west-2, eu-west-1, eu-central-1 and ap-southeast-1, GCP us-central1 and europe-west4, and Azure eastus2. There is no Middle East region in that list. For workloads with strict residency rules, BYOC, covered later, is the route that puts the data plane in an account and region you choose. The Python SDK's Azure region enum also lists germanywestcentral where the docs region table does not, so do not plan on it without confirming.

Audit logs are on Enterprise, available to organisation owners, written to S3 roughly every 30 minutes as JSON. They cover control-plane and management events: changes to organisations, projects, indexes, backups, users, API keys and private endpoints. They do not include namespace alias changes, and they are not a record of queries. The documentation recommends S3 Object Lock in compliance mode on the destination so logs cannot be altered. If your compliance story needs a record of who queried what, you have to build it at your own service layer, because Pinecone's audit log will not give it to you.

Secrets, the client and the supply chain

The service's own security is half the story; the other half is how your organisation handles the credentials and the software that touches them.

Start with where keys live. They belong in environment variables or a secrets manager such as Vault, never in browser code. The CORS error No 'Access-Control-Allow-Origin' header is present on the requested resource is Pinecone refusing a browser's cross-origin call, and the correct fix is to call from a backend; the incorrect fix is any workaround that ships the key to the client. The Python SDK masks keys in repr(), showing only the last four characters, and version 10 masks token responses, but to_dict() still exposes the token, so a logging helper that serialises client objects can leak. Treat SDK objects as sensitive in logs.

The SDK has environment variables that change behaviour, and each is a supply-chain surface: PINECONE_API_KEY, PINECONE_CLIENT_ID, PINECONE_CLIENT_SECRET, PINECONE_CONTROLLER_HOST, PINECONE_ADDITIONAL_HEADERS and PINECONE_GRPC_SCHEME. Explicit arguments always win over variables. Two deserve a security review. PINECONE_CONTROLLER_HOST redirects the control plane, so an attacker or a misconfiguration that sets it can send your key to another host. PINECONE_GRPC_SCHEME=http against a public host sends the key in cleartext, and Python 10 warns about it. It exists for Pinecone Local and must never appear in a production manifest. A policy check in CI that rejects both in production configuration is cheap insurance.

Version pinning is the final supply-chain control. The package name is pinecone; the older pinecone-client does not work for upgrades from version 6.0.0 on, and having both installed produces the import error cannot import name 'Pinecone' from 'pinecone'. Pin the major version, for example pinecone>=10,<11, lock a hash-checked requirements file, and send the X-Pinecone-Api-Version header explicitly. The Python 9 and 10 SDKs ship a compiled Rust extension for gRPC inside the wheel. Wheels exist for common platforms, including Windows on x86-64, but building from source needs a Rust toolchain, so an unusual base image, such as a minimal distribution on a less common architecture, either needs to be on the supported list or needs a build stage. Scan the resulting image with Trivy like any other, and build it from a pinned base as the Docker guide's senior level describes.

Multitenancy as a platform feature

If your platform serves many teams, or your product serves many customers, multitenancy is where the design either holds or fails. Pinecone's recommendation is one namespace per tenant. A namespace is a partition inside an index, every read and write targets exactly one, and a query scans only that namespace. The pattern isolates tenants from each other's data, lowers cost because a query reads only the tenant's own data, and is faster for the same reason. The cost point is worth stating in numbers from the pricing model: a query costs one read unit per gigabyte of the namespace searched, with a minimum of 0.25. Querying a 1 GB tenant namespace costs about 1 read unit; filtering a 100 GB shared namespace down to the same tenant costs about 100. Multiply by query volume and the difference is the whole bill.

Namespaces are created implicitly on the first upsert, or explicitly with create_namespace, which can declare which metadata fields to index. Prefer the explicit call in a platform, because implicit creation means a typo in a tenant identifier silently creates a new, empty tenant. Wrap tenant provisioning in one function that creates the namespace, records it in your own tenant registry and is the only code path allowed to do so. Likewise deprovisioning: delete_namespace removes a tenant's data and costs 5 write units, but backups, exports and any caches you hold elsewhere are yours to clean, which matters when a customer exercises a deletion right.

Namespace names are limited to 512 ASCII characters, and the count per index depends on plan, from 100 on Starter to a million on Enterprise. That makes namespace-per-tenant a design for up to hundreds of thousands of tenants on Standard and up to a million on Enterprise, per index, and beyond that you shard across indexes. A tenant too large to share an index gets its own, with namespaces inside it for its sub-groups. Large tenants are also where the per-namespace 100 requests per second ceiling arrives first, because all of a big tenant's traffic hits one namespace.

Namespace aliases, generally available at the end of September 2026 on 2026-07, solve the re-index problem. An alias is a stable, repointable name for a namespace in the same index. Reads can go through an alias; writes cannot. An index may have up to 1,000 aliases, an alias costs nothing, and aliases do not carry over when an index is restored from a backup. The cutover pattern is simple and powerful: readers query the alias, say tenant-acme; you ingest a rebuilt corpus into tenant-acme-v2 by writing to the real namespace name; when verification passes, you repoint the alias from tenant-acme-v1 to tenant-acme-v2 in one operation, and later delete the old namespace. A rollback is repointing back. The management endpoints live under /namespace-aliases on REST for 2026-07 and later. Two cautions: alias changes do not appear in the audit log, so record them yourself, and a restore will not bring them back, so keep alias definitions in code.

The limits of the pattern deserve honesty. Namespaces isolate data for reads, but they share the index's per-second ceilings and read-unit budget, so a tenant that floods an index can degrade the others on on-demand capacity. Isolation of capacity needs a separate index, or a Dedicated Read Nodes index for a big customer. And namespace-level isolation is logical: access control is at the project and role level, not per namespace. If tenant A's key can read the index, it can read tenant B's namespace by naming it. Enforce tenant boundaries in your own service layer, which holds the key and decides which namespace a request may touch; never hand a tenant-scoped decision to the client.

Cost as a model you can forecast

Pinecone's serverless bill is predictable if you hold the model in your head. There are five components: storage, reads, writes, egress and a few feature charges. Plan minimums sit on top: Starter is free, Builder is a flat $20 per month where operations stop at quota rather than bill overages, Standard has a $50 monthly minimum and Enterprise $500.

Storage is billed per gigabyte-month, and you can estimate it: records multiplied by the sum of the ID size, four bytes times the dimension, eight bytes times sparse non-zeros and the metadata size. One million vectors of 1,536 dimensions with 1 KB of metadata each comes to roughly 7.15 GB. Reads are read units: a query costs one per gigabyte of the namespace searched, with a 0.25 minimum, and top_k and the include flags do not change it. A document search costs the same as a query. Fetch costs one read unit per ten records, minimum one, and a list call costs one for up to 100 IDs. Writes are write units: one per kilobyte of the request plus the record being replaced, minimum five, and update and delete follow the same model. Deleting a namespace, or delete_all, costs five. Egress is the gigabytes of record data returned, with monthly allowances of 1 GB on Starter, 10 GB on Builder and 100 GB on Standard and Enterprise, and per-gigabyte overage beyond them on the paid tiers. Egress began to be metered on 1 September 2026, which is why a bill that was stable in August can move in September for a workload that returns many large payloads.

Feature charges include import at $0.25 per GB, charged even for failed rows, backup and restore billed on index size, and reranking: cohere-rerank-4-fast is $2 per 1,000 units, where a unit is one query plus up to 100 documents with about 500 tokens of chunking. Reranker choice carries a governance lesson. cohere-rerank-3.5 was deprecated in July 2026, and since 31 August 2026 its requests are served by cohere-rerank-4-fast. Scores differ between rerankers, so any similarity threshold tuned against the old model needs re-tuning, and nothing warned you in code. Models in your retrieval path are dependencies with a lifecycle, so track them in the same register as libraries.

The levers, in rough order of leverage, are structural. Use a namespace per tenant so queries scan small partitions. Use bulk import for initial loads instead of millions of small upserts. Move steady, heavy read traffic to Dedicated Read Nodes when the arithmetic favours it. Set include_values=False unless you need the vectors. Delete idle indexes, remembering that an idle serverless index costs only storage. And avoid paying for read capacity in indexes nobody queries by auditing usage monthly.

Versions, upgrades and migrations

Pinecone's API is versioned by date, and a new stable version and a release candidate arrive quarterly. Each stable version is supported for at least twelve months, giving at least nine months to migrate. The version is selected with the X-Pinecone-Api-Version header, and here is the rule that causes outages: if you omit it, requests go to the oldest supported stable version. When that version is retired, your requests silently move to the next oldest, and that move can contain breaking changes. Always send the header, and set it in one shared client factory rather than per call site.

SDKs are pinned to API versions, and upgrading the SDK is how you change version. Python 10, Node.js 9 and Go 7 target 2026-07; Python 9, Node.js 8 and Go 6 target 2026-04; Java's latest line, 6.x, targets 2025-10, with newer Java SDKs listed as not yet available. You can override the version with an additional header, but pinning an older API version does not bring back the older SDK's types or serialisers, so mixing is unsupported in practice. A platform with several languages will therefore have teams on different API versions for a while. Track that matrix and the retirement dates, and set an owner.

Pay special attention to the changes that do not announce themselves. In Python 10, the deprecated dimension=, metric=, vector_type= and spec= arguments on create still work and do not emit a DeprecationWarning, and the same goes for replicas=, pod_type= and serverless_read_capacity= on configure. A deprecation you cannot see in test output is a deprecation you will meet in production later. Make it visible with code search: grep for dimension=, spec= and attribute reads like .dimension. Also change exception handling. Local validation failures raise PineconeValueError or PineconeTypeError, and neither is an ApiError, so a handler that catches only API errors lets them through; catch PineconeError as the base. Both the older exception names such as PineconeException and NotFoundException are legacy aliases slated for removal in a future major version.

The upgrade procedure I recommend to a platform team is boring on purpose. Read the migration guide and the release notes. Pin the new SDK in a branch. Run the contract tests described below against a real, disposable index. Deploy to a canary service with the API version header explicit. Compare error rates, latency and result overlap against the old version for a defined period. Roll out. Because Pinecone Local speaks only API 2025-01, and SDKs that target 2026-07 send that version by default, do not assume Local covers the new SDK; test the classic vector path against it and everything else against a real index.

Moving an existing estate to document indexes is a data migration, not an upgrade. The steps are: design the schema, which is permanent; create the new index; export or re-derive the content and load it, using bulk import if it is large, with JSONL for document indexes; run both indexes in parallel and compare retrieval quality on a fixed evaluation set, using something like RAGAS; then move traffic and retire the old index. Backups do not support document-schema indexes, so your recovery plan for the new kind is re-ingest from the source of truth, which means that source of truth must be retained. Pod-based indexes are the other migration: pods are legacy, organisations signing up on or after 18 August 2025 cannot create them on Standard or Enterprise, and the free pod-to-serverless migration supports up to 500 million records and usually completes in under 30 minutes according to the FAQ. Pod billing is per pod-minute whether or not the pod is used, so the longer a pod index lingers, the more it costs.

Backups, recovery and the data lifecycle

A vector index is derived data in most architectures, but rebuilding it can mean re-embedding a whole corpus, which is slow, costly and sometimes impossible if the source has changed. Recovery planning therefore has two layers: Pinecone-side backups, and your own ability to rebuild from the source of truth.

A backup is a static, non-queryable copy of a serverless index, in the same project, cloud and region. It contains only records present at least 15 minutes before the backup. You create one with pc.backups.create(...) or the older pc.create_backup(...), and restore with pc.create_index_from_backup(backup_id=..., name=..., read_capacity=...). Backups can be scheduled, daily, weekly or monthly, with retention, using pc.backup_schedules.create(index_name=..., name=..., frequency="daily", retention_days=90); one schedule per index, available from API 2026-04. The CLI forms are pc index backup create, pc index restore and pc index restore list|describe. Backup limits by plan are 500 per project on Standard and 1,000 on Enterprise. The metric pinecone_db_scheduled_backup_failure_total tells you when a schedule failed, and you should alert on it, because a backup that silently stopped is discovered only during the incident that needs it.

Know what a backup does not cover. It is the same region and cloud, so it protects against data damage rather than a regional outage. Cross-region restore within the same cloud exists, but through the unstable API version and REST only, which makes it unsuitable as a dependable plan. Document-schema indexes are not supported. Namespace aliases do not carry over. Collections, the older snapshots, exist only for pod indexes. And a restore creates a new index, with a new host, so every consumer must be repointed; that is the one part of recovery that your platform's configuration management has to make quick. Keep the host in one place. Once a quarter, restore the latest backup of a representative index into a scratch project, run your evaluation queries against it and record the elapsed time; that measurement is your real recovery time, and the drill also tells you whether the source corpus needed for a rebuild is still retained.

Observability and governance

Pinecone exposes metrics to Prometheus on Builder and above through HTTP service discovery, so the same tooling that watches the rest of your estate can watch this too. The scrape configuration points at https://api.pinecone.io/prometheus/projects/PROJECT_ID/metrics/discovery with a bearer credential, a one-minute refresh and the same authorisation on the job. Because the credential is a project API key, give it a read-appropriate role and store it as a secret like any other. Datadog is supported as an integration, and New Relic works through the Prometheus path. For tracing, Traceloop or OpenLLMetry and Langtrace instrument calls, and the Java SDK has OpenTelemetry support; the OpenTelemetry guide covers the shape of that pipeline, and Langfuse is the natural place to correlate retrieval with generation.

The metrics worth dashboards: volume with pinecone_db_record_total and pinecone_db_storage_size_bytes; operation counts and durations, pinecone_db_op_query_count and pinecone_db_op_query_duration_sum and their upsert, fetch, update, delete and list siblings, where durations are in milliseconds; usage with the read-unit and write-unit counters; backup failures; and, on dedicated indexes, CPU and the three fullness gauges. Labels include index_name, cloud, region, capacity_mode, instance and shard_id. Alert on the rate of 429 responses as seen from your own clients, 5xx rate, p95 query duration, read-unit burn rate against budget, fullness above 0.8 on dedicated indexes, and backup failures. Also watch the provider's status page. One useful habit is to alert on your own client-side latency in addition, since the server metrics will not show network or retry delays that your users experience.

Governance is how a platform stays safe as teams multiply. The mechanisms that carry the most weight are small and procedural. Provision indexes only through code, with the Terraform provider, version 4 at the time of writing, using version = "~> 4.0". It manages pinecone_index in its serverless, integrated, BYOC, pod, on-demand, dedicated and schema forms, plus pinecone_collection, pinecone_project, pinecone_api_key, pinecone_service_account and pinecone_role_binding. Index and collection resources authenticate with PINECONE_API_KEY; organisation-level resources use PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET. That means the pipeline that applies infrastructure holds two kinds of credential, and you should scope each narrowly. The Terraform guide's state and review practices apply directly, since state files will contain whatever the provider returns, including key material for pinecone_api_key; protect state accordingly.

Incident playbooks

A playbook says what to check first, in what order, and what the safe action is. These are the incidents a platform owner will meet, in the order they tend to appear.

Queries returning 429. First read the message. The wording distinguishes the cause. A per-namespace message, "You've reached the query QPS limit for namespace ... Pace your queries, consider Dedicated Read Nodes for your index, or contact Pinecone Support", means one namespace is over 100 requests per second. A message about the monthly read-unit limit means a Starter or Builder quota is spent and operations are blocked until you upgrade or the period resets. A message about embedding tokens per minute names the model and input type, meaning the hosted inference limit for the project. An egress message means the monthly allowance on Starter or Builder is gone. The fixes are different: spread load across namespaces, upgrade, batch inference calls, or reduce returned payloads. Mitigate first by shedding or caching the heaviest callers, then fix the cause.

Fresh data missing from results. Almost always eventual consistency. Compare the LSN headers for the write and the query. If the write's LSN is beyond the index's max indexed LSN, wait. If it is not, check you are querying the right namespace, the right index host and that any filter matches how the metadata was written. Check describe_index_stats for namespace record counts. For document indexes, up to about a minute is normal for full-text search.

Writes failing or ingestion quietly short. On a Dedicated Read Nodes index, check indexFullness; at 1.0 writes are blocked while reads continue, and the fix is to add shards, so the response is an index configure and a wait for Ready. On any index, check the response of bulk upsert for failed_item_count and errors rather than relying on exceptions, and check you are inside 1,000 records or 2 MB per batch. A 400 with a dimension mismatch means the pipeline's embedding model changed under it.

Authentication failures. 401 UNAUTHENTICATED means a wrong, missing or other-project key; check which project the key belongs to, since keys are project-scoped. 403 can be a plan quota, such as maximum projects or indexes, or deletion protection on a delete; read the message. 402 means billing is delinquent or the account is deactivated, and no technical change fixes it. Calling the Admin API with an API key fails by design.

After every incident, write down the detection gap: which signal should have told you earlier, and add the alert.

Bring your own cloud, and where Pinecone stops

Bring your own cloud, generally available since 25 August 2026 for Enterprise, runs the data plane in your own AWS, GCP or Azure account. The data plane lives in your virtual network, on your Kubernetes cluster, with object storage in S3, GCS or Azure Blob, and since 1 September metadata is stored in FoundationDB inside your cluster. The control plane stays at Pinecone. The design is pull-based and zero-access: an agent inside your cluster pulls operations, stored as custom resources, and no inbound access from Pinecone is required. Only operational metrics and traces leave your account. You deploy with a Pulumi wizard from the pinecone-io/pulumi-pinecone-byoc repository, which needs Python 3.12 or later, uv, Pulumi, kubectl and the cloud's CLI, plus administrative rights: AWS AdministratorAccess, GCP roles/owner or Azure Owner. Defaults include a VPC CIDR of 10.0.0.0/16 on AWS and Azure or 10.112.0.0/12 on GCP, deletion protection on, and public access either on or restricted to PrivateLink, Private Service Connect or Private Link. Indexes use a byoc deployment type, and the CLI takes --byoc-environment.

BYOC is the answer to a particular question: data must stay in an account and region you control, which for some Gulf and Egyptian regulated workloads is the deciding requirement given the managed regions listed earlier. It is not free. You now operate a Kubernetes cluster's worth of infrastructure and its cost, you need to wire Prometheus inside your own network, and you hold the encryption keys, using your own KMS. Choose it for a compliance reason, not a performance one.

Now the question every senior engineer should be able to answer without defensiveness: where does Pinecone stop? Pinecone is a managed, serverless vector and document database. It is the right default when you want retrieval without operating a search cluster, when namespace-per-tenant fits your tenancy, and when you value elastic cost for spiky workloads.

It is a poorer fit in several situations. If you already run Postgres and your vectors are a column on rows that you join and update transactionally, pgvector keeps one system and one transaction boundary, and extra network hops to a second store are overhead you may not need at modest scale. If you need to run in your own environment with full control of the engine, or on-premises with no managed dependency, then self-hosted engines such as Qdrant, Milvus or Weaviate are open choices, while FAISS and Chroma suit embedded or local use. If your workload is mostly keyword search with a minor semantic part, a dedicated search engine may fit better, although document indexes with full-text search narrow that gap. If you need relational filtering, joins or aggregates over metadata, Pinecone's flat metadata, which cannot hold nested objects or nulls, is a hard constraint. If you need exact nearest neighbours rather than approximate, remember that queries are approximate and a query by an existing ID does not necessarily return that ID; use fetch for exact lookup. And if a hard requirement is a region Pinecone's managed offering lacks, BYOC or another system is the answer.

Running Pinecone as a platform for other teams

Everything above is a feature list until it becomes a service other teams can use without thinking about it. The platform's job is to make the safe path the easy path, and a handful of artefacts do most of the work.

A provisioning module that creates an index, its tags, deletion protection, the right service accounts and role bindings, and its alerts, from a few inputs: team, environment, kind, region and capacity mode. Teams should not call the control plane directly in production.

A client library that wraps the official SDK and bakes in the decisions: API version header set, host resolved from configuration, timeouts, a documented retry posture tested on the actual transport, tenant-to-namespace mapping through one function, and logging that never serialises credentials. The library is also where the LSN-aware "wait until visible" helper lives, and where result and error types are normalised so that teams are not each rediscovering that local validation raises PineconeError rather than an API error.

A contract test suite that runs against a real disposable index in CI: create, upsert, wait for visibility, query, filter, delete, tear down. It catches SDK and API behaviour changes before production does, and it is the gate for SDK upgrades. Pair it with a small evaluation set of queries with expected results, so a change in embedding model or scoring shows up as a number. Pinecone Local can speed the inner loop for classic vector indexes, but it ignores keys, speaks 2025-01, holds at most 100,000 records per index, and lacks import, backups, namespace management, Inference and Assistant, so it never replaces the real-index suite.

A change calendar: API retirement dates, SDK majors, model deprecations such as the reranker routing change, plan-limit changes announced in the release notes, and the quarterly restore drill. Someone owns each row, and the platform's monthly review reads the Pinecone release notes the way it reads a security advisory feed. In 2026 alone the release notes changed per-namespace limits, $in limits, billing for egress and the meaning of a reranker name; nobody is going to notice those by accident.

Finally, a support path. Know the plan's support level, who in your organisation may open tickets, and which limits you have already asked Support to raise, since most limits can be raised. Keep the evidence ready: index names, hosts, request IDs, timestamps and metrics, because a ticket with those gets answered faster than one without.

The review checklist

Use this when reviewing a design document, a pull request or an existing deployment. It is deliberately short enough to use.

Design

• Which index kind, and why? Is the schema, if any, reviewed as permanent?
• Which cloud and region, checked against residency and private endpoint support before creation?
• Is there one namespace per tenant, with a single provisioning path and a registry?
• Which limit binds first: per-namespace requests, per-index read units, or a plan quota? What is the plan if it is hit?
• Is the source of truth retained so the index can be rebuilt, including text, model version and schema?

Client code

• Is X-Pinecone-Api-Version explicit, and the SDK major pinned?
• Is the index targeted by host rather than name?
• Are bulk upserts checked for failed_item_count and errors?
• Are local validation errors caught as PineconeError, and does the retry configuration reach the transport in use?
• Is there a visibility strategy for read-after-write flows, not a sleep?
• Is include_values off unless needed, and top_k sensible for the 4 MB response limit?

Security

• Does each key have the narrowest role, and is each held in a secrets manager?
• Are production and non-production in separate projects?
• Are PINECONE_GRPC_SCHEME and PINECONE_CONTROLLER_HOST absent from production configuration?
• Is SSO on, with role assignment driven by groups? Are private endpoints, CMEK and audit logs enabled where the data classification calls for them?
• Is any TLS verification disabled?

Operations

• Are deletion protection, tags and an owner set on every index?
• Are Prometheus metrics scraped, with alerts for 429, 5xx, p95, read-unit burn, fullness and backup failure?
• Is there a scheduled backup, and a restore drill within the last quarter?
• Is the migration plan for any deprecated arguments or pod indexes dated?

Cost

• Can each team see its own read, write and egress consumption?
• Has the on-demand versus dedicated arithmetic been done for the busiest indexes in the last quarter?
• Are idle indexes found and removed?

The complete picture

Pinecone is a managed vector and document database whose power comes from separating things: a global control plane from regional data planes, reads from writes, storage from compute, and tenants from each other by namespace. Those separations give you elasticity and low operational burden, and they define where trouble arrives. Writes are durable but eventually searchable. The kind of an index is fixed at creation, so schema and data-plane choices are one-way doors. Limits are per namespace, per index and per plan, and the per-namespace 100 requests per second ceiling is the one that finds hot tenants. Dedicated Read Nodes move capacity from a metered model to a provisioned one, with a new failure mode when an index fills. Security is a layered trust model of scoped keys, service accounts, role bindings, private networking, customer-managed keys and audit logs, and its gaps, such as no query audit trail and a local emulator that ignores keys, are yours to cover. Cost is a model you can forecast from namespace size, request volume and egress. Versions move quarterly, with changes that do not warn, so a calendar and a contract test suite are the control.

A platform owner turns that into a small set of products: a provisioning module, a client library, a test suite, dashboards and alerts, a restore drill, a change calendar and an honest service level objective. When something goes wrong, the question to ask first is which plane, which limit, which version and which identity, and the playbooks above turn that into an order of checks.

Where the series leaves you

You began with a first index and a first query. You can now design the estate that a company's retrieval depends on, argue the choice of Pinecone against the alternatives with numbers, defend it to a security reviewer, run it through an upgrade and an incident, and hand other teams a path that does not require them to learn all of this. The next steps are practical. Run the restore drill. Inventory your API versions and keys. Put the change calendar in front of someone who will own it. Then read the neighbouring guides in this series for the pieces around the database: LangChain and LlamaIndex for orchestration, RAGAS and Langfuse for evaluation and tracing, and Terraform and Kubernetes for the infrastructure you will wrap it in.

Sources

• Pinecone documentation home
• 2026 release notes
• API versioning
• Rate limits
• Architecture
• Adopt the Documents API
• Import data
• Design for multitenancy
• Dedicated Read Nodes overview
• Namespace aliases
• Understanding cost
• Bring your own cloud
• Monitoring
• Security overview
• Manage RBAC
• Configure private endpoints
• Configure audit logs
• Migrate a pod-based index to serverless
• Terraform integration
• Python SDK v10 migration
• Pinecone CLI v1.0.0 release

How senior interviews differ

At this level nobody asks you what a namespace is. The interviewer wants to know whether you can own Pinecone as a dependency that other teams build on: whether you reason from limits and failure modes rather than from the happy path, whether you can say what you would measure, and whether you can argue a trade-off with someone who controls the budget. The strongest answers share a shape. They state the requirement and the constraint that decides the design, name the one or two facts about the tool that make a naive answer wrong, give the design, and finish with how it fails and how you would notice. Keep that shape in your head as you read the questions below. All facts here are as of API version 2026-07; where a number has changed recently, saying so signals that you read the release notes.

System-design prompts

Design multi-tenant retrieval for a SaaS product with 50,000 customers

Start by asking what varies: tenant size, query rate per tenant, whether tenants share any content and what residency rules apply. Then commit. One namespace per tenant is the recommended unit, because a query scans only that namespace, which isolates data, lowers cost and speeds queries. Read units scale with the size of the namespace searched, roughly one per gigabyte, so a small tenant's query is cheap, where filtering a large shared namespace down to one tenant would pay for the whole thing.

Then the limits. Fifty thousand namespaces fits in an index on Standard, where the ceiling is 100,000 namespaces per index, with headroom to grow; on Enterprise it is a million. Say that you would watch that ceiling and plan to shard tenants across indexes before reaching it. The per-namespace ceiling of 100 requests per second for query, upsert, update and delete is where the largest tenants will hurt first, so identify the top handful and give them their own index, ideally on Dedicated Read Nodes, with namespaces inside for their sub-groups. The index also has a read budget of 2,000 read units per second, which large namespaces consume faster than small ones.

Provisioning goes through one code path that creates the namespace explicitly and records it in a tenant registry, because implicit creation on first upsert turns a typo into a silent new tenant. The service layer, not the client, maps a request to a namespace, because Pinecone's access control is at project and role level and a key that can read the index can read any namespace by naming it. Deprovisioning deletes the namespace, which costs five write units, and also clears whatever you keep elsewhere.

Close with failure modes: a noisy tenant degrading others on shared on-demand capacity, a tenant outgrowing the per-namespace ceiling, and a model change that requires re-embedding. For the last, describe the namespace alias cutover. A weak answer says "one index per tenant", which hits index quotas of 20 per project on Standard and 200 on Enterprise almost immediately, or says "one namespace and a filter on tenant ID", which pays the read cost of the whole data set on every query.

Design the ingestion pipeline for 200 million documents with daily updates

Separate the initial load from the steady state. For the initial load, Pinecone recommends bulk import for datasets of roughly ten million records or more: files in Parquet for vector indexes or JSONL for document indexes sit in S3, GCS or Azure storage, and an import reads them through a storage integration. Mention the limits briefly, ten gigabytes per file and one terabyte per import on on-demand indexes, and the price of $0.25 per gigabyte, billed even for rows that fail, so you validate files before importing. Use the CONTINUE error mode only if you will reconcile the failures afterwards.

For the steady state, batched upserts of at most 1,000 records or 2 MB per request, concurrent, with the structured ID convention doc_id#chunk_n so that you can list and delete a document's chunks by prefix. Say what you check after every bulk call: in the current Python SDK a partial failure does not raise, so you inspect failed_item_count and errors. Say what you do about freshness: a 200 means durable, not searchable, so a user-facing flow compares the LSN headers on the write and on a query, with a deadline.

Then the rate ceiling: 100 write requests per second and 50 MB per second per namespace, so a pipeline writing a single namespace is bound there regardless of how many workers you add. Idempotency is the reason retries are safe; Pinecone's SDK retries POST for exactly that reason, and the same ID overwrites. For updates that touch many records by filter, name the tight limits: update-by-metadata is limited to 5 requests per second per namespace, so you design to avoid it.

Finish with the source of truth. The index is derived data, so the raw text, chunking version and embedding model version live in storage you control, and the pipeline can rebuild the index if needed.

A product team wants to switch embedding models. How do you do it without downtime?

The key fact is that vectors from two models are not comparable, so you cannot mix them in one namespace and expect meaningful scores. The answer is a parallel build. Create a new namespace, or a new index if the dimension or metric differs, and ingest the whole corpus into it with the new model, writing to its real name. Readers query an alias in the current API, so the cutover is a single repoint of the alias from the old namespace to the new. Before the cutover, run a fixed evaluation set against both and compare, using something like retrieval-quality metrics from an evaluation framework. After the cutover, keep the old namespace for a rollback window, then delete it.

Add the cautions that mark seniority. An alias is a pointer for reads only; writes must go to the real namespace, so your ingestion needs to know which version is live. Aliases do not appear in the audit log and are not restored from a backup, so keep their definitions in code and log the change yourself. If the new model's dimension differs from the index's, a new namespace is not enough, because dimension is fixed per index. Cost: double the storage and the embedding cost for the overlap period, and bulk import for the load. Mention hosted models by name only if you are sure: llama-text-embed-v2 supports several dimensions, and the multilingual model is 1024-dimensional.

How would you serve a read-heavy workload of several thousand queries per second?

Establish the shape first: is it one index, many namespaces or one hot namespace? The limits drive the answer. Per namespace, queries are capped at 100 requests per second, and per index read units are capped at 2,000 per second. If the traffic spreads across many namespaces, the namespace ceiling is not the problem; the index read budget may be. If it is concentrated in one namespace, no amount of client retries helps. The tool is Dedicated Read Nodes, where reads are exempt from per-second and read-unit limits, and you pay for provisioned capacity.

Explain the sizing: a shard holds 250 GB, nodes are shards times replicas, replicas spread across up to three zones, and you provision n plus one for availability. Node type b1 is balanced, and t1 has about four times the compute and memory at about three times the cost, so you load test to find which fits the latency target. Then the new failure mode: when index fullness reaches 1.0 writes are blocked while reads continue, so you alert on fullness above 0.8 and have a runbook to add shards, remembering that changes apply asynchronously and you wait for the state to return to Ready.

Then cost reasoning, since the question is secretly about money: compute the monthly read-unit spend on on-demand and compare with the dedicated configuration; dedicated wins at steady high volume and loses for spiky traffic. Add the caching layer the application should have regardless, and measure p95 at the client.

Where would you not use Pinecone?

This question tests honesty. A strong answer lists concrete conditions rather than preferences. When the vectors are a column on relational rows that you update and join transactionally at modest scale, pgvector avoids a second system. When the data must stay in an account and region you control and the managed regions do not include one you can use, you either choose BYOC, which is Enterprise and means operating the infrastructure, or a self-hosted engine such as Qdrant or Milvus. When the metadata is deeply nested or needs joins and aggregates, Pinecone's flat metadata, with no nested objects or nulls, is a hard constraint. When the use is a small local experiment, FAISS or Chroma is simpler. When a requirement is exact nearest neighbours, remember that queries are approximate. Then say what you would give up by leaving: no operations burden, elastic cost, namespace multitenancy at scale.

Incident-response questions

Queries suddenly return 429. Walk me through it.

Read the message before touching anything, because the wording tells you the cause. A per-namespace message about the query rate limit means one namespace exceeded 100 requests per second. A monthly read-unit message means a Starter or Builder quota is exhausted and operations are blocked. An embedding-token message names a model and input type and refers to the hosted inference limit for the project. An egress message means the monthly egress allowance is gone. These have different fixes: spread the load across namespaces or move to dedicated nodes; upgrade; batch inference calls and slow the embedding rate; reduce returned payloads with include_values=False and a smaller top_k.

Mitigate first: identify the heaviest callers from your own client metrics, shed or cache them, and confirm that retries are not amplifying the storm. The SDK retries 429 with jittered backoff and honours Retry-After, so a flood of retries is itself a signal. Then raise the structural fix, and note that most limits can be raised through Support if you bring metrics. A subtle point worth making: configuring retry_config reaches the control plane and gRPC but not data-plane REST in the Python SDK, so you verify the retry behaviour on the transport you actually use.

Users say a document they just uploaded is not found. What do you check?

Eventual consistency first. Compare the write's x-pinecone-request-lsn header with the query response's x-pinecone-max-indexed-lsn; if the index has not caught up, wait, and up to about a minute is normal for full-text search on document indexes. If it has caught up, check you are querying the correct namespace and index host, that the record count in describe_index_stats for that namespace includes it, that a metadata filter is not excluding it, and that the ingestion response did not report a failed item. The senior additions: the long-term fix is a visibility helper with a deadline and an honest "still indexing" state in the product, and you say that fixed sleeps are a bug.

Retrieval quality dropped overnight and no errors were logged. What happened?

Suspect a change that produces no error: a new embedding model or preprocessing change that began writing incompatible vectors into an existing namespace, or a hosted reranker change. A real example is the deprecated cohere-rerank-3.5, whose requests since 31 August 2026 are served by cohere-rerank-4-fast; scores differ, so thresholds tuned on the old one misbehave. Check deploy history, the model and version recorded for the namespace, and compare results with a fixed evaluation set. The remedy for damaged data is not an in-place repair: stop writes, roll back the pipeline, and repoint an alias to the last good namespace or re-ingest. The lesson is that models are dependencies, so they go in a register with owners and a change calendar.

A dedicated index stopped accepting writes while reads are fine.

That is fullness reaching 1.0, the documented behaviour: writes are blocked and reads continue. Confirm with the fullness metrics, which include memory and storage variants, then add shards through a configure call and wait for the capacity state to return to Ready. Then say what should have caught it: an alert at 0.8 on pinecone_db_index_fullness, and a capacity review tied to ingestion growth. Mention that a shard holds 250 GB, which gives you the arithmetic for forecasting.

A developer deleted a production index. What now, and how do you prevent it?

If deletion protection was on, the delete returned 403, so the first prevention is that it is on by default in your provisioning. If it was not, the data is gone from that index, and recovery is restoring the latest backup into a new index, which has a new host, or re-ingesting from the source of truth. Backups contain only records at least 15 minutes old, cover serverless indexes in the same region and cloud, and do not support document-schema indexes, so say which applies. Then the restore time depends on a drill you have run, which is why you run one each quarter. Prevention also includes least-privilege roles, so ordinary developer keys cannot delete indexes at all, and audit logs, available on Enterprise, to see who did it.

A leaked API key was found in a public repository.

Treat it as compromised immediately. Create a replacement, roll it out, then delete the old one; deletion is immediate and irreversible, so confirm the replacement is serving first, unless the exposure is so serious that you accept an outage. Keys are project-scoped, so the blast radius is that project, and the role on the key bounds the damage: a query key with the viewer role cannot write, and an API key cannot hold project membership roles, so it cannot add users. Review audit logs if you have them, noting they cover control-plane events but not queries, so you cannot prove from Pinecone alone that data was not read. Afterwards, add secret scanning to the repositories and move keys into a secrets manager such as Vault.

Arguing a trade-off to leadership

Convince finance that dedicated nodes are worth it

Do not lead with performance. Lead with a number from their own data: last quarter's read-unit spend for this index, the provisioned configuration that would survive your peak with a spare replica, and the break-even traffic level. Say explicitly when dedicated is not worth it, which builds trust: for spiky traffic on-demand costs less, because an idle serverless index costs only storage. Present the risk trade as well. Dedicated removes read-rate ceilings and gives predictable latency, but introduces a capacity you must watch, so ask for the operational commitment, alerts and an owner, along with the budget. End with a review date at which you will re-run the arithmetic.

Justify managed Pinecone over a self-hosted engine

Compare total cost, not the invoice. A self-hosted engine can have a lower unit price and still cost more once you add the on-call rotation, upgrades, capacity planning and the engineer-weeks to build backup and multitenancy. Pinecone's price buys the removal of a cluster to operate. Be fair about what you accept: a managed service means someone else's limits, a release cadence you must follow, and, for residency, a fixed list of regions unless you buy BYOC. State the condition under which you would reverse the decision, such as a residency rule or volume where self-hosting wins, and put a number on it.

How do you present risk when the security team asks about Pinecone?

Walk the trust model without hedging. Data is encrypted at rest with AES-256 and in transit with TLS 1.2. Identity is project-scoped keys with roles, service accounts for administration, SSO on Standard and above. Enterprise adds private endpoints, customer-managed keys and audit logs. Then state the gaps yourself: namespace isolation is logical, so tenant separation is enforced in your service; the audit log records management events, not queries; the local emulator ignores keys and so proves nothing about authentication; and managed regions are a fixed list. Offer BYOC where residency demands it. Volunteering the gaps is what makes the rest credible.

What strong answers have in common

A strong answer cites a limit or a default that changes the design, such as 100 requests per second per namespace or the oldest-version default, instead of speaking generally. It names a metric or a header you would check. It separates the control plane from the data plane when diagnosing. It treats the index as derived data with a source of truth elsewhere. It acknowledges what changed recently and which documentation pages are stale, for example that SDK overview pages still show extras and Node versions from before the rewrite. And it ends with how the design fails.

Sixty-second self-test

Answer aloud, without notes.

1. Name the three index kinds, and what you cannot do after creation.
2. Which limit hits a hot tenant first, and which hits the index?
3. How do you prove a write is visible?
4. What happens if you omit the API version header?
5. When do dedicated nodes win, and what new incident can they cause?
6. What does a backup not cover?
7. Where is tenant isolation enforced, and why not in the client?
8. What does the audit log not record?
9. How do you switch embedding models without downtime?
10. Name two situations where you would not choose Pinecone.

If you stumble on more than two, reread the matching section of the detailed guide, then try again tomorrow.

Production traps that appear only at scale

Most of what goes wrong with Pinecone in production does not appear in a demo, because demos have one tenant, one writer and no deadline. Each trap below follows the same pattern: the symptom you would see, the cause, and the fix. They are ordered roughly by how often they cost teams real time.

Fresh writes missing from results

Symptom. A user uploads a document and immediately asks about it; the answer ignores it. Support hears that the system "forgets". Cause. A 200 on upsert means the write is durable in the request log, not that it is searchable. Pinecone is eventually consistent, and new documents can take up to about a minute to become searchable. Fix. Compare the write response's x-pinecone-request-lsn header with the query response's x-pinecone-max-indexed-lsn, wait up to a deadline, and show an honest "still indexing" state when the deadline passes. Put this in the shared client library so no team reinvents it with a sleep.

One tenant takes the index down for others

Symptom. Query errors spike for many customers while one customer's traffic climbs. Cause. Queries are limited to 100 requests per second per namespace and 2,000 read units per second per index. A big namespace burns the index budget quickly because a query costs read units in proportion to the namespace size. Fix. Find the heavy namespaces in your own client metrics. Move the biggest tenants to their own index, on Dedicated Read Nodes if the arithmetic supports it, and apply per-tenant rate limits in your service before requests reach Pinecone.

Partial failure that does not raise

Symptom. A nightly ingest reports success, yet record counts are short by a few percent. Cause. In the current Python SDK a bulk upsert returns a response with failed_item_count and errors rather than raising, and upsert_from_dataframe no longer raises on partial failure either. Fix. Assert on those fields in every pipeline, pass on_error="raise" where you want the old behaviour, and reconcile record counts against the source with describe_index_stats after a load.

The silent API version move

Symptom. Nothing changed in your code, yet behaviour differs after a quarter-end. Cause. Requests without X-Pinecone-Api-Version default to the oldest supported stable version, and when that version is retired they move to the next, which may include breaking changes. Fix. Send the header explicitly from one shared client factory, and keep a calendar of retirement dates. Support for each stable version lasts at least twelve months, so a date is always visible well ahead.

Deprecations that give no warning

Symptom. An upgrade to Python 10 passes tests, and a later release breaks. Cause. In Python 10 the deprecated dimension=, metric=, vector_type= and spec= arguments on create still work without a DeprecationWarning, as do replicas=, pod_type= and serverless_read_capacity= on configure. Fix. Add a CI check that greps for those arguments, pinecone.preview and attribute reads like .dimension, and read dimension from idx.schema.fields["embedding"].dimension instead.

Retry settings that do not reach the transport

Symptom. You configured RetryConfig(max_retries=5) and still see unretried failures on data-plane calls. Cause. That configuration reaches the control plane and gRPC but not data-plane REST. And a gRPC DEADLINE_EXCEEDED is not retried at all. Fix. Test the retry posture against the transport you really use, set explicit timeouts, and handle DEADLINE_EXCEEDED in application code.

Exceptions that slip past handlers

Symptom. An unexpected exception type escapes a try block that catches API errors. Cause. In Python 10, client-side validation raises before a request is sent, for top_k outside 1 to 10,000, IDs over 512 characters, filter={} and bad namespace names. The exceptions are PineconeValueError and PineconeTypeError, and neither is an ApiError. Fix. Catch PineconeError, and keep the legacy alias names out of new code, since they are slated for removal.

Full indexes block writes

Symptom. On a dedicated index, writes begin failing while queries keep working. Cause. When indexFullness reaches 1.0, writes are blocked and reads continue. A shard holds 250 GB. Fix. Alert on pinecone_db_index_fullness above 0.8, forecast from ingestion growth, and add shards before you need them, waiting for the capacity state to return to Ready.

The index you cannot convert

Symptom. A team asks to "just turn on full-text search" for an existing index. Cause. An index's data plane is fixed at creation. Indexes created before 2026-07 keep the Vectors API, or the Records API for integrated embedding, and only schema indexes use the Documents API. Fix. Create a new index with a reviewed schema and re-ingest, running both in parallel with an evaluation set. Remember that backups do not support document-schema indexes, so you must retain the source data.

Local tests that prove nothing

Symptom. Everything passes against Pinecone Local, then fails in staging with authentication or API-version errors. Cause. Pinecone Local ignores API keys, speaks API 2025-01 only, is in-memory, holds at most 100,000 records per index, and has no import, backups, collections, namespace management or Inference. Fix. Use it for the inner development loop on the classic vector path only, and run a contract suite against a real disposable index in CI.

Egress surprises

Symptom. A bill moves in September although query volume did not. Cause. Egress metering began on 1 September 2026, with monthly allowances of 1 GB on Starter, 10 GB on Builder and 100 GB on Standard and Enterprise. Large payloads with values and metadata count. Fix. Set include_values=False, return only the fields you use, keep top_k realistic, and watch the egress line on the usage dashboard.

Reranker changes that move your thresholds

Symptom. Relevance thresholds tuned months ago suddenly pass or reject differently. Cause. cohere-rerank-3.5 was deprecated, and since 31 August 2026 its requests are served by cohere-rerank-4-fast. Scores differ. Fix. Pin the model name explicitly in code, re-tune thresholds against a fixed evaluation set, and track models in a register alongside libraries.

Platform-ownership habits

Platform ownership is mostly habit. The following practices cost little and prevent most of the traps above.

Provision through code. Create indexes, projects, service accounts and role bindings with the Terraform provider, version 4, pinned as ~> 4.0, so every index has an owner, tags and deletion protection from birth. Keep state secure, since it can hold key material. The Terraform guide's review practices apply directly.

Make the safe path the easy path. Ship one client library that sets the API version header, resolves the index host from configuration, maps tenants to namespaces through a single function, waits for visibility, and never logs credentials. If using Pinecone correctly takes more effort than using it carelessly, teams will use it carelessly.

Give keys one job each. An ingest pipeline gets DataPlaneEditor, a query service gets DataPlaneViewer, infrastructure automation gets a control-plane role. API keys cannot hold project membership roles, which is a useful guardrail. Separate production, staging and sensitive teams into different projects, because keys are project-scoped. Plan rotation as create, roll out, verify, delete, because deletion is immediate and irreversible, and put keys in a secrets manager such as Vault.

Read the release notes like a security feed. In 2026 alone they changed per-namespace limits, the $in limit, egress billing, role names and the meaning of a reranker name. Assign someone to read them monthly and keep a change calendar of API retirements, SDK majors and model deprecations.

Rehearse recovery. Schedule backups with pc.backup_schedules.create(...), alert on pinecone_db_scheduled_backup_failure_total, and once a quarter restore into a scratch project, run the evaluation queries and record the time. A backup restores into the same region and cloud, creates a new index with a new host, and does not carry aliases, so your configuration must make repointing fast.

Treat the index as derived data. Store the raw text, chunking version, embedding model and index definition in storage you control. Because a schema is permanent and some indexes cannot be backed up, your ability to rebuild is your real disaster recovery.

Show teams their own cost. Use naming or tags that identify the owning team, and report read units, write units and storage per team. Visibility is a cheaper control than central approval. Do the dedicated-versus-on-demand arithmetic each quarter for the busiest indexes, and delete idle ones, remembering an idle serverless index costs only storage.

Keep an embedding model register. For every index record the model, dimension, input type and version. Mixing vectors from different models in one namespace gives no error and poor results, and the register tells you what to re-embed when a model changes. For Arabic or mixed-language content, build an evaluation set in those languages before choosing a model, rather than assuming an English-trained model performs.

Write a short service-level document. Promise what you can measure: client-side latency percentiles, freshness expectation from your LSN measurements, recovery time from your drill. Publish what you do not promise, such as read-your-writes, exact nearest neighbours and cross-region recovery.

Own the support path. Know your plan's support level, who may open tickets and which limits you have already asked to be raised, since most can be. Keep index names, hosts, request IDs and metrics ready, because a ticket with evidence is answered faster.

Review checklists

Pull request checklist

Use this for any change that touches Pinecone code.

• Is X-Pinecone-Api-Version explicit, and is the SDK major pinned in the lockfile?
• Is the index targeted by host rather than name?
• Does any bulk upsert ignore failed_item_count and errors?
• Are errors caught as PineconeError, and is a deadline set on every call?
• Does any code read .dimension, .metric or .spec from a described index, or pass dimension= or spec= to create?
• Does a user-facing flow depend on read-after-write, and does it use the LSN comparison rather than a sleep?
• Are include_values, include_metadata and top_k chosen deliberately, with the 4 MB response limit in mind?
• Is a namespace name ever built directly from request input? It should come from the tenant registry.
• Are metadata values within the supported types, with no nulls or nested objects, and no filter list approaching 10,000 values?
• Are credentials read from the environment or a secrets manager, and absent from logs and serialised objects?
• Is PINECONE_GRPC_SCHEME set to http or PINECONE_CONTROLLER_HOST overridden anywhere outside local testing?
• Is TLS verification intact, with a corporate certificate supplied through ssl_ca_certs where needed?

Design document checklist

Use this before approving a new use of Pinecone.

• Which index kind, and why? If a document index, who reviewed the schema, given that it cannot be changed?
• Which cloud and region, and has residency, private endpoint support and plan availability been checked before creation, given the region cannot change?
• What is the tenancy model, how are tenants provisioned and removed, and how is isolation enforced in your own service?
• Which limit binds first for this workload: 100 requests per second per namespace, 2,000 read units per second per index, or a plan quota? What is the plan when it is hit?
• What is the expected monthly cost from storage, read units, write units and egress, and what would change the answer?
• On-demand or dedicated, with the break-even stated?
• How is the index rebuilt, from what source, how long does that take, and when was a restore last rehearsed?
• Which models are involved, with versions, and how will a change to any of them be introduced without mixing vectors?
• What are the freshness expectations, and how will the product tell users when indexing is behind?
• Which keys and roles exist, which project holds them, and how are they rotated?
• Who owns alerts for 429s, latency, read-unit burn, fullness and backups, and who is on call?
• What is the exit plan, meaning what would make you leave Pinecone and how portable is the data?

Existing deployment audit

Run this quarterly.

• Every index has an owner tag, an index-kind tag and deletion protection.
• No all-permission key is used by a service that only reads.
• No pinecone-cli- managed keys remain from former machines; pc auth local-keys list and prune clean local ones.
• Every service sends an explicit API version, and the earliest retirement date among them is in a calendar.
• A backup schedule exists with failure alerting, and a restore drill ran within the quarter.
• Idle indexes and namespaces have been identified and removed.
• The change log of the release notes has been read and its items triaged.

Practice cards

Try each in a scratch project before you need it in an incident.

Card 1: measure freshness. Upsert a record, capture the LSN from the response, poll a query until the indexed LSN catches up, and record the delay ten times. Write the worst case into your service-level document.

Card 2: classify a 429. Take four real or sample 429 messages and tag each by cause: per-namespace rate, monthly read units, embedding tokens per minute, egress. Write the fix for each.

Card 3: alias cutover. Create two namespaces, ingest different content into each, point an alias at the first, query through it, repoint it to the second and verify the results changed. Practise the rollback.

Card 4: key review. List the keys in a project, write what each can and cannot do, and replace one over-broad key with a narrower role.

Card 5: restore. Back up a small index, restore it into a new index, time it and diff the query results.

Card 6: version audit. Grep a repository for the deprecated arguments, pinecone.preview and PineconeAsyncio, and list what you would change.

Operational recipes

Confirm what is running

Check the installed SDK and your CLI, and confirm the API version your code actually sends, rather than trusting what you remember.

python -c "import pinecone; print(pinecone.__version__)"
pc version
pc auth status
pc target --show
pc index list

Inspect an index and its capacity

pc index describe -i my-index
pc index stats -i my-index

On a dedicated index, check the capacity state and the fullness metrics before and after any change. Use -j for JSON output you can parse in scripts.

Create a backup and restore it

pc index backup create -i my-index --name nightly-check
pc index restore -i BACKUP_ID -n my-index-restored
pc index restore list

The restore creates a new index with a new host, so update the host in configuration and confirm with a query. In scripts remember that delete commands prompt for confirmation, and need --skip-confirmation or --json; guard any automation that adds the flag.

Start a bulk import

pc index import start -i my-index --uri s3://bucket/path/ --integration-id INTEGRATION_ID --error-mode continue
pc index import list -i my-index

Check the error count when it finishes, and remember import costs $0.25 per GB even for rows that fail.

Pin and verify versions

pinecone>=10,<11

Put that line in your requirements file, send the API version header from one factory, and in Node.js confirm the runtime is version 22 or later for SDK 9. Remember that the documentation overview pages for Python and Node still show older requirements; the package metadata and release notes are authoritative.

Scrape metrics

scrape_configs:
  - job_name: 'pinecone-serverless-metrics'
    http_sd_configs:
      - url: https://api.pinecone.io/prometheus/projects/PROJECT_ID/metrics/discovery
        refresh_interval: 1m
        authorization: {type: Bearer, credentials: API_KEY}
    authorization: {type: Bearer, credentials: API_KEY}

Store the credential as a secret and give it a role no broader than needed. Graph pinecone_db_read_unit_count, pinecone_db_op_query_duration_sum and, for dedicated indexes, the fullness gauges. See the Prometheus and Grafana guides for the surrounding setup.

Find old habits in a code base

grep -rnE "pinecone\.init|pinecone-client|PineconeAsyncio|pinecone\.preview|dimension=|spec=|PINECONE_GRPC_SCHEME" .

Each hit is either a legacy API from before version 3 or a deprecation that will not warn. Triage them into a ticket with an owner.

Closing advice

The shortest summary of operating Pinecone at scale is that its elasticity moves your risk rather than removing it. You no longer worry about nodes; you worry about limits, consistency, identity, cost and versions. Teams that do well write those worries down as code, tests, alerts and calendars, and review the release notes before the release notes review them. When in doubt, go back to four questions: which plane, which limit, which version, which identity. The answers point at the fix more often than anything else does. For the tools around the database, see LangChain, LlamaIndex, RAGAS and Langfuse.