n8n Merge node: every mode with examples

The n8n Merge node brings two or more data streams back together. You use it after branches split by an If or Switch node, and to join data fetched by different nodes, for example customers from a CRM and invoices from a billing API. It waits until data from all inputs is available, then combines it according to the Mode you pick.

The four modes

Mode	What it does	Comparable to
Append	Outputs all items of input 1, then input 2, and so on	UNION ALL / array concat
Combine	Merges items from two inputs into one item each	JOIN
SQL Query	Runs a SQL query over the inputs as tables	AlaSQL
Choose Branch	Outputs the data of one input unchanged, after all inputs arrive	A barrier

Since n8n 1.49.0 the node supports more than two inputs (Number of Inputs) and the SQL Query mode (Merge docs).

Append

Keeps every item from every input, one input after another. Use it to collect results from branches into one list, for example after a Switch node where each route enriched its items differently and the next step treats them all the same.

Combine

Combine joins items from two inputs. Combine By sets the method.

Matching Fields

Enter the field to match on in each input (they can have different names, such as id and customerId). Output Type sets the join type:

Output Type	Keeps	SQL analogy
Keep Matches	Only items present in both	Inner join
Keep Non-Matches	Only items without a match	Anti-join
Keep Everything	Matches plus unmatched from both	Full outer join
Enrich Input 1	All of input 1, plus matching data from input 2	Left join
Enrich Input 2	All of input 2, plus matching data from input 1	Right join

Example: Input 1 has orders with customerId, Input 2 has customers with id. Combine by Matching Fields, customerId = id, Output Type Enrich Input 1: every order keeps its fields and gains the customer's fields. Orders without a customer stay in the output.

Options for matching:

• Fuzzy Compare treats "3" and 3 as equal. Turn it on when one API returns IDs as strings.
• Multiple Matches: Include All Matches (one output item per match) or Include First Match Only.
• Disable Dot Notation stops parent.child from being read as a nested path.

Position

Item 0 of input 1 merges with item 0 of input 2, item 1 with item 1, and so on. Unpaired items are dropped unless you turn on Include Any Unpaired Items. Use it only when both inputs are guaranteed to be in the same order, for example two nodes that processed the same list.

All Possible Combinations

Every item of input 1 combined with every item of input 2 (a cross join). Three people and two greetings give six items. Useful for generating variants, dangerous on large inputs.

Clash handling

When both items have a field with the same name, Input 2 wins by default. Options > Clash Handling lets you prefer input 1, or Always Add Input Number to Field Names to keep both values. For nested objects choose Deep Merge (merge at every level) or Shallow Merge (top level only).

SQL Query

Each input is a table named input1, input2, input3:

SELECT o.id, o.total, c.email
FROM input1 o
LEFT JOIN input2 c ON o.customerId = c.id
WHERE o.total > ?

Pass values through Options > Query Parameters, for example {{ [100] }}, rather than building SQL strings with expressions. The engine is AlaSQL, so check its supported statements for anything unusual. From n8n 1.95.0 (Merge node version 3.2), Empty Query Result decides whether a query with no rows outputs nothing or a single { "success": true } item.

SQL mode is the quickest way to express a join with filters and computed columns that would otherwise need a Combine node plus a Code node.

Choose Branch

Waits for all inputs, then outputs Input 1 Data, Input 2 Data, or A Single, Empty Item. The data passes through unchanged. Use it as a synchronization point: "continue with the order data, but only after the Slack notification branch is done".

Things that trip people up

• Uneven item counts. The docs note that input 1 takes precedence: with 5 items on input 1 and 10 on input 2, only five are processed. Put the "main" list on input 1.
• A branch that gets no items. After an If or Switch node, only branches that received items run. Test the Merge node with data that leaves one branch empty, and check the output is what you expect.
• Legacy execution order. Workflows on the v0 execution order (built before n8n 1.0) could run both branches of an If node when a Merge followed it. Check Workflow Settings > Execution Order on old imported workflows (execution order).
• Merging runs of the same node. The Merge node combines different inputs. To combine results from multiple runs of one node, for example inside a loop, use the done output of Loop Over Items or a Code node with $('Node').all(0, runIndex).

Merge vs Compare Datasets vs Code

Need	Node
Join two lists by key	Merge, Combine by Matching Fields
Know which records are new, changed, removed	Compare Datasets (up to four outputs)
Union of branch results	Merge, Append
Join with filters and computed fields	Merge, SQL Query
Anything with custom matching logic	Code node

From Pipedream Parallel

Pipedream's Parallel operator runs all matching branches; steps after the block can read the results of each. In n8n the equivalent is several connections out of one node (or a Switch node with "Send data to all matching outputs") and a Merge node where the branches meet. Choose Append if the next steps should process each branch's result as separate items, Combine by Position if each branch produced one item and you want them as one, and Choose Branch if you only need to wait.

Our converter rebuilds parallel paths with a Merge node where it can, and flags every workflow that has branches for manual review in the report, because branch logic isn't something to trust to automatic conversion. Get the report for your project in the converter. The report and 1 workflow are free. Full export: $3 per workflow, $19 minimum — coming soon. Mapping of all Pipedream operators: Pipedream control flow to n8n. Code steps that merge data by hand can be checked with the code step checker.

Not affiliated with Pipedream or n8n.