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: ""}})
Context Vars: 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)
Context Vars: 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"}
})
Context Vars: 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"}}
}, {})
Context Vars: 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")
Context Vars: 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
Context Vars: 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)
Context Vars: 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"