<!-- BusyBot node reference — https://busybot.net/tools/aggregate/ -->

> Node: Aggregate (`aggregate`) · Action · v1
> Category: Core Nodes · Credentials: none
> Updated: 2026-08-16

# Aggregate

> Combine many items into one

## Overview

Aggregates many items into a single item for downstream output. Supports Individual Fields mode (collect chosen fields into arrays) and All Item Data mode (bundle whole items), with options for flattening lists, keeping null entries, carrying binary data and disabling dot notation.

**Category:** Core Nodes  
**Tool Name:** `aggregate`  
**Version:** 1

**Appearance:** Icon: `aggregate` | Color: `#6366f1`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool does not require any credentials.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Mode | `options` | No | `individualFields` | How to aggregate incoming items. |
| | | | | Options: `individualFields`, `allItemData` |
| Fields to Aggregate | `fixedCollection` | No | `{ fields: [] }` | A list of specific fields to collect from incoming items. Field names support dot notation unless disabled. Used in Individual Fields mode. |
| — Input Field Name | `string` | No | — | Field name to collect from each input item. Dot notation is supported unless disabled. Supports expressions. |
| — Rename Field | `boolean` | No | `false` | If enabled, the aggregated list is written to Output Field Name instead. |
| — Output Field Name | `string` | No | — | Name of the output field to store the aggregated list (used only if Rename Field is enabled). |
| Put Output in Field | `string` | No | `data` | The field name on the output item that will contain the final array of all items. Supports dot notation unless disabled. Used in All Item Data mode. |
| Include | `options` | No | `allFields` | Which fields from the input items should be included in the aggregated array. Used in All Item Data mode. |
| | | | | Options: `allFields`, `specifiedFields` |
| Fields To Include | `string` | No | — | Comma-separated field names (or a JSON array string) to include when Include is Specified Fields. Dot notation is supported unless disabled. |
| Options | `collection` | No | `{}` | Additional settings to refine the output. |
| — Merge Lists | `boolean` | No | `false` | If the field being aggregated is already a list, flatten it into one list rather than a list of lists (Individual Fields mode). |
| — Keep Missing and Null Values | `boolean` | No | `false` | When enabled, missing or null entries are preserved as null. When disabled, they are ignored. |
| — Include Binaries | `boolean` | No | `false` | Include binary data (if present on items) in the aggregated output (All Item Data mode). |
| — Disable Dot Notation | `boolean` | No | `false` | Treat dots in field names as literal characters rather than paths to nested objects. |
| Max Concurrency | `number` | No | `100` | Maximum number of items to hydrate/process concurrently. |

## Output Data

Everything that reaches this node is collapsed into **one** output item — however many items arrive, exactly one leaves the main output port. The input JSON does not pass through, and binary data is not forwarded onto the output item itself.

What that item contains depends on Mode:

- **Individual Fields** — one array per entry in Fields to Aggregate, written under that entry's Input Field Name, or under its Output Field Name when Rename Field is on. With Merge Lists on, values that are themselves lists are flattened into the collected array rather than nested inside it. Missing and null values are skipped unless Keep Missing and Null Values is on, in which case they are collected as `null`.
- **All Item Data** — a single array of item objects under Put Output in Field (`data` by default). With Include set to `allFields` each entry is a copy of that item's JSON; with `specifiedFields` each entry contains only the fields named in Fields To Include. With Include Binaries on, each entry also carries the source item's binary data under a `binary` key.

The shape in All Item Data mode with the default output field:

```json
{
  "data": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ]
}
```

Items that arrive already carrying an upstream error are left out of the aggregate; in `errorPort` mode they are routed to the Error output port instead.

Reference the result downstream by expression, e.g. `{{ $json.data }}`.

## Usage Examples

- combine all results into one
- merge everything together
- collect all items into a single output
- aggregate the data from all branches
- gather all the processed results

## Example Configuration

Basic Individual Fields aggregation:

```json
{
  "type": "aggregate",
  "parameters": {
    "mode": "individualFields",
    "fieldsToAggregate": {
      "fields": [
        {
          "inputFieldName": "name",
          "renameField": false,
          "outputFieldName": ""
        },
        {
          "inputFieldName": "email",
          "renameField": true,
          "outputFieldName": "emailAddresses"
        }
      ]
    },
    "putOutputInField": "aggregatedData"
  }
}
```

All Item Data with options:

```json
{
  "type": "aggregate",
  "parameters": {
    "mode": "allItemData",
    "putOutputInField": "allItems",
    "include": "specifiedFields",
    "fieldsToInclude": "id,name,status",
    "options": {
      "keepMissingAndNullValues": true,
      "includeBinaries": false,
      "disableDotNotation": false
    }
  }
}
```

Field aggregation with nested paths:

```json
{
  "type": "aggregate",
  "parameters": {
    "mode": "individualFields",
    "fieldsToAggregate": {
      "fields": [
        {
          "inputFieldName": "user.profile.name",
          "renameField": true,
          "outputFieldName": "userNames"
        },
        {
          "inputFieldName": "metrics.score",
          "renameField": false,
          "outputFieldName": ""
        }
      ]
    },
    "options": {
      "mergeLists": true,
      "keepMissingAndNullValues": false
    }
  }
}
```

When aggregating user information from multiple sources:

```json
{
  "type": "aggregate",
  "parameters": {
    "mode": "individualFields",
    "fieldsToAggregate": {
      "fields": [
        {
          "inputFieldName": "firstName",
          "renameField": false,
          "outputFieldName": ""
        },
        {
          "inputFieldName": "lastName",
          "renameField": false,
          "outputFieldName": ""
        },
        {
          "inputFieldName": "contactInfo.email",
          "renameField": true,
          "outputFieldName": "emails"
        }
      ]
    },
    "putOutputInField": "userData",
    "options": {
      "keepMissingAndNullValues": false
    }
  }
}
```

When you need all data from each item preserved:

```json
{
  "type": "aggregate",
  "parameters": {
    "mode": "allItemData",
    "putOutputInField": "completeDataset",
    "include": "allFields",
    "options": {
      "includeBinaries": true,
      "keepMissingAndNullValues": true
    },
    "maxConcurrency": 5
  }
}
```

When working with nested arrays that need flattening:

```json
{
  "type": "aggregate",
  "parameters": {
    "mode": "individualFields",
    "fieldsToAggregate": {
      "fields": [
        {
          "inputFieldName": "tags",
          "renameField": true,
          "outputFieldName": "allTags"
        },
        {
          "inputFieldName": "categories",
          "renameField": false,
          "outputFieldName": ""
        }
      ]
    },
    "options": {
      "mergeLists": true,
      "keepMissingAndNullValues": false
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Collects multiple input items into a single output item, either by gathering specific fields into arrays or bundling all items together. Use when you need to consolidate results from a previous step before final output or further processing. Produces one item containing arrays or grouped data from all input items.