# Embed records

Chunk text records per document and embed each chunk through Knowledge.

## When to use it

Create searchable representations of document text in chunks. Choose a compatible embedding model and destination. A new model or chunking strategy can require reindexing; semantic similarity does not verify that a retrieved passage answers a question correctly.

## Add and configure

1. Add **Embed records** 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 `embed`.

## Settings

| Setting | Accepted value | Required | Default | What it controls |
| --- | --- | --- | --- | --- |
| Batch Size (`batch_size`) | integer; minimum 1; maximum 500 | No | 128 | Maximum chunk texts submitted together for embedding; at most 500 per batch. |
| Embedding Profile (`embedding_profile`) | string or null | No | null | Embedding configuration shared by indexing and retrieval. Compatible profiles are needed to compare vectors meaningfully. |
| Generation Model (`generation_model`) | string or null | No | null | Model choice used when generating content associated with this embedding task. |
| Group By Field (`group_by_field`) | string | No | "object_key" | Record field that scopes chunk identity (one document per group). Records missing it group under 'ungrouped'. |
| Include Breadcrumbs (`include_breadcrumbs`) | boolean | No | true | Prefix each chunk with its heading path ('A > B'). |
| Max Tokens (`max_tokens`) | integer; minimum 64; maximum 2000 | No | 480 | Token budget per chunk. |
| Min Chunk Tokens (`min_chunk_tokens`) | integer; minimum 0 | No | 120 | Trailing chunks under this merge into their predecessor (same heading). |
| Model (`model`) | string or null | No | null | Optional embedding model selection. It must match the embedding configuration available to your organisation. Leave unset to use that default. |
| Order By Field (`order_by_field`) | string | No | "index" | Record field that orders segments within a group. |
| Overlap Tokens (`overlap_tokens`) | integer; minimum 0; maximum 512 | No | 64 | Tokens shared between consecutive parts of a split chunk. |
| Record Type (`record_type`) | string | No | "embedded_chunk" | `record_type` stamped on every emitted record. |
| Text Field (`text_field`) | string | No | "text" | Record field holding the text to chunk and embed. |

## Inputs and outputs

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

### Outputs record fields

| Setting | Accepted value | Required | Default | What it controls |
| --- | --- | --- | --- | --- |
| dimensions (`dimensions`) | integer or null | No | Not specified | — |
| embedding (`embedding`) | list of number | Yes | Not specified | — |
| meta (`meta`) | object | No | Not specified | — |
| model (`model`) | string or null | No | Not specified | Provider-qualified model identifier for the operation. |
| ref (`ref`) | string; minimum characters 1 | Yes | Not specified | — |
| text (`text`) | string | No | Not specified | — |

## Effects, testing, and recovery

Calls a model and can consume model budget.

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: Embed digest segments grouped by file (defaults)

Step settings:

```json
{
  "group_by_field": "object_key",
  "text_field": "text"
}
```

## Example: Smaller chunks with a wider overlap

Step settings:

```json
{
  "max_tokens": 256,
  "min_chunk_tokens": 64,
  "overlap_tokens": 48
}
```

## 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.