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

Example

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 step.
• Available context roots: input (current item), arguments, steps.<name>.output, variables, and job_config.

Related

• filter — the first-class way to remove items from the stream
• map_fields — declarative field mapping instead of a hand-written expression
• Transforming and filtering — guide-level patterns and JSONata tips