# Pinecone

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

App · Databases · 20 actions. Web page: https://docs.lodol.com/docs/integrations/pinecone

## Actions

### Configure index

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**

- Index (`index`, text, required): 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 protection (`deletion_protection`, text): 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).
- Tags (`tags`, object): 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_protection` (text): enabled or disabled, after the change
- `dimension` (number): How many numbers each vector holds
- `host` (text): The host its vectors are served from
- `index` (object): The index as Pinecone reports it
- `metric` (text): cosine, dotproduct or euclidean
- `name` (text): The index's name
- `ready` (true/false): Whether it can be read and written
- `state` (text): The index's state
- `tags` (object): Custom labels, after the change

**Example output**

```json
{
  "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 name (`name`, text, required): 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.
- Dimension (`dimension`, number, required): 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 metric (`metric`, text): 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`.
- Cloud (`cloud`, text): 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`.
- Region (`region`, text): 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 protection (`deletion_protection`, text): 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`.
- Tags (`tags`, object): Custom labels on the index, at most 20, such as {"env": "staging"}. Keys are 80 characters or fewer and values 120.

**Outputs**

- `deletion_protection` (text): enabled or disabled
- `dimension` (number): How many numbers each vector holds
- `host` (text): The host its vectors are served from
- `index` (object): The index as Pinecone reports it
- `metric` (text): cosine, dotproduct or euclidean
- `name` (text): The index's name
- `ready` (true/false): Whether it can be written to yet
- `state` (text): Usually 'Initializing' right after creation
- `tags` (object): Custom labels on the index

**Example output**

```json
{
  "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 name (`name`, text, required): 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 model (`model`, text, required): Which of Pinecone's hosted models embeds the text. This cannot be changed after the index is created.
- Text field (`text_field`, text): 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 metric (`metric`, text): 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).
- Cloud (`cloud`, text): 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`.
- Region (`region`, text): 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 protection (`deletion_protection`, text): 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`.
- Tags (`tags`, object): Custom labels on the index, at most 20, such as {"env": "staging"}. Keys are 80 characters or fewer and values 120.

**Outputs**

- `deletion_protection` (text): enabled or disabled
- `dimension` (number): The width of the vectors the model produces
- `host` (text): The host its records are served from
- `index` (object): The index as Pinecone reports it
- `metric` (text): cosine, dotproduct or euclidean
- `model` (text): The embedding model it was built with
- `name` (text): The index's name
- `ready` (true/false): Whether it can be written to yet
- `state` (text): Usually 'Initializing' right after creation
- `tags` (object): Custom labels on the index
- `text_field` (text): The record field this index embeds

**Example output**

```json
{
  "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**

- Index (`index`, text, required): 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**

- `deleted` (true/false): True once Pinecone has accepted the deletion
- `index` (text): The index that was deleted

**Example output**

```json
{
  "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**

- Index (`index`, text, required): 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.
- Namespace (`namespace`, text, required): 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**

- `deleted` (true/false): True once Pinecone has deleted it
- `index` (text): The index it was in
- `namespace` (text): The namespace that was deleted

**Example output**

```json
{
  "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**

- Index (`index`, text, required): 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 IDs (`ids`, list): Which vectors to delete, at most 1000 at a time. Leave empty only when emptying the whole namespace below.
- Delete everything in the namespace (`delete_all`, true/false): Delete every vector in the namespace instead of named ids. Off by default, and refused if ids are also given. Default: `false`.
- Namespace (`namespace`, text): 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**

- `deleted` (true/false): True once Pinecone has deleted them
- `deleted_all` (true/false): Whether the whole namespace was emptied
- `ids` (list): The ids that were named, if any
- `index` (text): The index they were deleted from
- `namespace` (text): The namespace they were deleted from

**Example output**

```json
{
  "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**

- Index (`index`, text, required): 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_protection` (text): enabled or disabled
- `dimension` (number): How many numbers each vector holds
- `host` (text): The host its vectors are served from
- `index` (object): The index as Pinecone reports it
- `metric` (text): cosine, dotproduct or euclidean
- `name` (text): The index's name
- `ready` (true/false): Whether it can be read and written yet
- `state` (text): Initializing, Ready, Terminating, ...
- `tags` (object): Custom labels on the index

**Example output**

```json
{
  "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**

- Index (`index`, text, required): 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 IDs (`ids`, list, required): Which vectors to read, at most 1000 at a time. 'List record IDs' returns these.
- Namespace (`namespace`, text): 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**

- `count` (number): How many vectors came back
- `ids` (list): The ids that were found
- `missing_ids` (list): The ids that were asked for and are not there
- `namespace` (text): The namespace they were read from
- `usage` (object): Read units this call consumed
- `vectors` (object): Each id mapped to the vector stored under it

**Example output**

```json
{
  "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**

- Model (`model`, text, required): Which hosted embedding model to run.
- Text (`inputs`, list, required): 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 for (`input_type`, text): 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 long (`truncate`, text): 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 parameters (`parameters`, object): 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**

- `count` (number): How many embeddings came back
- `data` (list): The embeddings as Pinecone reports them
- `embeddings` (list): One vector per input, ready to upsert or search with
- `model` (text): The model that produced them
- `usage` (object): Tokens this call consumed
- `vector_type` (text): dense or sparse

**Example output**

```json
{
  "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**

- Index (`index`, text, required): 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**

- `dimension` (number): How many numbers each vector holds
- `index_fullness` (number): Always 0 on a serverless index, which scales itself
- `metric` (text): How similarity is measured
- `namespace_names` (list): Just the namespace names, for chaining
- `namespaces` (object): Each namespace's name mapped to its vector count
- `total_vector_count` (number): Vectors across every namespace
- `vector_type` (text): dense or sparse

**Example output**

```json
{
  "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**

- `count` (number): How many there are
- `indexes` (list): Every index in the project
- `names` (list): Just the index names, for chaining

**Example output**

```json
{
  "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 model (`model_type`, text): 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 type (`vector_type`, text): 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**

- `count` (number): How many there are
- `models` (list): The models that matched
- `names` (list): Just the model names, for chaining

**Example output**

```json
{
  "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**

- Index (`index`, text, required): 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 with (`prefix`, text): Only return namespaces beginning with this. Leave empty for all of them.
- Limit (`limit`, number): 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 token (`pagination_token`, text): 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**

- `count` (number): How many came back on this page
- `has_more` (true/false): Whether another page follows
- `names` (list): Just the namespace names, for chaining
- `namespaces` (list): The namespaces on this page
- `next_pagination_token` (text): The 'Page token' that reads the next page, or empty
- `total_count` (number): How many the index has in total

**Example output**

```json
{
  "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**

- Index (`index`, text, required): 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.
- Namespace (`namespace`, text): 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 with (`prefix`, text): 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.
- Limit (`limit`, number): 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 token (`pagination_token`, text): 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**

- `count` (number): How many ids came back
- `has_more` (true/false): Whether another page follows
- `ids` (list): The ids on this page, sorted
- `namespace` (text): The namespace that was listed
- `next_pagination_token` (text): The 'Page token' that reads the next page, or empty
- `usage` (object): Read units this call consumed

**Example output**

```json
{
  "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**

- Model (`model`, text, required): Which hosted reranking model to run.
- Question (`query`, text, required): What the documents are being ranked against.
- Documents (`documents`, list, required): 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 on (`rank_fields`, list): 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 keep (`top_n`, number): How many of the reranked documents to return. Leave empty to keep them all, reordered. At least 1.
- Include the documents (`return_documents`, true/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 long (`truncate`, text): 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 parameters (`parameters`, object): 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**

- `count` (number): How many results came back
- `data` (list): The documents, best first
- `model` (text): The model that ranked them
- `order` (list): Each result's position in the list that was sent
- `top_score` (number): The best document's relevance, 0 to 1
- `usage` (object): Rerank units this call consumed

**Example output**

```json
{
  "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**

- Index (`index`, text, required): 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.
- Namespace (`namespace`, text, required): 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.
- Question (`query_text`, text): 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 vector (`query_vector`, list): Search with a vector instead of text - as wide as the index. Leave empty when a question is given.
- Query by record ID (`query_id`, text): Search for records similar to one already in the namespace. Leave empty when a question or a vector is given.
- How many results (`top_k`, number): How many of the nearest matches to return, 1-10000. Defaults to 10. From 1 to 10000. Default: `10`.
- Metadata filter (`filter`, object): 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 return (`fields`, list): Which of each record's fields to include in the results - for example ["chunk_text"]. Leave empty for all of them.
- Rerank with (`rerank_model`, text): 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 on (`rerank_fields`, list): 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 reranking (`rerank_top_n`, number): How many results to keep once reranked. Leave empty to keep them all, reordered. At least 1.
- Rerank question (`rerank_query`, text): 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**

- `count` (number): How many records came back
- `hits` (list): The matching records, best first
- `ids` (list): Just the matching ids, for chaining
- `namespace` (text): The namespace that was searched
- `top_hit` (object): The single best record, or empty
- `usage` (object): Read units, embedding tokens and rerank units used

**Example output**

```json
{
  "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**

- Index (`index`, text, required): 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 vector (`vector`, list): The vector to search with - as wide as the index. The 'embeddings' from a 'Generate embeddings' step drops straight in here.
- Query by vector ID (`vector_id`, text): 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.
- Namespace (`namespace`, text): 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 results (`top_k`, number): How many of the nearest matches to return, 1-10000. Defaults to 10. From 1 to 10000. Default: `10`.
- Metadata filter (`filter`, object): 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 vectors (`include_values`, true/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 metadata (`include_metadata`, true/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**

- `count` (number): How many matches came back
- `ids` (list): Just the matching ids, for chaining
- `matches` (list): The nearest vectors, most similar first
- `namespace` (text): The namespace that was searched
- `top_match` (object): The single nearest vector, or empty
- `usage` (object): Read units this search consumed

**Example output**

```json
{
  "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**

- Index (`index`, text, required): 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 ID (`vector_id`, text, required): Which vector to change.
- New values (`values`, list): A replacement vector, as wide as the index. Leave empty to keep the stored numbers.
- Metadata to set (`set_metadata`, object): 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 values (`sparse_values`, object): 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.
- Namespace (`namespace`, text): 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**

- `index` (text): The index it is in
- `matched_records` (number): How many records the change touched
- `namespace` (text): The namespace it is in
- `updated` (true/false): True once Pinecone has applied the change
- `vector_id` (text): The vector that was changed

**Example output**

```json
{
  "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**

- Index (`index`, text, required): 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.
- Namespace (`namespace`, text, required): 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.
- Records (`records`, list, required): 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**

- `ids` (list): The ids that were written, for chaining
- `index` (text): The index they went into
- `namespace` (text): The namespace they went into
- `upserted_count` (number): How many records were sent

**Example output**

```json
{
  "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**

- Index (`index`, text, required): 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.
- Vectors (`vectors`, list, required): 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.
- Namespace (`namespace`, text): 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**

- `ids` (list): The ids that were written, for chaining
- `index` (text): The index they went into
- `namespace` (text): The namespace they went into
- `upserted_count` (number): How many vectors Pinecone stored

**Example output**

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