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

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

# Merge

> Combine multiple input streams

## Overview

Combines multiple data streams into a single output. Used to unify diverged branches or enrich data by joining results from different sources.

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

**Appearance:** Icon: `merge` | Color: `#14b8a6`

## Node Type

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

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input 1`, `Input 2`, `Input 3`, `Input 4`, `Input 5` |
| Output | `Output`, `Error` |

Merge is the one node with a variable number of inputs: it accepts up to five, and only the inputs your workflow connects contribute items. `Input 1` is the primary stream — it is the side that Merge Fields matches from, and the one Enrich Input 1 keeps.

## Credentials

This tool does not require any credentials.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Mode | `options` | Yes | `append` | How to merge the input streams. Append stacks all items. Combine pairs items based on sub-mode. |
| | | | | Options: `append`, `combine` |
| Combine Mode | `options` | No | `mergeByFields` | Sub-mode for Combine. Only used when Mode is 'Combine'. _(shown when Mode is `combine`)_ |
| | | | | Options: `mergeByFields` (merge by fields — match on a key), `mergeByPosition` (merge by position), `allCombinations` (all possible combinations) |
| Merge Fields | `string` | No | `id` | Field name(s) to match on when using 'Merge by Fields'. Use comma-separated values for different fields per input (e.g., 'userId,customerId'). Supports dot notation for nested fields (e.g., 'user.id'). _(shown when Mode is `combine` and Combine Mode is `mergeByFields`)_ |
| Output Type | `options` | No | `keepMatches` | Join logic for matching modes. Determines which items to include in output. _(shown when Mode is `combine` and Combine Mode is `mergeByFields`, `mergeByPosition`)_ |
| | | | | Options: `keepMatches` (inner join), `enrichInput1` (left join), `keepEverything` (full outer join) |
| Clash Handling | `options` | No | `preferInput1` | How to handle conflicts when the same field exists in multiple inputs. _(shown when Mode is `combine`)_ |
| | | | | Options: `preferInput1`, `preferInput2` (prefer input 2 / later input), `preferLater`, `addSuffix` |
| Fuzzy Compare | `boolean` | No | `false` | If enabled, treats similar values as matches (e.g., string '3' matches number 3). _(shown when Mode is `combine` and Combine Mode is `mergeByFields`)_ |
| Multiple Matches | `boolean` | No | `false` | If enabled, includes all matching items. If disabled, only the first match is used. _(shown when Mode is `combine` and Combine Mode is `mergeByFields`)_ |
| Max Concurrency | `number` | No | `100` | Maximum items to process concurrently when writing output. |

## Output Data

All results leave through the single `Output` port. How many items you get depends on Mode:

| Mode | Items produced |
|------|----------------|
| `append` | Every item from every connected input, one output item each, in input order |
| `combine` + `mergeByFields` | One output item per matched pair; Output Type decides what happens to items with no match |
| `combine` + `mergeByPosition` | The items at position 1 are merged together, then position 2, and so on |
| `combine` + `allCombinations` | Every item of the first input merged with every item of the next — the item count multiplies |

Merged items combine the JSON of their sources, and their binary properties are combined as well; when the same binary property name exists on both sides, the later input's wins. Every output item carries `_mergeInfo`:

```json
{
  "_mergeInfo": {
    "mode": "combine",
    "combineMode": "mergeByFields",
    "mergedAt": 1765432100000,
    "sourceInputCount": 2
  }
}
```

- `combineMode` is present only when Mode is `combine`. `sourceInputCount` is the number of inputs the node received.
- **Clash Handling** decides which value survives when the same key exists in more than one item: `preferInput1` keeps the earlier value, `preferInput2` and `preferLater` take the later one, and `addSuffix` keeps the earlier value under the original key and stores the other under `{field}_input2`.
- **Keep Everything** also appends the items from the other inputs that matched nothing, unchanged.
- With **Multiple Matches** off, only the first matching item from each input is used; with it on, you get one output item per combination of matches, so a key that appears three times on one side produces three items.
- With error handling set to **continue** (the default), errored input items are written to `Output` ahead of the merged items, each carrying an `_error` object.

## Usage Examples

- merge the two branches back together
- combine results from parallel processing
- join the API response with database data
- unify outputs from different sources
- converge parallel workflows

## Example Configuration

Basic append mode:

```json
{
  "parameters": {
    "mode": "append"
  }
}
```

Combine by fields — inner join:

```json
{
  "parameters": {
    "mode": "combine",
    "combineMode": "mergeByFields",
    "mergeFields": "id",
    "outputType": "keepMatches",
    "clashHandling": "preferInput2"
  }
}
```

Combine by fields — left join with fuzzy matching:

```json
{
  "parameters": {
    "mode": "combine",
    "combineMode": "mergeByFields",
    "mergeFields": "userId,customerId",
    "outputType": "enrichInput1",
    "clashHandling": "addSuffix",
    "fuzzyCompare": true,
    "multipleMatches": true
  }
}
```

Combine by position — full outer join:

```json
{
  "parameters": {
    "mode": "combine",
    "combineMode": "mergeByPosition",
    "outputType": "keepEverything",
    "clashHandling": "preferInput1"
  }
}
```

All combinations:

```json
{
  "parameters": {
    "mode": "combine",
    "combineMode": "allCombinations",
    "clashHandling": "preferLater"
  }
}
```

Nested field matching:

```json
{
  "parameters": {
    "mode": "combine",
    "combineMode": "mergeByFields",
    "mergeFields": "user.id,profile.email",
    "outputType": "keepMatches",
    "clashHandling": "preferInput2",
    "fuzzyCompare": false,
    "multipleMatches": false
  }
}
```

Data enrichment (left join pattern). Used to enrich primary data with additional information:

```json
{
  "parameters": {
    "mode": "combine",
    "combineMode": "mergeByFields",
    "mergeFields": "id",
    "outputType": "enrichInput1",
    "clashHandling": "preferInput2"
  }
}
```

Data deduplication (inner join pattern). Used to find matching records between datasets:

```json
{
  "parameters": {
    "mode": "combine",
    "combineMode": "mergeByFields",
    "mergeFields": "email",
    "outputType": "keepMatches",
    "clashHandling": "preferInput1",
    "fuzzyCompare": true
  }
}
```

Sequential data merging. Used to combine data streams in order:

```json
{
  "parameters": {
    "mode": "combine",
    "combineMode": "mergeByPosition",
    "outputType": "keepEverything",
    "clashHandling": "addSuffix"
  }
}
```

Simple data stacking. Used to combine all data into one stream:

```json
{
  "parameters": {
    "mode": "append",
    "maxConcurrency": 50
  }
}
```

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

Combines items from two or more input datasets into a single output using append, combine-by-position, or combine-by-field matching. Use when you need to join or concatenate data from separate tool outputs. Produces a unified dataset with items from all inputs merged according to the selected mode.