What is a Pinecone namespace, and how does it change query behaviour?

## The partition model A Pinecone index has one vector dimension and one distance metric, and inside it records are grouped into **namespaces**. A namespace is just a string label attached to records. Two records in different namespaces are completely independent for search purposes even though they live in the same index and share its configuration. The API surface is deliberately small: `namespace` is an optional argument on the data-plane calls. `index.upsert(vectors=[...], namespace="tenant-a")` writes into that partition. `index.query(vector=..., top_k=5, namespace="tenant-a")` searches it. `fetch`, `update` and `delete` take the same argument. If you omit it, the operation targets the **default namespace**, which is literally the empty string `""` — this is why `describe_index_stats()` on a naively populated index shows a namespace whose key is an empty string. ## Implicit lifecycle There is no create-namespace step in the index creation call. A namespace begins to exist the moment the first record is upserted with that name, and it ceases to exist when its last record is removed. That makes namespaces extremely cheap to mint compared with indexes: adding a tenant is a write, not a control-plane operation with provisioning latency. The same property makes typos dangerous. Upserting to `"tenat-a"` does not fail — it quietly creates a new namespace containing exactly those records, and the subsequent query against `"tenant-a"` returns nothing at all rather than an error. Empty results from a correct-looking query are the classic namespace bug, and the first diagnostic is always to print `describe_index_stats()` and look at the namespace keys and their vector counts. ## Query scoping is the whole point The behavioural rule that matters is: **one query, one namespace**. Pinecone does not offer a cross-namespace search or a wildcard. That has three consequences worth stating in an interview. First, isolation is structural rather than filter-based. A tenant's query physically cannot reach another tenant's vectors, because the other vectors are not in the searched partition. There is no filter to get wrong and no risk that a mis-specified condition leaks a neighbour's document — an attractive property when tenants are separate customers. Second, `top_k` is per namespace. If tenant A's namespace holds ten records and you ask for `top_k=20`, you get ten. Nothing is borrowed from elsewhere in the index to fill the gap. Conversely, a large noisy namespace can no longer crowd out a small one, because they are never scored against each other. Third, fan-out is your problem. A feature that must search fifty tenants at once needs fifty `query` calls issued concurrently plus a client-side merge of the scored results — and merging is only meaningful because all namespaces in an index share the same metric, so the scores are comparable. If cross-group search is the common case rather than the exception, namespaces are the wrong tool and a metadata attribute on the records is a better model. ## Namespaces versus metadata Both partition data, but they behave differently. A metadata attribute keeps all records in one searchable pool and narrows the candidate set at query time; that keeps cross-group search to one call, at the cost of the search touching a shared structure and of correctness depending on every query supplying the right condition. A namespace removes the records from each other's search space entirely and makes bulk removal trivial — deleting everything in a namespace is a single call, `index.delete(delete_all=True, namespace="tenant-a")`, whereas deleting by attribute across a large shared pool is a heavier operation. The two are also composable: it is normal to use a namespace for the hard tenant boundary and metadata for softer within-tenant slices such as document type or date. ## Operational habits Derive the namespace string from a stable identifier — an internal tenant id rather than a display name that can change — and centralise it in one function so no call site can forget it or spell it differently. Treat "query returned zero results" as a namespace question before it is a relevance question. And remember that writes are visible only in the namespace they were written to, so a smoke test that upserts into the default namespace and queries a named one will look broken for reasons that have nothing to do with embeddings. ## What good answers include Strong candidates state that the namespace is a hard query boundary, that it is created implicitly, that the default is the empty string, and that cross-namespace search requires application-level fan-out. Weaker answers describe namespaces as "like a folder" without knowing that a query cannot span them, which is exactly the fact every design decision hangs on.