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

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

# Aggregate Binary

> Collect binary data from multiple items into a single output item

## Overview

The Aggregate Binary tool reads binary data from N input items and produces a single output item containing all binary properties merged together. Each input item's binary data is re-stored under a new property name based on the chosen naming mode (indexed, originalFileName, or inputFieldName). The output item includes a metadata array listing all collected files with their property names, original file names, MIME types, and sizes. No external API or credentials are required — this is a pure data transformation tool.

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

**Appearance:** Icon: `aggregate` | Color: `#7722CC`

## Node Type

**Action (Binary)** — handles file/binary data operations

## Input / Output

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

## Credentials

This tool does not require any credentials.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Binary Property | `string` | No | `data` | Name of the binary property to read from each input item. Items without this binary property are silently skipped. Names are case-sensitive — see the upstream node's Binary Data panel for the exact names to use. |
| Output Property Prefix | `string` | No | `file` | Prefix used for naming output binary properties in "indexed" naming mode. Each property will be named {prefix}_0, {prefix}_1, etc. _(shown when Naming Mode is `indexed`)_ |
| Naming Mode | `options` | No | `indexed` | How to name each binary property in the output item. |
| | | | | Options: `indexed` (name properties as {prefix}_0, {prefix}_1, etc.), `originalFileName` (use the original file name from binary metadata, sanitized and deduplicated), `inputFieldName` (use a value from a JSON field on each input item as the property name) |
| Name Source Field | `string` | No | `name` | JSON field on each input item to use as the binary property name. The value is sanitized (non-alphanumeric characters replaced with underscores). _(shown when Naming Mode is `inputFieldName`)_ |
| Include Metadata Array | `boolean` | No | `true` | Whether to include a metadata array in the output JSON listing all collected files with their property names, file names, MIME types, and sizes. |
| Metadata Field Name | `string` | No | `files` | Name of the metadata array field in the output JSON. _(shown when Include Metadata Array is `true`)_ |
| Max Concurrency | `number` | No | `10` | Maximum number of input items to hydrate concurrently from the store. |

## Output Data

Every input item is collapsed into **one** output item on the main port. That item carries all of the collected binary properties together, named according to Naming Mode. The input JSON does not pass through — the output JSON contains only the fields listed below.

```json
{
  "files": [
    {
      "index": 0,
      "propertyName": "file_0",
      "fileName": "invoice.pdf",
      "mimeType": "application/pdf",
      "fileSize": 48213,
      "sourcePointer": "..."
    }
  ],
  "totalFiles": 1
}
```

- `totalFiles` is always present and counts the binaries that were actually collected.
- The metadata array is written under the name given by Metadata Field Name (`files` by default) and is present only when Include Metadata Array is on. Each entry describes one collected file; `sourcePointer` is an internal reference to the input item it came from.
- Input items that do not carry the named Binary Property are skipped silently — they produce no metadata entry and are not counted in `totalFiles`.
- In `originalFileName` and `inputFieldName` modes, names are sanitized and duplicates get a numeric suffix (`report`, `report_1`, `report_2`), so no file is lost to a name collision.

Reference a collected file downstream by its property name, and the metadata by expression, e.g. `{{ $json.files[0].fileName }}`.

## Usage Examples

- Aggregate downloaded files into a single item for email attachment
- Merge binary outputs from parallel branches
- Collect images from multiple API responses into one item
- Combine PDF files from multiple sources before compression
- Gather attachments for a multi-file upload

## Example Configuration

Collects all `data` binary properties and names them `file_0`, `file_1`, etc. Includes a metadata array under `aggregated_files`:

```json
{
  "type": "aggregate_binary",
  "parameters": {
    "binaryPropertyName": "data",
    "namingMode": "indexed",
    "outputPropertyPrefix": "file",
    "includeMetadataArray": true,
    "metadataFieldName": "aggregated_files",
    "maxConcurrency": 10
  }
}
```

Uses the original file name stored in each binary item's metadata (sanitized and deduplicated) as the property name:

```json
{
  "type": "aggregate_binary",
  "parameters": {
    "binaryPropertyName": "data",
    "namingMode": "originalFileName",
    "includeMetadataArray": true,
    "metadataFieldName": "file_index",
    "maxConcurrency": 5
  }
}
```

Each input item has a JSON field (e.g. `reportId`) whose value becomes the binary property name in the output:

```json
{
  "type": "aggregate_binary",
  "parameters": {
    "binaryPropertyName": "attachment",
    "namingMode": "inputFieldName",
    "nameSourceField": "reportId",
    "includeMetadataArray": true,
    "metadataFieldName": "reports_metadata",
    "maxConcurrency": 8
  }
}
```

Collects binaries without producing a metadata array in the output JSON. Metadata Field Name is omitted because Include Metadata Array is off:

```json
{
  "type": "aggregate_binary",
  "parameters": {
    "binaryPropertyName": "data",
    "namingMode": "indexed",
    "outputPropertyPrefix": "asset",
    "includeMetadataArray": false,
    "maxConcurrency": 10
  }
}
```

Minimal configuration — reads from `data`, uses indexed naming with the default `file` prefix, writes the metadata array to `files`, concurrency of 10. Set Output Property Prefix only when you want a prefix other than `file`:

```json
{
  "type": "aggregate_binary",
  "parameters": {
    "namingMode": "indexed"
  }
}
```

When a previous node downloads multiple files, aggregate them into one item before passing to a compression or upload node:

```json
{
  "type": "aggregate_binary",
  "parameters": {
    "binaryPropertyName": "data",
    "namingMode": "originalFileName",
    "includeMetadataArray": true,
    "metadataFieldName": "file_list",
    "maxConcurrency": 10
  }
}
```

Each input item carries a `jobId` field and a PDF binary under `report`. Aggregate all PDFs, naming each by its job ID:

```json
{
  "type": "aggregate_binary",
  "parameters": {
    "binaryPropertyName": "report",
    "namingMode": "inputFieldName",
    "nameSourceField": "jobId",
    "includeMetadataArray": true,
    "metadataFieldName": "reports",
    "maxConcurrency": 4
  }
}
```

When processing many images in a pipeline where metadata is not needed downstream, disable the metadata array to reduce output size:

```json
{
  "type": "aggregate_binary",
  "parameters": {
    "binaryPropertyName": "image",
    "namingMode": "indexed",
    "outputPropertyPrefix": "img",
    "includeMetadataArray": false,
    "maxConcurrency": 20
  }
}
```

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

Aggregate Binary collects binary data from multiple input items and merges them into a single output item with distinctly named binary properties. Use it when a workflow produces several binary files across separate items and a downstream node requires all files consolidated under one item. The output item contains merged binary properties named by index, original file name, or input field name, plus a metadata array detailing each file with its property name, MIME type, and size.