Pinecone

Read and write the Pinecone vector database: create indexes, embed text, upsert and search vectors, and rerank the results.

Actions

Action	What it does
Configure index	Change an existing index's deletion protection or its tags.
Create index	Create a serverless index for vectors you supply yourself - the kind 'Upsert vectors' and 'Search with a vector' work with.
Create index with an embedding model	Create a serverless index that turns text into vectors for you.
Delete index	Delete an index and every vector in it.
Delete namespace	Delete a namespace and every record in it.
Delete vectors	Delete vectors by id, or empty a whole namespace.
Describe index	Read one index's configuration: its dimension, distance metric, cloud and region, tags, deletion protection, and the host it is served from.
Fetch vectors	Read vectors back by id, with their numbers and metadata.
Generate embeddings	Turn text into vectors with one of Pinecone's hosted models, without an index.
Get index statistics	Count what an index holds: the total number of vectors, and the number in each namespace, plus the dimension and metric the index was built with.
List indexes	List every index in the Pinecone project, with each one's dimension, distance metric, region and readiness.
List models	List the embedding and reranking models Pinecone hosts, with each one's dimensions, supported metrics, input limits and parameters.
List namespaces	List every namespace in an index, with how many records each one holds and how much space it uses.
List record IDs	List the ids stored in one namespace, in sorted order, optionally narrowed to those starting with a prefix.
Rerank documents	Re-order a list of documents by how well they answer a question, using a hosted reranking model.
Search records	Search a namespace with a question in plain text, and optionally rerank the results in the same call.
Search with a vector	Find the vectors nearest to one you supply, or nearest to a vector already in the index.
Update vector	Change one stored vector's numbers, its metadata, or both, without rewriting the rest of it.
Upsert text records	Write text straight into an index built with 'Create index with an embedding model' - Pinecone embeds it for you, so nothing has to produce a vector first.
Upsert vectors	Write vectors into a namespace.

Change an existing index's deletion protection or its tags. An index's dimension, metric, cloud and region are fixed when it is created and are not offered here. Turn deletion protection off with this before 'Delete index' will run.

Inputs

IndexindextextRequired: Which index to work with. Pick from the list, or paste the index's host from the Pinecone console - a value ending in '.pinecone.io' is used as the host directly.
Deletion protectiondeletion_protectiontext: Whether Pinecone should refuse to delete this index. Leave the field untouched to keep the current setting.One of: disabled (Off - the index can be deleted), enabled (On - deleting the index is refused until this is turned off).
Tagstagsobject: Custom labels on the index, such as {"env": "staging"}. Set a key to "" to remove it. Leave the field untouched to keep the current tags.

Outputs

deletion_protectiontext: enabled or disabled, after the change
dimensionnumber: How many numbers each vector holds
hosttext: The host its vectors are served from
indexobject: The index as Pinecone reports it
metrictext: cosine, dotproduct or euclidean
nametext: The index's name
readytrue/false: Whether it can be read and written
statetext: The index's state
tagsobject: Custom labels, after the change

Example output

{
  "deletion_protection": "disabled",
  "dimension": 1024,
  "host": "product-search-4a1b2c3.svc.aped-4627-b74a.pinecone.io",
  "index": {
    "deletion_protection": "disabled",
    "deployment": {
      "cloud": "aws",
      "deployment_type": "managed",
      "environment": "aped-4627-b74a",
      "region": "us-east-1"
    },
    "host": "product-search-4a1b2c3.svc.aped-4627-b74a.pinecone.io",
    "name": "product-search",
    "schema": {
      "fields": {
        "_sparse_values": {
          "type": "sparse_vector"
        },
        "_values": {
          "dimension": 1024,
          "metric": "cosine",
          "type": "dense_vector"
        }
      }
    },
    "status": {
      "ready": true,
      "state": "Ready"
    },
    "tags": {
      "env": "production"
    }
  },
  "metric": "cosine",
  "name": "product-search",
  "ready": true,
  "state": "Ready",
  "tags": {
    "env": "production"
  }
}

Create index

Create a serverless index for vectors you supply yourself - the kind 'Upsert vectors' and 'Search with a vector' work with. Give it the width of the vectors you will store and how similarity should be measured; neither can be changed afterwards. The index takes a moment to become ready.

Inputs

Index namenametextRequired: A name for the new index: 1-45 characters, lower-case letters, digits and '-', starting and ending with a letter or digit. It must be unique in the project.
DimensiondimensionnumberRequired: How many numbers each vector holds, 1-20000. This must match whatever produces your vectors - llama-text-embed-v2 and multilingual-e5-large both produce 1024.From 1 to 20000. Default: 1024.
Distance metricmetrictext: How similarity between two vectors is measured. This cannot be changed after the index is created.One of: cosine (Cosine - the usual choice for text embeddings), dotproduct (Dot product - required for hybrid dense + sparse search), euclidean (Euclidean - straight-line distance). Default: cosine.
Cloudcloudtext: Which public cloud hosts the index. A free Starter project can only use aws; the others need a paid plan.One of: aws (AWS - the only cloud a free Starter project can use), gcp (Google Cloud), azure. Default: aws.
Regionregiontext: Which region hosts the index, such as 'us-east-1'. A free Starter project can only use us-east-1.Default: us-east-1.
Deletion protectiondeletion_protectiontext: Whether Pinecone should refuse to delete this index. Turning it on means 'Delete index' fails until it is turned off again.One of: disabled (Off - the index can be deleted), enabled (On - deleting the index is refused until this is turned off). Default: disabled.
Tagstagsobject: Custom labels on the index, at most 20, such as {"env": "staging"}. Keys are 80 characters or fewer and values 120.

Outputs

deletion_protectiontext: enabled or disabled
dimensionnumber: How many numbers each vector holds
hosttext: The host its vectors are served from
indexobject: The index as Pinecone reports it
metrictext: cosine, dotproduct or euclidean
nametext: The index's name
readytrue/false: Whether it can be written to yet
statetext: Usually 'Initializing' right after creation
tagsobject: Custom labels on the index

Example output

{
  "deletion_protection": "disabled",
  "dimension": 1024,
  "host": "product-search-4a1b2c3.svc.aped-4627-b74a.pinecone.io",
  "index": {
    "deletion_protection": "disabled",
    "deployment": {
      "cloud": "aws",
      "deployment_type": "managed",
      "environment": "aped-4627-b74a",
      "region": "us-east-1"
    },
    "host": "product-search-4a1b2c3.svc.aped-4627-b74a.pinecone.io",
    "name": "product-search",
    "schema": {
      "fields": {
        "_sparse_values": {
          "type": "sparse_vector"
        },
        "_values": {
          "dimension": 1024,
          "metric": "cosine",
          "type": "dense_vector"
        }
      }
    },
    "status": {
      "ready": true,
      "state": "Ready"
    },
    "tags": {
      "env": "production"
    }
  },
  "metric": "cosine",
  "name": "product-search",
  "ready": true,
  "state": "Ready",
  "tags": {
    "env": "production"
  }
}

Create index with an embedding model

Create a serverless index that turns text into vectors for you. Nothing has to compute an embedding before writing or before searching: 'Upsert text records' sends the text and 'Search records' sends the question. Choose which field of your records holds the text - the default is 'chunk_text'.

Inputs

Index namenametextRequired: A name for the new index: 1-45 characters, lower-case letters, digits and '-', starting and ending with a letter or digit. It must be unique in the project.
Embedding modelmodeltextRequired: Which of Pinecone's hosted models embeds the text. This cannot be changed after the index is created.
Text fieldtext_fieldtext: Which field of each record holds the text to embed. Every record written to this index must carry it. Defaults to 'chunk_text'.Default: chunk_text.
Distance metricmetrictext: How similarity is measured. Leave empty to use the metric the chosen model is trained for, which is usually the right answer.One of: cosine (Cosine - the usual choice for text embeddings), dotproduct (Dot product - required for hybrid dense + sparse search), euclidean (Euclidean - straight-line distance).
Cloudcloudtext: Which public cloud hosts the index. A free Starter project can only use aws; the others need a paid plan.One of: aws (AWS - the only cloud a free Starter project can use), gcp (Google Cloud), azure. Default: aws.
Regionregiontext: Which region hosts the index, such as 'us-east-1'. A free Starter project can only use us-east-1.Default: us-east-1.
Deletion protectiondeletion_protectiontext: Whether Pinecone should refuse to delete this index. Turning it on means 'Delete index' fails until it is turned off again.One of: disabled (Off - the index can be deleted), enabled (On - deleting the index is refused until this is turned off). Default: disabled.
Tagstagsobject: Custom labels on the index, at most 20, such as {"env": "staging"}. Keys are 80 characters or fewer and values 120.

Outputs

deletion_protectiontext: enabled or disabled
dimensionnumber: The width of the vectors the model produces
hosttext: The host its records are served from
indexobject: The index as Pinecone reports it
metrictext: cosine, dotproduct or euclidean
modeltext: The embedding model it was built with
nametext: The index's name
readytrue/false: Whether it can be written to yet
statetext: Usually 'Initializing' right after creation
tagsobject: Custom labels on the index
text_fieldtext: The record field this index embeds

Example output

{
  "deletion_protection": "disabled",
  "dimension": 1024,
  "host": "product-search-4a1b2c3.svc.aped-4627-b74a.pinecone.io",
  "index": {
    "deletion_protection": "disabled",
    "deployment": {
      "cloud": "aws",
      "deployment_type": "managed",
      "environment": "aped-4627-b74a",
      "region": "us-east-1"
    },
    "host": "product-search-4a1b2c3.svc.aped-4627-b74a.pinecone.io",
    "name": "product-search",
    "schema": {
      "fields": {
        "_sparse_values": {
          "type": "sparse_vector"
        },
        "_values": {
          "dimension": 1024,
          "metric": "cosine",
          "type": "dense_vector"
        }
      }
    },
    "status": {
      "ready": true,
      "state": "Ready"
    },
    "tags": {
      "env": "production"
    }
  },
  "metric": "cosine",
  "model": "llama-text-embed-v2",
  "name": "product-search",
  "ready": true,
  "state": "Ready",
  "tags": {
    "env": "production"
  },
  "text_field": "chunk_text"
}

Delete index

Delete an index and every vector in it. This cannot be undone. If deletion protection is on, run 'Configure index' first to turn it off. Deletion is asynchronous - the index leaves 'List indexes' a moment later.

Inputs

IndexindextextRequired: Which index to work with. Pick from the list, or paste the index's host from the Pinecone console - a value ending in '.pinecone.io' is used as the host directly.

Outputs

deletedtrue/false: True once Pinecone has accepted the deletion
indextext: The index that was deleted

Example output

{
  "deleted": true,
  "index": "product-search"
}

Delete namespace

Delete a namespace and every record in it. This cannot be undone. Use it to clear out a whole partition of an index without deleting the index itself.

Inputs

IndexindextextRequired: Which index to work with. Pick from the list, or paste the index's host from the Pinecone console - a value ending in '.pinecone.io' is used as the host directly.
NamespacenamespacetextRequired: Which namespace inside the index to work in. This endpoint names the namespace in its address, so it cannot be left out; use '__default__' for the default one.

Outputs

deletedtrue/false: True once Pinecone has deleted it
indextext: The index it was in
namespacetext: The namespace that was deleted

Example output

{
  "deleted": true,
  "index": "product-search",
  "namespace": "staging"
}

Delete vectors

Delete vectors by id, or empty a whole namespace. This cannot be undone. Pinecone can also delete by metadata filter, but only on pod-based indexes, so that is not offered here - search for what you want first and delete the ids it returns.

Inputs

IndexindextextRequired: Which index to work with. Pick from the list, or paste the index's host from the Pinecone console - a value ending in '.pinecone.io' is used as the host directly.
Vector IDsidslist: Which vectors to delete, at most 1000 at a time. Leave empty only when emptying the whole namespace below.
Delete everything in the namespacedelete_alltrue/false: Delete every vector in the namespace instead of named ids. Off by default, and refused if ids are also given.Default: false.
Namespacenamespacetext: Which namespace inside the index to work in. Namespaces partition an index - a search only ever sees one. Leave empty for the default namespace, which is also called '__default__'.

Outputs

deletedtrue/false: True once Pinecone has deleted them
deleted_alltrue/false: Whether the whole namespace was emptied
idslist: The ids that were named, if any
indextext: The index they were deleted from
namespacetext: The namespace they were deleted from

Example output

{
  "deleted": true,
  "deleted_all": false,
  "ids": [
    "sku-4181"
  ],
  "index": "product-search",
  "namespace": "catalogue"
}

Describe index

Read one index's configuration: its dimension, distance metric, cloud and region, tags, deletion protection, and the host it is served from. 'ready' says whether it can be written to yet - a freshly created index takes a moment.

Inputs

IndexindextextRequired: Which index to work with. Pick from the list, or paste the index's host from the Pinecone console - a value ending in '.pinecone.io' is used as the host directly.

Outputs

deletion_protectiontext: enabled or disabled
dimensionnumber: How many numbers each vector holds
hosttext: The host its vectors are served from
indexobject: The index as Pinecone reports it
metrictext: cosine, dotproduct or euclidean
nametext: The index's name
readytrue/false: Whether it can be read and written yet
statetext: Initializing, Ready, Terminating, ...
tagsobject: Custom labels on the index

Example output

{
  "deletion_protection": "disabled",
  "dimension": 1024,
  "host": "product-search-4a1b2c3.svc.aped-4627-b74a.pinecone.io",
  "index": {
    "deletion_protection": "disabled",
    "deployment": {
      "cloud": "aws",
      "deployment_type": "managed",
      "environment": "aped-4627-b74a",
      "region": "us-east-1"
    },
    "host": "product-search-4a1b2c3.svc.aped-4627-b74a.pinecone.io",
    "name": "product-search",
    "schema": {
      "fields": {
        "_sparse_values": {
          "type": "sparse_vector"
        },
        "_values": {
          "dimension": 1024,
          "metric": "cosine",
          "type": "dense_vector"
        }
      }
    },
    "status": {
      "ready": true,
      "state": "Ready"
    },
    "tags": {
      "env": "production"
    }
  },
  "metric": "cosine",
  "name": "product-search",
  "ready": true,
  "state": "Ready",
  "tags": {
    "env": "production"
  }
}

Fetch vectors

Read vectors back by id, with their numbers and metadata. Ids the index does not have are reported in 'missing_ids' rather than failing the step, so a typo is visible instead of looking like an empty index.

Inputs

IndexindextextRequired: Which index to work with. Pick from the list, or paste the index's host from the Pinecone console - a value ending in '.pinecone.io' is used as the host directly.
Vector IDsidslistRequired: Which vectors to read, at most 1000 at a time. 'List record IDs' returns these.
Namespacenamespacetext: Which namespace inside the index to work in. Namespaces partition an index - a search only ever sees one. Leave empty for the default namespace, which is also called '__default__'.

Outputs

countnumber: How many vectors came back
idslist: The ids that were found
missing_idslist: The ids that were asked for and are not there
namespacetext: The namespace they were read from
usageobject: Read units this call consumed
vectorsobject: Each id mapped to the vector stored under it

Example output

{
  "count": 1,
  "ids": [
    "sku-4181"
  ],
  "missing_ids": [],
  "namespace": "catalogue",
  "usage": {
    "readUnits": 1
  },
  "vectors": {
    "sku-4181": {
      "id": "sku-4181",
      "metadata": {
        "category": "cookware",
        "title": "Cast iron skillet"
      },
      "values": [
        0.12,
        -0.04,
        0.88,
        0.31
      ]
    }
  }
}

Generate embeddings

Turn text into vectors with one of Pinecone's hosted models, without an index. 'embeddings' comes back as the plain arrays 'Upsert vectors' and 'Search with a vector' take, so this chains straight into either.

Inputs

ModelmodeltextRequired: Which hosted embedding model to run.
TextinputslistRequired: The pieces of text to embed, one vector per piece. A list of strings from an earlier step works as it is.
What the text is forinput_typetext: Pinecone's text models embed a stored passage differently from a search query. Choosing the wrong one costs accuracy rather than failing, so it is worth setting: 'Passage' when storing, 'Query' when searching.One of: passage (Passage - text being stored in an index), query (Query - text being searched with).
If the text is too longtruncatetext: What the model should do with input longer than it can read. Leave empty for the model's own default.One of: END (Cut the end off and embed the rest), NONE (Refuse the request instead).
Extra model parametersparametersobject: Any further model-specific parameters, such as {"dimension": 512}. Run "List models" to see what a model accepts. The fields above win over the same keys given here.

Outputs

countnumber: How many embeddings came back
datalist: The embeddings as Pinecone reports them
embeddingslist: One vector per input, ready to upsert or search with
modeltext: The model that produced them
usageobject: Tokens this call consumed
vector_typetext: dense or sparse

Example output

{
  "count": 1,
  "data": [
    {
      "values": [
        0.12,
        -0.04,
        0.88,
        0.31
      ],
      "vector_type": "dense"
    }
  ],
  "embeddings": [
    [
      0.12,
      -0.04,
      0.88,
      0.31
    ]
  ],
  "model": "llama-text-embed-v2",
  "usage": {
    "total_tokens": 12
  },
  "vector_type": "dense"
}

Get index statistics

Count what an index holds: the total number of vectors, and the number in each namespace, plus the dimension and metric the index was built with. The quickest way to confirm an upsert landed.

Inputs

IndexindextextRequired: Which index to work with. Pick from the list, or paste the index's host from the Pinecone console - a value ending in '.pinecone.io' is used as the host directly.

Outputs

dimensionnumber: How many numbers each vector holds
index_fullnessnumber: Always 0 on a serverless index, which scales itself
metrictext: How similarity is measured
namespace_nameslist: Just the namespace names, for chaining
namespacesobject: Each namespace's name mapped to its vector count
total_vector_countnumber: Vectors across every namespace
vector_typetext: dense or sparse

Example output

{
  "dimension": 1024,
  "index_fullness": 0,
  "metric": "cosine",
  "namespace_names": [
    "",
    "staging"
  ],
  "namespaces": {
    "": {
      "vectorCount": 1240
    },
    "staging": {
      "vectorCount": 18
    }
  },
  "total_vector_count": 1258,
  "vector_type": "dense"
}

List indexes

List every index in the Pinecone project, with each one's dimension, distance metric, region and readiness. Returns the names, which is the value every other action's 'Index' field takes.

Inputs

None.

Outputs

countnumber: How many there are
indexeslist: Every index in the project
nameslist: Just the index names, for chaining

Example output

{
  "count": 1,
  "indexes": [
    {
      "deletion_protection": "disabled",
      "deployment": {
        "cloud": "aws",
        "deployment_type": "managed",
        "environment": "aped-4627-b74a",
        "region": "us-east-1"
      },
      "host": "product-search-4a1b2c3.svc.aped-4627-b74a.pinecone.io",
      "name": "product-search",
      "schema": {
        "fields": {
          "_sparse_values": {
            "type": "sparse_vector"
          },
          "_values": {
            "dimension": 1024,
            "metric": "cosine",
            "type": "dense_vector"
          }
        }
      },
      "status": {
        "ready": true,
        "state": "Ready"
      },
      "tags": {
        "env": "production"
      }
    }
  ],
  "names": [
    "product-search"
  ]
}

List models

List the embedding and reranking models Pinecone hosts, with each one's dimensions, supported metrics, input limits and parameters. Run this to find a model name for 'Generate embeddings', 'Rerank documents' or a new integrated index.

Inputs

Kind of modelmodel_typetext: Narrow the list to one kind. Leave empty for both.One of: embed (Embedding models - text into vectors), rerank (Reranking models - re-order search results).
Vector typevector_typetext: Narrow embedding models to the kind of vector they produce. Only applies when the kind is 'Embedding models'.One of: dense (Dense - an array of floats), sparse (Sparse - indices and values, for keyword-style search).

Outputs

countnumber: How many there are
modelslist: The models that matched
nameslist: Just the model names, for chaining

Example output

{
  "count": 1,
  "models": [
    {
      "default_dimension": 1024,
      "max_batch_size": 96,
      "max_sequence_length": 2048,
      "modality": "text",
      "model": "llama-text-embed-v2",
      "provider_name": "NVIDIA",
      "short_description": "A high performance dense embedding model for text.",
      "supported_dimensions": [
        384,
        512,
        768,
        1024,
        2048
      ],
      "supported_metrics": [
        "cosine",
        "dotproduct"
      ],
      "supported_parameters": [
        {
          "allowed_values": [
            "query",
            "passage"
          ],
          "parameter": "input_type",
          "required": true,
          "type": "one_of",
          "value_type": "string"
        }
      ],
      "type": "embed",
      "vector_type": "dense"
    }
  ],
  "names": [
    "llama-text-embed-v2"
  ]
}

List namespaces

List every namespace in an index, with how many records each one holds and how much space it uses. A namespace exists as soon as something is written into it, so there is nothing to create.

Inputs

IndexindextextRequired: Which index to work with. Pick from the list, or paste the index's host from the Pinecone console - a value ending in '.pinecone.io' is used as the host directly.
Name starts withprefixtext: Only return namespaces beginning with this. Leave empty for all of them.
Limitlimitnumber: How many results to return per page, 1-100. Defaults to 100, which is also Pinecone's ceiling.From 1 to 100. Default: 100.
Page tokenpagination_tokentext: Feed the 'next_pagination_token' from a previous run back in here to read the next page. Leave empty to start at the beginning.

Outputs

countnumber: How many came back on this page
has_moretrue/false: Whether another page follows
nameslist: Just the namespace names, for chaining
namespaceslist: The namespaces on this page
next_pagination_tokentext: The 'Page token' that reads the next page, or empty
total_countnumber: How many the index has in total

Example output

{
  "count": 2,
  "has_more": false,
  "names": [
    "catalogue",
    "staging"
  ],
  "namespaces": [
    {
      "name": "catalogue",
      "record_count": "1240"
    },
    {
      "name": "staging",
      "record_count": "18"
    }
  ],
  "next_pagination_token": null,
  "total_count": 2
}

List record IDs

List the ids stored in one namespace, in sorted order, optionally narrowed to those starting with a prefix. This is how you find an id when you do not already have one - the vectors themselves come from 'Fetch vectors'.

Inputs

IndexindextextRequired: Which index to work with. Pick from the list, or paste the index's host from the Pinecone console - a value ending in '.pinecone.io' is used as the host directly.
Namespacenamespacetext: Which namespace inside the index to work in. Namespaces partition an index - a search only ever sees one. Leave empty for the default namespace, which is also called '__default__'.
ID starts withprefixtext: Only return ids beginning with this. Ids are often written 'document1#chunk3', so a prefix of 'document1#' returns one document's chunks. Leave empty for everything.
Limitlimitnumber: How many results to return per page, 1-100. Defaults to 100, which is also Pinecone's ceiling.From 1 to 100. Default: 100.
Page tokenpagination_tokentext: Feed the 'next_pagination_token' from a previous run back in here to read the next page. Leave empty to start at the beginning.

Outputs

countnumber: How many ids came back
has_moretrue/false: Whether another page follows
idslist: The ids on this page, sorted
namespacetext: The namespace that was listed
next_pagination_tokentext: The 'Page token' that reads the next page, or empty
usageobject: Read units this call consumed

Example output

{
  "count": 2,
  "has_more": false,
  "ids": [
    "sku-4181",
    "sku-4182"
  ],
  "namespace": "catalogue",
  "next_pagination_token": null,
  "usage": {
    "readUnits": 1
  }
}

Rerank documents

Re-order a list of documents by how well they answer a question, using a hosted reranking model. Useful straight after a search: a vector search finds candidates quickly and a reranker puts the genuinely relevant ones on top. Plain strings are accepted as documents.

Inputs

ModelmodeltextRequired: Which hosted reranking model to run.
QuestionquerytextRequired: What the documents are being ranked against.
DocumentsdocumentslistRequired: The documents to re-order. A list of plain strings works - each becomes {"text": "..."}, which is what the default ranking field reads. Objects work too, in which case name their field below.
Fields to rank onrank_fieldslist: Which field of each document the model should read. Leave empty for 'text', which is what plain strings become. Every document must carry the field named.
How many to keeptop_nnumber: How many of the reranked documents to return. Leave empty to keep them all, reordered.At least 1.
Include the documentsreturn_documentstrue/false: Whether each result carries the document itself as well as its score and original position. On by default.Default: true.
If the text is too longtruncatetext: What the model should do with input longer than it can read. Leave empty for the model's own default.One of: END (Cut the end off and embed the rest), NONE (Refuse the request instead).
Extra model parametersparametersobject: Any further model-specific parameters, such as {"dimension": 512}. Run "List models" to see what a model accepts. The fields above win over the same keys given here.

Outputs

countnumber: How many results came back
datalist: The documents, best first
modeltext: The model that ranked them
orderlist: Each result's position in the list that was sent
top_scorenumber: The best document's relevance, 0 to 1
usageobject: Rerank units this call consumed

Example output

{
  "count": 1,
  "data": [
    {
      "document": {
        "text": "Cast iron holds heat far longer than steel."
      },
      "index": 1,
      "score": 0.9134
    }
  ],
  "model": "bge-reranker-v2-m3",
  "order": [
    1
  ],
  "top_score": 0.9134,
  "usage": {
    "rerank_units": 1
  }
}

Search records

Search a namespace with a question in plain text, and optionally rerank the results in the same call. Searching by text needs an index built with 'Create index with an embedding model'; searching by vector or by the id of a stored record works on any index. Give exactly one of the three.

Inputs

IndexindextextRequired: Which index to work with. Pick from the list, or paste the index's host from the Pinecone console - a value ending in '.pinecone.io' is used as the host directly.
NamespacenamespacetextRequired: Which namespace inside the index to work in. This endpoint names the namespace in its address, so it cannot be left out; use '__default__' for the default one.
Questionquery_texttext: What to search for, in plain text. Pinecone embeds it with the index's own model. Only works on an index built with an embedding model.
Query vectorquery_vectorlist: Search with a vector instead of text - as wide as the index. Leave empty when a question is given.
Query by record IDquery_idtext: Search for records similar to one already in the namespace. Leave empty when a question or a vector is given.
How many resultstop_knumber: How many of the nearest matches to return, 1-10000. Defaults to 10.From 1 to 10000. Default: 10.
Metadata filterfilterobject: Narrow the search by metadata, in Pinecone's filter syntax - {"genre": {"$in": ["comedy", "drama"]}, "year": {"$eq": 2019}}. Leave empty to search everything in the namespace.
Fields to returnfieldslist: Which of each record's fields to include in the results - for example ["chunk_text"]. Leave empty for all of them.
Rerank withrerank_modeltext: Optionally re-order the results with a reranking model before they are returned. Leave empty to keep the search's own order.
Fields to rerank onrerank_fieldslist: Which field the reranking model should read, such as ["chunk_text"]. Required when a reranking model is chosen, and every returned record must carry the field.
How many to keep after rerankingrerank_top_nnumber: How many results to keep once reranked. Leave empty to keep them all, reordered.At least 1.
Rerank questionrerank_querytext: A different question to rank against. Required when reranking a search made by vector or record ID, since there is no query text to use.

Outputs

countnumber: How many records came back
hitslist: The matching records, best first
idslist: Just the matching ids, for chaining
namespacetext: The namespace that was searched
top_hitobject: The single best record, or empty
usageobject: Read units, embedding tokens and rerank units used

Example output

{
  "count": 1,
  "hits": [
    {
      "_id": "doc-17",
      "_score": 0.913,
      "fields": {
        "chunk_text": "Cast iron holds heat far longer than steel."
      }
    }
  ],
  "ids": [
    "doc-17"
  ],
  "namespace": "handbook",
  "top_hit": {
    "_id": "doc-17",
    "_score": 0.913,
    "fields": {
      "chunk_text": "Cast iron holds heat far longer than steel."
    }
  },
  "usage": {
    "embed_total_tokens": 8,
    "read_units": 5
  }
}

Search with a vector

Find the vectors nearest to one you supply, or nearest to a vector already in the index. Returns each match's id and similarity score, most similar first, with its metadata unless you turn that off. Give a vector or an id, not both.

Inputs

IndexindextextRequired: Which index to work with. Pick from the list, or paste the index's host from the Pinecone console - a value ending in '.pinecone.io' is used as the host directly.
Query vectorvectorlist: The vector to search with - as wide as the index. The 'embeddings' from a 'Generate embeddings' step drops straight in here.
Query by vector IDvector_idtext: Instead of supplying a vector, name one already in the index and search for what is nearest to it - 'more like this'. Leave empty when a query vector is given.
Namespacenamespacetext: Which namespace inside the index to work in. Namespaces partition an index - a search only ever sees one. Leave empty for the default namespace, which is also called '__default__'.
How many resultstop_knumber: How many of the nearest matches to return, 1-10000. Defaults to 10.From 1 to 10000. Default: 10.
Metadata filterfilterobject: Narrow the search by metadata, in Pinecone's filter syntax - {"genre": {"$in": ["comedy", "drama"]}, "year": {"$eq": 2019}}. Leave empty to search everything in the namespace.
Include the vectorsinclude_valuestrue/false: Whether each match carries its numbers as well as its id and score. Off by default: the numbers are large and slow to read back, and rarely what a workflow wants.Default: false.
Include metadatainclude_metadatatrue/false: Whether each match carries the metadata stored with it. On by default, because that is usually the part a later step reads.Default: true.

Outputs

countnumber: How many matches came back
idslist: Just the matching ids, for chaining
matcheslist: The nearest vectors, most similar first
namespacetext: The namespace that was searched
top_matchobject: The single nearest vector, or empty
usageobject: Read units this search consumed

Example output

{
  "count": 1,
  "ids": [
    "sku-4181"
  ],
  "matches": [
    {
      "id": "sku-4181",
      "metadata": {
        "category": "cookware",
        "title": "Cast iron skillet"
      },
      "score": 0.8721
    }
  ],
  "namespace": "catalogue",
  "top_match": {
    "id": "sku-4181",
    "metadata": {
      "category": "cookware",
      "title": "Cast iron skillet"
    },
    "score": 0.8721
  },
  "usage": {
    "readUnits": 5
  }
}

Update vector

Change one stored vector's numbers, its metadata, or both, without rewriting the rest of it. Metadata given here is merged into what is already stored, so keys you leave out are kept.

Inputs

IndexindextextRequired: Which index to work with. Pick from the list, or paste the index's host from the Pinecone console - a value ending in '.pinecone.io' is used as the host directly.
Vector IDvector_idtextRequired: Which vector to change.
New valuesvalueslist: A replacement vector, as wide as the index. Leave empty to keep the stored numbers.
Metadata to setset_metadataobject: Metadata keys to add or overwrite - {"category": "cookware"}. Keys not named here are left alone. Values must be a string, number, boolean or list of strings.
New sparse valuessparse_valuesobject: A replacement sparse vector, as {"indices": [1, 312], "values": [0.4, 0.9]} with the two lists the same length. Only for an index that stores sparse vectors.
Namespacenamespacetext: Which namespace inside the index to work in. Namespaces partition an index - a search only ever sees one. Leave empty for the default namespace, which is also called '__default__'.

Outputs

indextext: The index it is in
matched_recordsnumber: How many records the change touched
namespacetext: The namespace it is in
updatedtrue/false: True once Pinecone has applied the change
vector_idtext: The vector that was changed

Example output

{
  "index": "product-search",
  "matched_records": 1,
  "namespace": "catalogue",
  "updated": true,
  "vector_id": "sku-4181"
}

Upsert text records

Write text straight into an index built with 'Create index with an embedding model' - Pinecone embeds it for you, so nothing has to produce a vector first. Each record needs an '_id' and the index's text field; anything else on it is stored as metadata. Writing an id again replaces it.

Inputs

IndexindextextRequired: Which index to work with. Pick from the list, or paste the index's host from the Pinecone console - a value ending in '.pinecone.io' is used as the host directly.
NamespacenamespacetextRequired: Which namespace inside the index to work in. This endpoint names the namespace in its address, so it cannot be left out; use '__default__' for the default one.
RecordsrecordslistRequired: The records to write, at most 1000 at a time - for example [{"_id": "doc-17", "chunk_text": "Cast iron holds heat.", "category": "cookware"}]. The text field must be the one named when the index was created.

Outputs

idslist: The ids that were written, for chaining
indextext: The index they went into
namespacetext: The namespace they went into
upserted_countnumber: How many records were sent

Example output

{
  "ids": [
    "doc-17"
  ],
  "index": "support-articles",
  "namespace": "handbook",
  "upserted_count": 1
}

Upsert vectors

Write vectors into a namespace. Each one is an id, an array of numbers as wide as the index, and optional metadata to filter on later. Writing an id that is already there replaces it, so this is safe to re-run.

Inputs

IndexindextextRequired: Which index to work with. Pick from the list, or paste the index's host from the Pinecone console - a value ending in '.pinecone.io' is used as the host directly.
VectorsvectorslistRequired: The vectors to write, at most 1000 at a time - for example [{"id": "sku-4181", "values": [0.12, -0.04], "metadata": {"category": "cookware"}}]. Metadata values must be a string, number, boolean or list of strings.
Namespacenamespacetext: Which namespace inside the index to work in. Namespaces partition an index - a search only ever sees one. Leave empty for the default namespace, which is also called '__default__'.

Outputs

idslist: The ids that were written, for chaining
indextext: The index they went into
namespacetext: The namespace they went into
upserted_countnumber: How many vectors Pinecone stored

Example output

{
  "ids": [
    "sku-4181"
  ],
  "index": "product-search",
  "namespace": "catalogue",
  "upserted_count": 1
}

ActionsCopy Anchor Link

Configure indexCopy Anchor Link

Inputs

Outputs

Create indexCopy Anchor Link

Inputs

Outputs

Create index with an embedding modelCopy Anchor Link

Inputs

Outputs

Delete indexCopy Anchor Link

Inputs

Outputs

Delete namespaceCopy Anchor Link

Inputs

Outputs

Delete vectorsCopy Anchor Link

Inputs

Outputs

Describe indexCopy Anchor Link

Inputs

Outputs

Fetch vectorsCopy Anchor Link

Inputs

Outputs

Generate embeddingsCopy Anchor Link

Inputs

Outputs

Get index statisticsCopy Anchor Link

Inputs

Outputs

List indexesCopy Anchor Link

Inputs

Outputs

List modelsCopy Anchor Link

Inputs

Outputs

List namespacesCopy Anchor Link

Inputs

Outputs

List record IDsCopy Anchor Link

Inputs

Outputs

Rerank documentsCopy Anchor Link

Inputs

Outputs

Search recordsCopy Anchor Link

Inputs

Outputs

Search with a vectorCopy Anchor Link

Inputs

Outputs

Update vectorCopy Anchor Link

Inputs

Outputs

Upsert text recordsCopy Anchor Link

Inputs

Outputs

Upsert vectorsCopy Anchor Link

Inputs

Outputs

On this page

Actions

Configure index

Create index

Create index with an embedding model

Delete index

Delete namespace

Delete vectors

Describe index

Fetch vectors

Generate embeddings

Get index statistics

List indexes

List models

List namespaces

List record IDs

Rerank documents

Search records

Search with a vector

Update vector

Upsert text records

Upsert vectors