What does a Pinecone vector record contain, and how should you batch upserts?

## What a record is Pinecone stores *records*, not rows. A record has: - **`id`** — a string you supply. Pinecone never generates one for you. Ids are the primary key: they are what `fetch`, `update` and `delete` address, and what makes a re-run of your ingestion idempotent. Practical ids are deterministic and derived from the source, e.g. `doc-4711#chunk-12`, rather than a fresh UUID per run (a fresh UUID per run duplicates your whole corpus on the second run). - **`values`** — the dense embedding, a list of floats. Its length **must equal the dimension the index was created with**. A mismatch is a hard request error, not a silent truncation, and it is the single most common first-day failure: you swapped embedding models and the new one emits a different width. - **`metadata`** — an optional flat dictionary. Values may be strings, numbers, booleans, or lists of strings. Nested objects and nulls are not stored; if a field is absent, simply omit the key. Metadata has its own per-record size ceiling (about 40 KB), which matters because people are tempted to stuff the whole source chunk text in there. Dense `values` are the normal case; an index can also carry sparse values alongside them for hybrid retrieval, which is a separate subject. ## The write call ``` index.upsert(vectors=[...], namespace="tenant-a") ``` Two accepted record spellings — a dict with `id`/`values`/`metadata`, or a positional tuple `(id, values, metadata)`. The dict form is worth preferring because it is self-describing and survives someone adding a field later. The operation is **upsert**, one word for insert-or-replace: if the id is new it is created, if it exists the stored record is replaced. There is no duplicate-key error and no second copy under the same id — a fact worth stating explicitly in an interview, because it is what lets you re-run a failed ingest job over the same input without cleaning up first. ## Why batching matters Each `upsert` call is one HTTPS round trip to a remote service. Writing 50,000 vectors one at a time means 50,000 round trips and, on serverless, 50,000 chances to hit a write rate limit. So you batch. The constraint from the other side is the **request size limit — roughly 2 MB per upsert call**. Work out what that means for your data: a 1536-dimension float embedding is a few kilobytes of JSON on its own, so a couple of hundred records with small metadata is already near the ceiling, and records carrying long text metadata get there much faster. That is why ~100 records per batch is the conventional default rather than a magic number: it comfortably fits under the size cap for typical embedding widths, keeps individual retries cheap when one call fails, and amortises the round trip well. If you get a request-too-large error, the fix is a smaller batch, not a bigger timeout. A related habit: chunk your input *before* embedding, so batch boundaries line up between your embedding calls and your upsert calls, and a failure retries a single aligned unit. ## Namespaces and the call boundary One `upsert` call writes into one namespace (the default namespace if you pass none). Records for different tenants therefore cannot share a batch — partition your work by namespace first, then batch within each partition. ## Failure modes to name - **Dimension mismatch** — rejected outright; check the index's configured dimension against your model's output width. - **Oversized request** — batch too large, or metadata too heavy; shrink the batch. - **Non-deterministic ids** — re-running ingestion silently doubles your data instead of replacing it. - **Fat metadata** — storing whole documents in metadata inflates every request and every response that includes metadata; store a reference and keep the text in your own store or a small field. - **Assuming the write is immediately queryable** — Pinecone acknowledges the write before it is visible to search, which is a separate consistency concern.