Control-plane index management on api.pinecone.io: list, describe,
create (vector, schema-based, or integrated-embedding), configure,
delete, and check whether a new index is ready (is-ready).
On API version 2026-07 POST /indexes is schema-based:
create-index sends the reserved _values dense-vector field,
which creates a classic vector index served by
::pinecone::vectors. describe-index returns the dimension and
metric under schema.fields._values.
Functions
build-configure-body
fn (options: Map): Map
The PATCH /indexes/{name} body from the set options among
deletion_protection, tags, read_capacity, deployment (pod
replicas/pod_type), and schema. Exposed for testing.
Example
::pinecone::indexes/build-configure-body({deletion_protection: "disabled", tags: null}) // {deletion_protection: "disabled"}
build-create-for-model-body
fn (name: Str, model: Str, options: Map): Map
The POST /indexes/create-for-model body: embed holds model,
field_map (default {text: "text"}), and optional metric,
dimension, read_parameters, write_parameters. Exposed for testing.
Example
::pinecone::indexes/build-create-for-model-body("notes", "llama-text-embed-v2", {}).embed // {model: "llama-text-embed-v2", field_map: {text: "text"}}
build-create-index-body
fn (name: Str, dimension: Int, options: Map): Map
The POST /indexes body for a classic dense vector index: a schema with
only the reserved _values field, plus deployment and any set
deletion_protection, tags, read_capacity. Exposed for testing.
Example
::pinecone::indexes/build-create-index-body("docs", 3, {metric: "dotproduct"}).schema // {fields: {_values: {type: "dense_vector", dimension: 3, metric: "dotproduct"}}}
build-deployment
fn (options: Map): Map
The deployment for a managed (serverless) index from cloud (default
"aws") and region (default "us-east-1") options. Exposed for testing.
Example
::pinecone::indexes/build-deployment({region: "eu-west-1"}) // {deployment_type: "managed", cloud: "aws", region: "eu-west-1"}
build-schema-index-body
fn (name: Str, schema: Map, options: Map): Map
The POST /indexes body for an index with an explicit schema. Exposed
for testing.
Example
schema {fields: {_sparse_values: {type: "sparse_vector"}}}
::pinecone::indexes/build-schema-index-body("keywords", schema, {tags: {team: "search"}}).tags // {team: "search"}
configure-index
fn (name: Str, options: Map): Map
fn (name: Str, options: Map, opts: Map): Map
PATCH /indexes/{name} - Change an index: deletion_protection
("enabled"/"disabled"), tags (merged; set a key to "" to remove
it), read_capacity, pod deployment. Returns the updated
description.
Example
::pinecone::indexes/configure-index("docs", {deletion_protection: "disabled", tags: {team: ""}})
pinecone.api.key
create-index
fn (name: Str, dimension: Int): Map
fn (name: Str, dimension: Int, options: Map): Map
fn (name: Str, dimension: Int, options: Map, opts: Map): Map
POST /indexes - Create a serverless dense vector index. options:
metric ("cosine" default, "euclidean", "dotproduct"), cloud
("aws" default, "gcp", "azure"), region (default "us-east-1"),
deletion_protection ("enabled"/"disabled"), tags (Map of
strings), read_capacity. Returns the index description. A new index is
not ready for data for a few seconds: from a later step or a
schedule, call describe-index until is-ready before upserting.
Example
::pinecone::indexes/create-index("docs", 1536, {
metric: "cosine",
deletion_protection: "enabled",
tags: {team: "search"}
})
// in a later step:
index ::pinecone::indexes/describe-index("docs")
if(::pinecone::indexes/is-ready(index), index.host, null)
pinecone.api.key
create-index-for-model
fn (name: Str, model: Str): Map
fn (name: Str, model: Str, options: Map): Map
fn (name: Str, model: Str, options: Map, opts: Map): Map
POST /indexes/create-for-model - Create an index with integrated
embedding: Pinecone embeds the text field named by field_map with
a hosted model (e.g. "llama-text-embed-v2",
"multilingual-e5-large", "pinecone-sparse-english-v0") on upsert and
search. Read and write it with ::pinecone::records. options:
field_map (default {text: "text"}), cloud, region, metric,
dimension, deletion_protection, tags. Pinecone calls this a
legacy integrated index; it keeps working on 2026-07.
Example
::pinecone::indexes/create-index-for-model("notes", "llama-text-embed-v2", {
field_map: {text: "chunk_text"}
})
pinecone.api.key
create-index-from-schema
fn (name: Str, schema: Map, options: Map): Map
fn (name: Str, schema: Map, options: Map, opts: Map): Map
POST /indexes - Create an index from an explicit schema. A schema
of only _values (dense) and/or _sparse_values (sparse) makes a
vector index (::pinecone::vectors); any other fields make a
document index, read and written through the Documents API (use
::pinecone::api/json for those endpoints). options as for
create-index.
Example
// A sparse vector index
::pinecone::indexes/create-index-from-schema("keywords", {
fields: {_sparse_values: {type: "sparse_vector"}}
}, {})
pinecone.api.key
delete-index
fn (name: Str): Any
fn (name: Str, opts: Map): Any
DELETE /indexes/{name} - Delete an index and all its data. Fails while
deletion_protection is "enabled"; disable it with configure-index
first.
Example
::pinecone::indexes/delete-index("docs")
pinecone.api.key
describe-index
fn (name: Str): Map
fn (name: Str, opts: Map): Map
GET /indexes/{name} - One index: host (what the data-plane functions
take), status: {ready, state}, deployment, schema,
deletion_protection, tags.
Example
index ::pinecone::indexes/describe-index("docs")
index.host
pinecone.api.key
is-ready
fn (index: Map): Bool
True when an index description (from describe-index,
create-index, or list-indexes) reports status.ready, so its
host accepts data. Use ready-check to also spot a failed index.
Example
// From a later step or a schedule, before the first upsert
index ::pinecone::indexes/describe-index("docs")
cond {
::pinecone::indexes/is-ready(index) => {
::pinecone::vectors/upsert(index.host, [{id: "doc-1", values: [0.1, 0.2, 0.3]}])
}
=> { null }
}
list-indexes
fn (): Map
fn (opts: Map): Map
GET /indexes - Your indexes: {indexes: [{name, host, status, deployment, schema, deletion_protection, tags?}]}.
Example
out ::pinecone::indexes/list-indexes()
map(out.indexes, %.name)
pinecone.api.key
ready-check
fn (index: Map): Str
Classify an index description: "ready" (status.ready is true),
"failed" (state InitializationFailed or Failed), or "pending".
Exposed for testing.
Example
::pinecone::indexes/ready-check({status: {ready: true, state: "Ready"}}) // "ready"
::pinecone::indexes/ready-check({status: {ready: false, state: "Failed"}}) // "failed"
::pinecone::indexes/ready-check({status: {ready: false, state: "Initializing"}}) // "pending"