# Map fields

Reshape each record: select, rename, drop and set fields, with ${…} templates.

## When to use it

Select, rename, remove, and set fields to reshape each input record. Use record templates for calculated text. Check for name collisions and missing inputs before connecting a write destination.

## Add and configure

1. Add **Map fields** 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 `map`.

## Settings

| Setting | Accepted value | Required | Default | What it controls |
| --- | --- | --- | --- | --- |
| Drop (`drop`) | list of string | No | Not specified | Top-level fields to remove. |
| Rename (`rename`) | object of string | No | Not specified | Top-level fields to rename, `{old: new}`, all at once (two fields can swap). A renamed field replaces any field already named `new`. |
| Select (`select`) | list of string or null | No | null | Top-level fields to keep, in this order; every other field is left out. Omit to start from the whole record. |
| Select Missing (`select_missing`) | "omit" / "null" | No | "omit" | A selected field the record lacks: `omit` leaves it out, `null` writes null. |
| Set (`set`) | object | No | Not specified | Fields to write, `{field: value}`. Strings may embed `${…}` expressions — a JSONPath into the INPUT record, a literal, or a builtin call such as `${lower($.title)}`; `$${` is a literal `${`. |
| when (`when`) | object or null | No | null | Only records matching this predicate are mapped; the rest pass through unchanged. |
| Op (`when.op`) | "eq" / "ne" / "contains" / "exists" / "in" | No | "exists" | Comparison operation (as in `filter`). |
| Path (`when.path`) | string | Yes | Not specified | JSONPath into each record (e.g. `$.status`). |
| Value (`when.value`) | value or null | No | null | Comparison value (ignored for 'exists'). |

## Inputs and outputs

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

## Effects, testing, and recovery

Transforms or passes records without a declared external side effect.

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. The step declares safe replay for its supported recovery path.

## Example: Project a fixed set of fields, null when absent

Step settings:

```json
{
  "select": [
    "id",
    "title",
    "url"
  ],
  "select_missing": "null"
}
```

Input records:

```json
[
  {
    "id": 1,
    "raw": {
      "html": "…"
    },
    "title": "A",
    "url": "https://a.example"
  },
  {
    "id": 2,
    "title": "B"
  }
]
```

Expected output for this example:

```json
[
  {
    "id": 1,
    "title": "A",
    "url": "https://a.example"
  },
  {
    "id": 2,
    "title": "B",
    "url": null
  }
]
```

## Example: Rename, drop and derive fields with templates

Step settings:

```json
{
  "drop": [
    "internal"
  ],
  "rename": {
    "desc": "summary"
  },
  "set": {
    "label": "${upper($.code)}: ${$.name}",
    "price": "${number($.price)}",
    "summary_or_name": "${coalesce($.desc, $.name)}"
  }
}
```

Input records:

```json
[
  {
    "code": "ab",
    "internal": true,
    "name": "Widget",
    "price": "9.50"
  }
]
```

Expected output for this example:

```json
[
  {
    "code": "ab",
    "label": "AB: Widget",
    "name": "Widget",
    "price": 9.5,
    "summary_or_name": "Widget"
  }
]
```

## Example: Flag only the matching records

Step settings:

```json
{
  "set": {
    "urgent": true
  },
  "when": {
    "op": "eq",
    "path": "$.priority",
    "value": "high"
  }
}
```

Input records:

```json
[
  {
    "id": 1,
    "priority": "High"
  },
  {
    "id": 2,
    "priority": "low"
  }
]
```

Expected output for this example:

```json
[
  {
    "id": 1,
    "priority": "High",
    "urgent": true
  },
  {
    "id": 2,
    "priority": "low"
  }
]
```

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