# transform

> Source: https://docs.clonepartner.com/reference/steps/transform/

<!-- sources: src/steps/transform-step.ts, src/steps/base-step.ts, src/steps/types.ts, references/envoy/step-types.md -->

# transform

Applies a JSONata expression to each item; the evaluated result becomes the item emitted downstream.

## When to use it

Use `transform` to reshape, rename, or compute fields on each record. To remove items from the stream, use a [filter](/reference/steps/filter/) step instead — a transform whose expression evaluates to `null` or `undefined` passes the original input through unchanged rather than dropping it.

## Configuration

The config is not an object with keys — it must be a single JSONata expression string. An object config fails validation with `Transform step config must be a JSONata expression string`.

| Key | Type | Required | Default | Description |
|---|---|---|---|---|
| `config` | string | Yes | — | JSONata expression evaluated per item with `{ input, arguments, steps, variables, job_config }`. The result is emitted downstream. |

## Example

```yaml
name: format-users
connectors:
  source:
    type: csv
steps:
  - name: read_users
    type: call_method
    config:
      connector: source
      method: read
      args:
        resource: users

  - name: format
    type: transform
    config: |
      {
        "id": input.id,
        "full_name": input.first_name & " " & input.last_name,
        "email": input.email
      }
```

## Behavior notes

- **The evaluated expression is the output.** The step has no logic of its own — the config evaluator resolves the expression and the result replaces the input item.
- **Array results fan out.** An array result emits each element as a separate downstream item; an empty array (`[]`) drops the item.
- **`null`/`undefined` results do not drop the item.** The original input passes through unchanged — a common footgun. A pattern like `condition ? input : undefined` keeps non-matching items. Return `[]` to drop from inside a transform, or use a [filter](/reference/steps/filter/) step.
- Available context roots: `input` (current item), `arguments`, `steps.<name>.output`, `variables`, and `job_config`.

## Related

- [filter](/reference/steps/filter/) — the first-class way to remove items from the stream
- [map_fields](/reference/steps/map-fields/) — declarative field mapping instead of a hand-written expression
- [Transforming and filtering](/building/transforming-and-filtering/) — guide-level patterns and JSONata tips