pinecone_upsert_documents
Insert or update documents in a Pinecone index, embedding text on the way in and validating each record so your upsert never fails as a whole.
Instructions
Upsert records, optionally embedding them on the way in.
Each document needs a unique _id. Fields declared in the index
schema are searched; every other field is stored and indexed for
filtering automatically.
Embedding is plug-and-play. Pass embed_source_field naming the text
field to embed and the toolbox fills every dense and sparse field the
schema declares, using embed_provider/embed_model (defaults come
from VTB_EMBED_PROVIDER / VTB_EMBED_MODEL). A document that already
carries a vector for a field is left alone, so you can mix pre-computed
and generated vectors in one call. The vector width is checked against
the schema before anything is sent.
Validated before sending, because Pinecone fails an entire upsert if
any one document is invalid: each document needs a unique _id and
at least one schema field (a metadata-only document is rejected), and
no field name may start with _ or $. Requests are split at
1000 documents.
TTL is implemented by this server, not by Pinecone: ttl_seconds
stamps a vtb_expires_at epoch on each record, searches exclude
lapsed records by default, and pinecone_purge_expired reclaims the
storage. Records written without a TTL carry no extra field and are
never hidden by that filter.
Args:
documents: e.g. [{"_id": "d1", "body": "...", "category": "tech", "year": 2026}].
embed_source_field: Field whose text becomes the vector(s).
dense_field / sparse_field: Target schema fields when the index
declares more than one.
ttl_seconds: Lifetime in seconds. Omit for no expiry.
batch_size: Documents per request when batching.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | ||
| documents | Yes | ||
| namespace | Yes | ||
| batch_size | No | ||
| dense_field | No | ||
| embed_model | No | ||
| ttl_seconds | No | ||
| sparse_field | No | ||
| sparse_model | No | ||
| embed_provider | No | ||
| embed_dimension | No | ||
| sparse_provider | No | ||
| embed_source_field | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||