# Vector search

Find the nearest indexed chunks for each record's query text.

## When to use it

Retrieve semantically similar indexed chunks for each query. Select the index, result count, and filters appropriate to the task. A high similarity score is a ranking signal, not a factual validation of a generated answer.

## Add and configure

1. Add **Vector search** from the workflow step picker.
2. Give the step a recognisable name and connect its required inputs.
3. Set the options below. Nested names identify fields within an object or a list item.
4. Validate the recipe, inspect the test result, then run it on the intended data.

The step identifier used in the editor’s code view is `vector_search`.

## Settings

| Setting | Accepted value | Required | Default | What it controls |
| --- | --- | --- | --- | --- |
| Collection (`collection`) | string; minimum characters 1; maximum characters 128 | No | "default" | Vector-store collection to search within the tenant. |
| Embedding Profile (`embedding_profile`) | string or null | No | null | Embedding configuration shared by indexing and retrieval. Compatible profiles are needed to compare vectors meaningfully. |
| K (`k`) | integer; minimum 1; maximum 100 | No | 5 | Max matches to return per record. |
| Min Score (`min_score`) | number; minimum -1.0; maximum 1.0 or null | No | null | Cosine-similarity floor; matches below it are dropped. |
| Query Field (`query_field`) | string or null | No | null | Record field holding the query text (dotted paths supported, e.g. `question`). Mutually exclusive with query_template. |
| Query Template (`query_template`) | string or null | No | null | Per-record query template with `${field}` placeholders (e.g. `${title} ${body}`). Mutually exclusive with query_field. |

## Inputs and outputs

| Direction | Port | Content | Required | Multiple records |
| --- | --- | --- | --- | --- |
| Inputs | `in` | records | Yes | Yes |
| Outputs | `out` | records | Yes | Yes |

## Effects, testing, and recovery

Reads an external source.

The declared preview behaviour is to execute this step. Reads, processing, or model usage can therefore be real. Read [dry runs](/docs/workflows/dry-runs) before using a preview with live connections.

No duplicate-prevention key is declared for this step. Do not assume that manually repeating the step is free of repeated effects.

## Example: Five nearest chunks for each record's question

Step settings:

```json
{
  "k": 5,
  "query_field": "question"
}
```

## Example: Query rendered from two fields, with a similarity floor

Step settings:

```json
{
  "collection": "apps-support-kb",
  "k": 3,
  "min_score": 0.2,
  "query_template": "${title} ${body}"
}
```

## Check the result

Inspect the selected run’s status, counts, errors, and output records. An empty collection can be a valid result, and a completed step can contain per-record failures where the step defines that behaviour. Check the next step’s expected record shape before publishing or delivering the result.