# JSONata

Apply a [JSONata](https://jsonata.org/) query to select, reshape, and compute values from JSON. Use it when you need
more than simple field extraction: filtering, aggregation, mapping, or building a new JSON shape from an existing
payload. JSONata lives in the **Data format** category of the `fx` menu. For expression syntax and operators, see the
[JSONata documentation](https://docs.jsonata.org/).

## Parameters

| Parameter         | Type   | Required | Default | Description                                                                                                                                    |
| ----------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Input             | string | yes      | —       | JSON document as a string. Must parse as JSON.                                                                                                 |
| Query             | string | yes      | `""`    | JSONata expression to evaluate. See the [JSONata documentation](https://docs.jsonata.org/) for syntax and built-in functions.                  |
| Variable Bindings | string | no       | —       | Variables to bind into the expression, as a JSON object string. Example: `{"var1": "value1", "var2": 123}`. Referenced in Query as `$varName`. |

`Input` is the primary JSON document (previous step output or a literal).

:::tip
Enable **Variable Bindings** from **+ Advanced** only when the query needs named variables. Leave it off for simple
field selection and most aggregates.
:::

## Returned value

| Type     | Description                                                                                                                                                    |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `string` | The expression result. Object and array results are a JSON string. Primitive results (string, number, boolean, null) use their string form (for example `85`). |

## Limitations

- Input, Query, and Variable Bindings (when set) must be strings. Non-string input or query raises an error.
- Input and Variable Bindings must be valid JSON. Empty or malformed JSON raises `Invalid JSON format`.
- An empty or syntactically invalid Query raises `Invalid JSONata expression`. See
  [JSONata documentation](https://docs.jsonata.org/) for valid expression forms.
- Variable Bindings must be a JSON **object**. A bindings document of `null` is rejected.
- Large integer values in object results are preserved when the result is stringified (for example, BSON-style IDs).

:::caution
Invalid JSON in **Input** or **Variable Bindings**, or an invalid **Query**, stops evaluation with an error — fix the
string before re-running the step.
:::

## Examples

<details>
<summary>Select a field</summary>

Extract a single property from a JSON object — the most common JSONata use in a flow. Pass the previous step’s JSON
into **Input**, set **Query** to the field name, and read the string result under **Output value**.

1. Set **Input** to the JSON from the previous step (or a literal document).
2. Set **Query** to the field path. Paste:

   ```text title="Query"
   name
   ```

3. Confirm **Output value** shows the selected field.

   <div class="docs-screenshot-compact">

   ![JSONata selecting the name field from a JSON object](./assets/select-a-field.png)

   </div>

</details>

<details>
<summary>Aggregate values</summary>

Compute a total or other aggregate over an array without leaving Studio. Use JSONata aggregation functions such as
`$sum` on nested fields — see [aggregation functions](https://docs.jsonata.org/aggregation-functions) in the JSONata
docs.

1. Set **Input** to a JSON document that contains the array to aggregate.
2. Set **Query** to the aggregate expression. Paste:

   ```text title="Query"
   $sum(items.(price * quantity))
   ```

3. Confirm **Output value** is the numeric result as a string.

   <div class="docs-screenshot-compact">

   ![JSONata summing price times quantity across items](./assets/aggregate-values.png)

   </div>

</details>

<details>
<summary>Filter with variable bindings</summary>

Reuse the same query with different filter values by binding variables instead of hard-coding them in **Query**. Use
this when the city (or other filter) comes from another step or should change without editing the expression. Bound
names are referenced as `$name` in the query — see
[programming constructs](https://docs.jsonata.org/programming) in the JSONata docs.

1. Open **+ Advanced** and enable **Variable Bindings**.

   <div class="docs-screenshot-compact">

   ![JSONata Advanced menu with Variable Bindings optional](./assets/enable-variable-bindings.png)

   </div>

2. Set **Input** to the JSON document. Set **Query** to a filter that uses `$city`. Paste:

   ```text title="Query"
   persons[city=$city].name
   ```

3. Set **Variable Bindings** to a JSON object that defines `city`. Paste:

   ```text title="Variable Bindings"
   {"city":"Paris"}
   ```

4. Confirm **Output value** lists the matching names as a JSON string.

   <div class="docs-screenshot-compact">

   ![JSONata filtering persons by bound city variable](./assets/filter-with-variable-bindings.png)

   </div>

</details>