> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ingestly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Transform

> Reshape, convert, or script-process data within a pipeline.

<Note>This node is in **preview**. Its behavior may change in future releases.</Note>

The transform node reshapes data produced by upstream nodes. Choose a mode to match your use case: convert data to a standard format, map fields into a new structure, or write a custom script.

## When to use transform

* You need the output in a **specific format**: CSV for a data warehouse, Excel for a finance team, XML for a legacy integration. Use **Format** mode.
* The downstream system expects a different field shape than extract produced. Use **Schema transform** mode to remap names and nesting.
* You need to compute derived values (totals, normalized currencies, days overdue) that shouldn't have come from the AI. Use **Script** mode to do the math deterministically.
* Skip transform when the extract output already matches the downstream schema. A pass-through transform adds runtime without value.

## Mode

Select the top-level **Mode** to switch between transform behaviors:

| Mode                 | Description                                                                             |
| -------------------- | --------------------------------------------------------------------------------------- |
| **Format**           | Convert data to CSV, JSON, XML, or Excel                                                |
| **Schema transform** | Map input fields to a new output structure using field mapping and template expressions |
| **Script**           | Write a custom script to transform data                                                 |

## Configuration

### Format mode

| Field               | Type    | Required | Description                                                  |
| ------------------- | ------- | -------- | ------------------------------------------------------------ |
| **Output format**   | select  | Yes      | Target format: `CSV`, `JSON`, `XML`, or `Excel`              |
| **JSON path**       | string  | No       | JSONPath expression to select a subset of the input data     |
| **Delimiter**       | string  | No       | Column delimiter for CSV output. Defaults to `,`             |
| **Include headers** | boolean | No       | Include column headers in CSV output. Defaults to `true`     |
| **Pretty print**    | boolean | No       | Format JSON/XML output with indentation. Defaults to `false` |
| **Sheet name**      | string  | No       | Worksheet name for Excel output                              |
| **Root element**    | string  | No       | Root element name for XML output                             |

### Schema transform mode

| Field              | Type           | Required | Description                                                      |
| ------------------ | -------------- | -------- | ---------------------------------------------------------------- |
| **Field mappings** | mapping editor | Yes      | Define output fields by mapping input field paths to output keys |

Use `>` as the separator for nested field paths. For example, `invoice > total` refers to the `total` property inside the `invoice` object. The editor validates field references against the upstream node's output schema and provides autocomplete suggestions as you type.

You can use template expressions inside mapping values to concatenate fields, apply transformations, or insert literal text.

### Script mode

| Field      | Type        | Required | Description                                                                           |
| ---------- | ----------- | -------- | ------------------------------------------------------------------------------------- |
| **Script** | code editor | Yes      | The script to execute. Reference upstream nodes by name, e.g. `extract.payload.field` |

The script runs in an isolated environment. Each upstream node is exposed as a JS global with the same shape as `{{nodeName}}` in templates (`success`, `payload`, `metadata`, `error`). Return a value from the script to pass it to the next node.

```js theme={null}
// Combine an upstream extract with a variable node
return {
  customer: extract.payload.email,
  threshold: Number(vars.payload.amountLimit),
  flagged: extract.payload.amount > vars.payload.amountLimit
};
```

## Inputs and outputs

**Allowed inputs:** Extract, merge, HTTP, loop, variable, store, prompt.

**Output:** Data converted, mapped, or transformed according to the configured mode.

## Related

<CardGroup cols={2}>
  <Card title="Extract action" icon="sparkles" href="/nodes/extract">
    Extract structured data before transforming
  </Card>

  <Card title="Callback output" icon="webhook" href="/nodes/callback">
    Deliver transformed data via webhook
  </Card>

  <Card title="Email output" icon="paper-plane" href="/nodes/email-output">
    Send transformed data via email
  </Card>

  <Card title="Review action" icon="user-check" href="/nodes/review">
    Review data before transforming
  </Card>
</CardGroup>