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:

{
  "_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:

{
  "parameters": {
    "mode": "append"
  }
}

Combine by fields — inner join:

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

Combine by fields — left join with fuzzy matching:

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

Combine by position — full outer join:

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

All combinations:

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

Nested field matching:

{
  "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:

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

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

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

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

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

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

{
  "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.