> For the complete documentation index, see [llms.txt](https://docs.middle.app/middle-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.middle.app/middle-docs/product/accounts/workflow-parameters/array-manipulation.md).

# Array Manipulation

An array is a data structure that stores a list of elements, typically of the same type, where each element is accessible by an index. Middle is able to accommodate arrays within synced data and Action inputs and outputs.

An example of an array is a list of line items in an invoice. This list of line items would appear as an array, along with other fields in the invoice, such as the invoice ID and sale date.

When arrays are involved in your data you will need to use array manipulation parameters to parse out the data you need. Array manipulation tools can be used together to perform multiple functions to an array.

The examples below use the JSON found in a [copied workflow](https://docs.middle.app/middle-docs/product/accounts/workflow-parameters.md). `params` contains child parameters in the order shown. These array parameters do not use their own `expression`; their settings are child parameters.

Map, Reduce, Filter, Sort, and First provide [parameter-scoped variables](https://docs.middle.app/middle-docs/product/accounts/workflow-parameters/variables.md#parameter-scoped-variable) while evaluating each item. With `"output_name": "items"`, `items:value` is the current item and `items:index` is its position in the original array, starting at `0`. Reduce also provides `items:acc`, the accumulated value. These names are available only inside the operation's mapping, reduction, comparison, or sort-key parameter, including its descendants. Use different output names for nested operations so the inner operation does not hide the outer one's variables.

## Map Array

JSON type: `map_array`.

Allows you to take an array and map it into a new array. For example, you can extract each invoice line's price, or use [Construct Object](https://docs.middle.app/middle-docs/product/accounts/workflow-parameters/advanced-parameters.md#construct-object) to build a different object for each line. Map produces one output item for each input item, in the same order. All output items must have the same type. An empty input array produces an empty array.

| Child       | Purpose                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------- |
| `params[0]` | The array to map.                                                                           |
| `params[1]` | The value to produce for each item. It can use `output_name:value` and `output_name:index`. |

This example converts `[100, 250]` from cents to dollars and returns `[1, 2.5]`.

```json
{
  "type": "map_array",
  "output_name": "prices",
  "params": [
    {
      "type": "construct_array",
      "params": [
        {"type": "math_expression", "expression": "100"},
        {"type": "math_expression", "expression": "250"}
      ]
    },
    {
      "type": "math_expression",
      "expression": "{} * 0.01",
      "params": [
        {"type": "parent_np_selector", "expression": "prices:value"}
      ]
    }
  ]
}
```

## Reduce Array

JSON type: `reduce_array`.

Allows you to take an array and output a single value. Accommodates accumulation so that you can add up numbers or compile strings from multiple array objects. The initial value becomes the accumulator before the first item. Each item's result replaces the accumulator, and the final accumulator is returned. An empty array returns the initial value unchanged.

| Child       | Purpose                                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| `params[0]` | The array to reduce.                                                                                    |
| `params[1]` | The initial accumulator, such as `0` for addition or empty text for joining strings.                    |
| `params[2]` | The next accumulator value. It can use `output_name:value`, `output_name:index`, and `output_name:acc`. |

Keep the result's type consistent with the initial accumulator. This example adds `10` and `20` to a starting value of `0`, returning `30`.

```json
{
  "type": "reduce_array",
  "output_name": "total",
  "params": [
    {
      "type": "construct_array",
      "params": [
        {"type": "math_expression", "expression": "10"},
        {"type": "math_expression", "expression": "20"}
      ]
    },
    {"type": "math_expression", "expression": "0"},
    {
      "type": "math_expression",
      "expression": "{} + {}",
      "params": [
        {"type": "parent_np_selector", "expression": "total:acc"},
        {"type": "parent_np_selector", "expression": "total:value"}
      ]
    }
  ]
}
```

## Filter Array

JSON type: `filter_array`.

Allows you to filter an array based on decision criteria. These criteria are applied to each object in the array. An item stays in the array when the comparison returns true. Filter preserves the original items and their order; it does not change their values. If no items match, the result is an empty array.

| Child       | Purpose                                                                                              |
| ----------- | ---------------------------------------------------------------------------------------------------- |
| `params[0]` | The array to filter.                                                                                 |
| `params[1]` | A boolean condition evaluated for each item. It can use `output_name:value` and `output_name:index`. |

This example keeps numbers greater than `10`, returning `[20]`. See [Flow Control](https://docs.middle.app/middle-docs/product/accounts/workflow-parameters/flow-control.md#if) for every comparison option.

```json
{
  "type": "filter_array",
  "output_name": "amounts",
  "params": [
    {
      "type": "construct_array",
      "params": [
        {"type": "math_expression", "expression": "5"},
        {"type": "math_expression", "expression": "20"}
      ]
    },
    {
      "type": "comparison",
      "expression": "NUMBERLIKE_GREATER_THAN",
      "params": [
        {"type": "parent_np_selector", "expression": "amounts:value"},
        {"type": "math_expression", "expression": "10"}
      ]
    }
  ]
}
```

## Sort Array

JSON type: `sort_array`.

Allows you to sort an array's values or sort its objects based on a field within each object. Sorting is ascending unless reverse is true. Reversing the sort with a date or datetime will sort the array from newest to oldest.

| Child       | Purpose                                                                                   |
| ----------- | ----------------------------------------------------------------------------------------- |
| `params[0]` | The array to sort.                                                                        |
| `params[1]` | Reverse: a boolean. Include this when supplying a sort key.                               |
| `params[2]` | The key to compare for each item. It can use `output_name:value` and `output_name:index`. |

With just the first child, Sort compares the items themselves in ascending order. For an explicit reverse setting or an object field, supply all three children. Use `props` on the scoped value to select an object's field. Keys must be comparable values such as numbers, strings, dates, or datetimes; a missing field or incompatible key types can prevent sorting. Ascending sorts preserve the original order of items with equal keys; reverse sorts also reverse the order within those ties.

This example sorts `[10, 30, 20]` in descending order, returning `[30, 20, 10]`.

```json
{
  "type": "sort_array",
  "output_name": "scores",
  "params": [
    {
      "type": "construct_array",
      "params": [
        {"type": "math_expression", "expression": "10"},
        {"type": "math_expression", "expression": "30"},
        {"type": "math_expression", "expression": "20"}
      ]
    },
    {"type": "boolean", "expression": "BOOLEAN_IS_TRUE"},
    {"type": "parent_np_selector", "expression": "scores:value"}
  ]
}
```

## First Match in Array

JSON type: `first`.

Allows you to output either the first item in the array or the first item that matches the defined criteria. The result is a single item, not an array. If the input is empty or no item matches, the result is null. A null input also returns null. To use a field from the selected item, add `props` to the First parameter itself.

| Child       | Purpose                                                                                                                       |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `params[0]` | The array to search.                                                                                                          |
| `params[1]` | Optional boolean condition. It can use `output_name:value` and `output_name:index`. Without it, First returns the first item. |

First stops at the first match in the current array order. Sort the array first if you need the newest or highest match. This example returns `20`.

```json
{
  "type": "first",
  "output_name": "amounts",
  "params": [
    {
      "type": "construct_array",
      "params": [
        {"type": "math_expression", "expression": "5"},
        {"type": "math_expression", "expression": "20"},
        {"type": "math_expression", "expression": "30"}
      ]
    },
    {
      "type": "comparison",
      "expression": "NUMBERLIKE_GREATER_THAN",
      "params": [
        {"type": "parent_np_selector", "expression": "amounts:value"},
        {"type": "math_expression", "expression": "10"}
      ]
    }
  ]
}
```

## Count Array

JSON type: `array_length`.

Counts the items in an array. When used in conjunction with an array filter this allows you to know if and how many items in the array meet the filter criteria. Its only child, `params[0]`, is the array to count. An empty array returns `0`; null is not an array and cannot be counted.

This example returns `2`.

```json
{
  "type": "array_length",
  "params": [
    {
      "type": "construct_array",
      "params": [
        {"type": "template", "expression": "Yoga"},
        {"type": "template", "expression": "Pilates"}
      ]
    }
  ]
}
```

## De-duplicate Array

JSON type: `dedupe_array`.

Removes repeated values from an array. Its only child, `params[0]`, is an array of scalar values, such as strings, numbers, dates, datetimes, or booleans. There is no separate field or comparison option. To get unique values from a field in an array of objects, first use Map Array to extract that field, then de-duplicate the resulting array.

De-duplicate does not preserve array order. Use Sort Array afterward if order matters. Text values are case-sensitive, so `"Yoga"` and `"yoga"` remain separate values. An empty array returns an empty array.

This example returns the two unique strings `"Yoga"` and `"Pilates"`, in no guaranteed order.

```json
{
  "type": "dedupe_array",
  "params": [
    {
      "type": "construct_array",
      "params": [
        {"type": "template", "expression": "Yoga"},
        {"type": "template", "expression": "Pilates"},
        {"type": "template", "expression": "Yoga"}
      ]
    }
  ]
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.middle.app/middle-docs/product/accounts/workflow-parameters/array-manipulation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
