Create a Pinecone index by declaring its searchable fields.

The schema decides which searches the index can ever answer, and it cannot be changed afterwards - so decide up front:

• dense_fields -> semantic search. Dimension must match the embedding model you will use.

• sparse_fields -> learned lexical search (SPLADE-style).

• text_fields -> BM25 full-text search and Lucene query strings.

Recipes matching the five common setups:

1. Keyword search only, one field: text_fields=[{"name": "body"}]

2. Multi-field FTS: text_fields=[{"name": "body"}, {"name": "summary"}]

3. Dense + FTS in one index: dense_fields=[{"name": "embedding", "dimension": 1024}] plus text_fields=[{"name": "body"}]

4. Multi-signal (dense + sparse + FTS): all three lists populated.

5. Sparse + dense hybrid over the Vectors API: exactly one dense and one sparse field, no text fields.

Limits enforced before the call is sent: at most one dense_vector field and at most one sparse_vector field per index, up to 100 full-text string fields. Field names must be unique, at most 64 bytes, and must not start with _ (reserved for _id / _score) or $ (reserved for filter operators).

Only searchable fields go in the schema. Ordinary metadata is indexed for filtering automatically the first time it appears on a record; declaring it here is rejected by the API.

Args: name: 1-45 chars, lowercase alphanumerics and hyphens. pod: Pod deployment instead of managed serverless, e.g. {"environment": "us-east-1-aws", "pod_type": "p1.x1", "replicas": 1, "shards": 1}. read_capacity: {"mode": "OnDemand"} or {"mode": "Dedicated", "dedicated": {...}}. deletion_protection: "enabled" blocks deletion until switched back. tags: Up to 20 key/value pairs. cmek_id: Customer-managed encryption key id. timeout: Seconds to wait for readiness; -1 returns immediately.

Create an index with a hosted embedding model attached.

Pinecone embeds text_field on write and embeds queries on read, so no embedding provider is needed on this side. Read it back with pinecone_search_records. The model cannot be changed later.

Args: model: Hosted model, e.g. "llama-text-embed-v2", "multilingual-e5-large", "pinecone-sparse-english-v0". text_field: Record field holding the raw text to embed. filterable_fields: e.g. {"genre": {"filterable": true}}.

List every index in the project, with the search modes each supports.

Full server-side description of one index: schema, deployment, status, host.

Report which searches an index can answer, and with which fields.

Call this before searching an index you did not create in this session. It names the dense / sparse / full-text fields, the dimension each dense field expects, and the list of valid mode values for pinecone_search.

Change an index's deletion protection, tags or read capacity.

The field schema is immutable - a new signal (a sparse field, an FTS field) means creating a new index and reindexing.

Delete an index and everything in it. Requires confirm=true.

List the namespaces in an index, with record counts where available.

Describe one namespace: record count and metadata.

Create an empty namespace. Upserting to a new namespace also creates it.

Delete a namespace and every record in it. Requires confirm=true.

Sample records from a namespace and describe the metadata shape.

Returns each field observed, its types, how many of the sampled records carried it, and up to three example values - enough to write a correct filter without dumping the namespace into the conversation.

Record counts, dimension and per-namespace breakdown for an index.

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.

Upsert through the legacy Vectors API - raw values plus metadata.

Use this for single-vector indexes where you want a dense and a sparse vector on the same record, which is what makes the one-request hybrid query in pinecone_query_vectors possible.

Args: vectors: [{"id": "v1", "values": [...], "sparse_values": {"indices": [...], "values": [...]}, "metadata": {"category": "tech"}}]. ttl_seconds: Stamps _expires_at into each record's metadata.

Partially update documents - by id, or by filter across many at once.

Args: documents: Per-record updates, each with _id and the fields to change. filter: Update every document matching this filter instead. set_fields: Fields to set on all matched documents. remove_fields: Field names to strip.

Update one record's vector values or metadata via the Vectors API.

Delete records by id, by metadata filter, or clear a namespace.

delete_all=true requires confirm=true.

Permanently delete records whose TTL has lapsed. Requires confirm=true.

Searches already hide expired records; this is what actually frees the storage. Run it on a schedule if you rely on TTL.

Fetch records by id or filter, without ranking them.

include_fields=["*"] returns every field; omitting it returns all available fields for a document fetch.

List record ids in a namespace, optionally filtered by id prefix.

Search an index, validating the request against its schema first.

Modes, and what each needs from the schema:

• text - BM25. A text clause names exactly one field, so scoring across several fields sends one clause per field in a single request and Pinecone combines them with equal weight (there is no per-clause weight). Pass fields to choose them, or omit it to use every FTS field. field_queries gives each field its own query text, e.g. {"body": "disappointing", "summary": "Disappointing"}.

• query_string - Lucene syntax, which targets fields inside the query itself: title:(quantum) OR body:(machine AND learning). Supports AND/OR/NOT, +/-, grouping, phrases "...", phrase slop "..."~2, boosting term^2, phrase prefix "mach lear"* and regex body:/mach.*/. Fuzzy matching (~1 on a single term) is not supported.

• dense - semantic search. query is embedded with the configured provider unless you pass vector yourself.

• sparse - learned lexical search over a sparse vector field.

• hybrid - every signal the index has, run separately and fused client-side. A dense or sparse clause must be the only clause in its request, so this is one request per signal merged with Reciprocal Rank Fusion (fusion="weighted" plus weights={"dense": 2, "text": 1} to bias one signal).

• auto - the richest mode the index supports.

filter narrows candidates before ranking and is deterministic, not a scoring signal. Metadata operators: $eq $ne $gt $gte $lt $lte $in $nin $exists $and $or $not. On FTS-enabled string fields you also get $match_phrase, $match_all and $match_any (at most 128 tokens each) - which is how you rank by vector while requiring an exact term.

include_fields defaults to every stored field. Pass a narrower list to keep responses small, or [] for ids and scores only. top_k may be 1-10000.

Records whose TTL has lapsed are excluded by default; records written without a TTL are never hidden.

Search an integrated-inference index - Pinecone embeds the query.

Only for indexes created with pinecone_create_index_for_model. Optional server-side reranking: pass rerank_model (e.g. "bge-reranker-v2-m3") and rerank_fields.

match_terms constrains sparse retrieval to records containing specific terms, e.g. {"strategy": "all", "terms": ["refund"]} (sparse indexes on pinecone-sparse-english-v0 only).

Vectors API query - the true single-request dense+sparse hybrid.

On a single-vector index holding both a dense and a sparse vector per record, passing both here has Pinecone do the hybrid scoring server side, rather than the client-side fusion pinecone_search uses for schema indexes.

Pass query instead of vectors to have them embedded here first, or id to search by an existing record.

Rerank a candidate list with a hosted cross-encoder.

Use it as a second stage: retrieve widely with pinecone_search (top_k 50-100), then rerank down to the handful you actually want.

Args: documents: [{"id": "d1", "text": "..."}]. rank_fields: Which field the reranker reads, default ["text"].

Generate embeddings without storing them - useful for dimension checks.

List the hosted embedding and reranking models Pinecone offers.

Report configuration: backends, default embedding provider, read-only mode.