n8n Merge Node

Most workflows eventually hit a wall: data lives in separate paths but needs to come together. You fetch customer records from your CRM in one branch. Order history comes from your e-commerce platform in another. Both streams contain valuable information, but they flow separately through your workflow. Without a way to combine them, you cannot create that unified customer profile the business needs.

The Merge node solves this fundamental problem. It takes data from multiple input streams and combines them into a single output, giving you the unified dataset your downstream nodes require.

The Multi-Stream Problem

Workflows often branch for good reasons. You might run parallel API calls for speed. An If node splits data based on conditions. Different triggers feed into the same processing logic. But eventually, these separate streams need to reunite.

Without merging, you face awkward workarounds: duplicate nodes in each branch, complex expressions trying to reference data from other paths, or restructuring your entire workflow to avoid the branch in the first place.

What the Merge Node Actually Does

The Merge node waits for data from all connected inputs before executing. Once every input has delivered its items:

• Combines data streams using your chosen strategy
• Supports multiple modes for different merging scenarios
• Handles more than two inputs for complex workflows
• Provides SQL-like join operations for matching records by field values
• Preserves data integrity while combining separate sources

Think of it as a junction point where separate roads merge into one. Traffic from each road continues together down a single path.

What You’ll Learn

• When to use Merge versus Aggregate or other data nodes
• All four Merge modes and when each applies
• How to match records by field values like database joins
• SQL Query mode for complex matching logic
• Common mistakes that cause missing data or unexpected behavior
• Real-world patterns for CRM enrichment, API response combining, and more

When to Use the Merge Node

Before diving into configuration, understand when Merge is the right choice versus other data manipulation nodes.

Scenario	Best Choice	Why
Combine customer data with order data from different sources	Merge	Joining separate data streams
Stack items from two branches into one list	Merge (Append)	Simple concatenation of streams
Turn 50 separate items into one array	Aggregate	Collecting items within one stream
Compare two datasets to find differences	Compare Datasets	Finding what changed between versions
Calculate sum or count across items	Summarize	Mathematical aggregations
Wait for multiple branches before continuing	Merge (Choose Branch)	Synchronization without combining data

Rule of thumb: Use Merge when you have two or more separate data streams that need to become one. Use Aggregate when you have multiple items within a single stream that need to become an array. The key distinction is whether data comes from different workflow paths (Merge) or flows sequentially through one path (Aggregate).

Understanding Merge Modes

The Merge node offers four distinct modes. Choosing the right mode determines how your output data is structured.

Append Mode

Best for: Stacking all items from all inputs into a single sequential list.

Append takes every item from every input and outputs them one after another. No matching or combining happens. Items from Input 1 come first, followed by items from Input 2, and so on.

Example:

Input 1: [Customer A, Customer B]
Input 2: [Customer C, Customer D]
Output:  [Customer A, Customer B, Customer C, Customer D]

Use Append when you have similar data from multiple sources that should be treated as one collection. Perfect for combining results from parallel API calls or merging branches that processed different subsets of the same data type.

Combine Mode

Best for: Merging items from two inputs side-by-side based on a matching strategy.

Combine mode is where the real power lives. It offers three sub-modes for different matching needs:

• Matching Fields: Join records where specified fields match (like SQL joins)
• By Position: Combine the first item of Input 1 with the first item of Input 2, second with second, etc.
• All Possible Combinations: Create every possible pairing between inputs (Cartesian product)

Combine mode works with exactly two inputs. For more inputs, use Append mode or chain multiple Merge nodes.

SQL Query Mode

Best for: Complex matching logic using SQL syntax.

SQL Query mode lets you write custom queries against your input data. Inputs become tables named input1, input2, etc. You can write any valid AlaSQL query.

SELECT * FROM input1
LEFT JOIN input2 ON input1.customer_id = input2.customer_id
WHERE input1.status = 'active'

This mode shines when standard Combine options cannot express your matching logic. If you know SQL, this feels natural.

Choose Branch Mode

Best for: Synchronizing branches without actually combining data.

Choose Branch waits for all inputs to have data, then outputs only the data from one input that you specify. The other input’s data is discarded.

Use this when you need to ensure parallel processes complete before continuing, but only care about one branch’s output. Common in workflows where one branch fetches data while another performs a side effect like logging.

Mode Comparison Table

Mode	Inputs	Matching	Output
Append	2+	None	All items from all inputs, stacked
Combine	2	Fields, Position, or All	Merged items based on strategy
SQL Query	2+	Custom SQL	Query results
Choose Branch	2+	None	Items from selected input only

Combine Mode Deep Dive

Combine mode handles the most common merging scenario: joining two data streams based on some relationship. Understanding its options prevents the confusion that trips up many users.

Combine By: Matching Fields

This works like SQL joins. You specify which field from Input 1 should match which field from Input 2. When values match, those items get combined into a single output item containing fields from both inputs.

Configuration:

1. Set Mode to “Combine”
2. Set Combine By to “Matching Fields”
3. Enter Input 1 Field (e.g., customer_id)
4. Enter Input 2 Field (e.g., id)

When input1.customer_id equals input2.id, those items merge.

Output Type Options:

The Output Type setting controls which items appear in your output:

Output Type	SQL Equivalent	What It Does
Keep Matches	INNER JOIN	Only items that match in both inputs
Keep Non-Matches	Exclusive pairs	Only items that did NOT match
Keep Everything	FULL OUTER JOIN	All items, matched or not
Enrich Input 1	LEFT JOIN	All Input 1 items, with matching Input 2 data added
Enrich Input 2	RIGHT JOIN	All Input 2 items, with matching Input 1 data added

Example: Enriching customers with orders

Input 1 (Customers):

[
  { "customer_id": "C001", "name": "Alice" },
  { "customer_id": "C002", "name": "Bob" }
]

Input 2 (Orders):

[
  { "id": "C001", "order_total": 150 },
  { "id": "C003", "order_total": 200 }
]

With Enrich Input 1 and matching customer_id to id:

[
  { "customer_id": "C001", "name": "Alice", "order_total": 150 },
  { "customer_id": "C002", "name": "Bob" }
]

Alice gets her order data. Bob appears without order data (no match). Customer C003 does not appear (not in Input 1).

Combine By: Position

Position-based combining pairs items by their index. The first item from Input 1 combines with the first item from Input 2. The second with the second. And so on.

When to use:

• Both inputs have the same number of items in corresponding order
• You processed the same data in parallel and need to reunite it
• Order inherently matches between streams

Important: If inputs have different item counts, the output only contains as many items as the shorter input. Extra items from the longer input are discarded.

Combine By: All Possible Combinations

This creates a Cartesian product. Every item from Input 1 pairs with every item from Input 2.

Example:

Input 1: [A, B]
Input 2: [1, 2, 3]
Output:  [A-1, A-2, A-3, B-1, B-2, B-3]

Use this sparingly. With large inputs, the output explodes in size. 100 items times 100 items equals 10,000 output items.

Advanced Options

Fuzzy Compare: When enabled, n8n tolerates type differences when matching. The string "123" matches the number 123. Enable this when data comes from APIs with inconsistent typing.

Disable Dot Notation: Prevents n8n from interpreting dots in field names as nested property access. Enable this if your field names literally contain dots (like customer.id as a single field name, not a nested path).

Multiple Matches: Controls behavior when multiple items from Input 2 match a single item from Input 1.

• Include All Matches: Create multiple output items, one for each match
• Include First Match Only: Only combine with the first matching item

Your First Merge

Let’s build two practical examples step by step.

Example 1: Append Mode (Combining Lists)

Scenario: You have customers from two different CRM systems that need to be processed together.

Step 1: Set up two data sources in your workflow, both outputting customer records.

Step 2: Add the Merge node

1. Click + to add a node
2. Search for “Merge” (or “Join”)
3. Add it to your canvas

Step 3: Connect both sources

1. Connect CRM 1 output to the first input
2. Connect CRM 2 output to the second input

Step 4: Configure Append mode

1. Set Mode to “Append”
2. Leave other settings as default

Step 5: Test the node

1. Click Test step
2. View the output containing all customers from both sources

Example 2: Combine By Matching Fields

Scenario: Join user data from your database with activity logs from analytics.

Step 1: Set up your data sources

• Input 1: Database query returning users with user_id field
• Input 2: Analytics API returning activity with userId field

Step 2: Add and connect the Merge node

Step 3: Configure Combine mode

1. Set Mode to “Combine”
2. Set Combine By to “Matching Fields”
3. Input 1 Field: user_id
4. Input 2 Field: userId
5. Output Type: “Enrich Input 1” (keep all users, add matching activity)

Step 4: Enable Fuzzy Compare if needed

If your IDs might have type inconsistencies (string vs number), expand Options and enable Fuzzy Compare.

Step 5: Test and verify

Run the node. Each user should now have their activity data attached. Users without activity appear without those fields.

SQL Query Mode

For complex merging logic, SQL Query mode provides full control using familiar database syntax. The node uses AlaSQL, a JavaScript SQL database.

Basic Setup

1. Set Mode to “SQL Query”
2. Enter your SQL query in the Query field

Your input streams become tables named input1, input2, input3, etc. Each table contains the items from that input.

Common Query Patterns

LEFT JOIN (Enrich first input):

SELECT input1.*, input2.order_total, input2.order_date
FROM input1
LEFT JOIN input2 ON input1.customer_id = input2.customer_id

INNER JOIN with filtering:

SELECT *
FROM input1
INNER JOIN input2 ON input1.id = input2.user_id
WHERE input2.status = 'active'

UNION (Similar to Append but deduplicates):

SELECT * FROM input1
UNION
SELECT * FROM input2

Complex matching with multiple conditions:

SELECT *
FROM input1
LEFT JOIN input2
  ON input1.email = input2.email
  AND input1.company = input2.company_name

Field Name Considerations

SQL Query mode works best with simple field names. If your data has:

• Spaces in field names: Use bracket notation [Field Name]
• Special characters: Consider using an Edit Fields node to rename before merging
• Nested objects: Dot notation accesses nested properties, but complex structures may need flattening first

Error Handling

SQL syntax errors stop the workflow. Test your queries with small sample datasets first. The error message usually indicates the line and position of the syntax problem.

Multi-Input Workflows

Starting with n8n version 1.49.0, the Merge node supports more than two inputs. This simplifies workflows that need to combine data from many sources.

Adding More Inputs

1. Open the Merge node
2. Click the + button to add additional inputs
3. Connect your data sources to each input

Multi-Input with Append Mode

Append mode works seamlessly with multiple inputs. Items stack in order: all items from Input 1, then all from Input 2, then Input 3, and so on.

Input 1: [A, B]
Input 2: [C, D]
Input 3: [E, F]
Output:  [A, B, C, D, E, F]

Multi-Input with SQL Query Mode

SQL Query mode also supports multiple inputs. Each becomes an additional table:

SELECT * FROM input1
UNION ALL
SELECT * FROM input2
UNION ALL
SELECT * FROM input3

Or more complex joins:

SELECT input1.*, input2.score, input3.region
FROM input1
LEFT JOIN input2 ON input1.id = input2.user_id
LEFT JOIN input3 ON input1.country_code = input3.code

Important Notes

• Combine mode still only works with two inputs. For more, use Append or SQL Query.
• All inputs must provide data before the Merge node executes. One empty input stalls the entire node.
• The order of inputs matters for Append mode and for priority when fields overlap.

Common Mistakes and How to Fix Them

After reviewing hundreds of community forum posts, these mistakes cause the most confusion. Each includes the exact fix.

Mistake 1: Input 1 Takes Precedence in Combine Mode

Symptom: Output has fewer items than expected. Some Input 2 items seem to disappear.

Cause: When using Combine By Position, the output only contains as many items as the shorter input. If Input 1 has 5 items and Input 2 has 10, you get 5 output items.

Example:

Input 1: [A, B, C, D, E]     (5 items)
Input 2: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]  (10 items)
Output:  [A-1, B-2, C-3, D-4, E-5]  (5 items)

Fix:

• Use Matching Fields instead of Position if items should match by value
• Ensure inputs have equal item counts when using Position
• Switch to Append if you want all items regardless of count

Mistake 2: Merge After If Node Executes Both Branches

Symptom: Nodes in both the true and false branches of an If node execute, even though data only went one way.

Cause: The Merge node waits for input from all connected branches. This waiting behavior can trigger execution of nodes in branches that received no data.

Why this happens: n8n’s execution model tries to satisfy the Merge node’s requirement for all inputs. This can cause unexpected execution paths.

Fix Options:

1. Restructure the workflow: Avoid using Merge immediately after If nodes when possible
2. Use Choose Branch mode: If you only need one branch’s data anyway
3. Add a Filter node after Merge: Remove empty results
4. Check for empty inputs: Use an If node after Merge to handle cases where a branch had no data

This is also documented in the If node troubleshooting section.

Mistake 3: Matching Fields With Spaces or Special Characters

Symptom: Matching fields finds no matches, even though data appears identical.

Cause: Field names with spaces, dots, or special characters can confuse the matching logic.

Example:

// Input 1
{ "Customer ID": "123" }

// Input 2
{ "customer_id": "123" }

These look similar but Customer ID (with space) does not equal customer_id (with underscore).

Fix:

• Use Edit Fields node to rename fields before merging
• Enable Disable Dot Notation if field names contain literal dots
• Standardize field naming across your data sources

Mistake 4: Combine By Position Losing Data

Symptom: Some items from the longer input disappear.

Cause: Position-based combining only outputs items up to the length of the shorter input.

Fix:

• Verify both inputs have equal item counts
• Use Matching Fields if items should match by value, not position
• Pre-filter or pad inputs to ensure equal lengths

Mistake 5: Fuzzy Compare Disabled Causing Type Mismatches

Symptom: Fields that should match do not match. Matching returns empty results.

Cause: One input has customer_id: "123" (string) while the other has customer_id: 123 (number). With strict comparison, these are different values.

Example:

// Input 1 - ID is a string
{ "id": "456" }

// Input 2 - ID is a number
{ "id": 456 }

Fix:

1. Expand Options in the Merge node
2. Enable Fuzzy Compare

This tells n8n to treat "456" and 456 as matching values.

Mistake 6: Empty Inputs Causing Workflow to Halt

Symptom: The Merge node never executes. Workflow seems stuck.

Cause: Merge waits for all inputs to have data. If one branch produces no items, Merge waits indefinitely.

Example scenario:

Webhook → If node → True branch (has data) → Merge
                  → False branch (no data) → Merge

If the condition is always true, false branch never sends data to Merge.

Fix Options:

1. Restructure workflow: Ensure all paths leading to Merge will have data
2. Add default items: Use a Set node to create placeholder items when a branch would otherwise be empty
3. Use Choose Branch mode: If you only need one branch’s data
4. Split into separate workflows: If branches are truly independent

Merge vs Aggregate: The Critical Difference

This comparison causes the most confusion. Understanding the difference saves hours of debugging.

Visual Comparison

Merge: Combines separate streams

Stream A ──┬─► [Merge] ─► Combined items from both streams
Stream B ──┘

Data flows through different paths in your workflow and needs to join together.

Aggregate: Collects items within one stream

Item 1 ─┐
Item 2 ─┼─► [Aggregate] ─► Single item containing array of all
Item 3 ─┘

Multiple items flow sequentially through the same path and need to become an array.

When to Choose Each

You Have…	You Need…	Use
Two API calls running in parallel	Combined results	Merge
If node splitting into branches	Data from both branches	Merge
50 items from a loop	One item with an array	Aggregate
Paginated API responses in sequence	All pages in one array	Aggregate
Customer data + Order data from different nodes	Joined customer-order records	Merge
100 emails to send in one batch	Single batch request payload	Aggregate

Quick Test

Ask yourself: “Is the data coming from different workflow paths, or the same path?”

• Different paths (branches, parallel execution) → Merge
• Same path (sequential items) → Aggregate

For detailed Aggregate patterns, see the Aggregate node guide.

Real-World Examples

Example 1: Joining CRM Contacts With Order Data

Scenario: Your CRM has customer profiles. Your e-commerce platform has order history. You need unified records showing each customer with their purchase total.

Workflow Structure:

[CRM API] ────────────────┬─► [Merge] ─► [Edit Fields] ─► [Google Sheets]
                          │
[E-commerce API] ─────────┘

Merge Configuration:

• Mode: Combine
• Combine By: Matching Fields
• Input 1 Field: email
• Input 2 Field: customer_email
• Output Type: Enrich Input 1

Result: Every CRM contact has their order data attached. Contacts without orders still appear (for follow-up targeting).

Example 2: Combining API Responses From Parallel Requests

Scenario: You need data from three different API endpoints. Running them in parallel saves time, but you need all results together for the next step.

Workflow Structure:

[Webhook] ─┬─► [API 1] ─┬─► [Merge] ─► [Process Data]
           ├─► [API 2] ─┤
           └─► [API 3] ─┘

Merge Configuration:

• Mode: Append
• Inputs: 3

Result: All API responses stack into one stream for unified processing.

Example 3: Enriching Leads With Company Information

Scenario: Your form captures lead emails. You need to enrich each lead with company data from a clearbit-style API before sending to your CRM.

Workflow Structure:

[Form Trigger] ─► [Split in Batches] ─► [Company Lookup API] ─┐
                         ▲                                     │
                         └─────────────────────────────────────┘
                                          │ (done)
                                    [Merge] ←── [Original Leads]
                                          │
                                    [CRM Create]

Merge Configuration:

• Mode: Combine
• Combine By: Matching Fields
• Input 1 Field: email
• Input 2 Field: lookup_email
• Output Type: Keep Matches

Result: Each lead record now includes company name, size, industry from the lookup.

Example 4: Merging Paginated Results With Metadata

Scenario: An API returns paginated results. You need all pages combined, plus metadata from the first response.

Workflow Structure:

[HTTP Request] ─► [Extract Metadata] ─────────┬─► [Merge] ─► [Output]
       │                                       │
       └─► [Loop for Pages] ─► [Aggregate] ───┘

Merge Configuration:

• Mode: Combine
• Combine By: All Possible Combinations (since metadata is one item)

Result: Every item has the metadata attached (total count, query info, etc.).

Example 5: Using SQL Query for Complex Matching

Scenario: Match records where either email OR phone number matches, and only for active users.

Merge Configuration:

• Mode: SQL Query

SELECT input1.*, input2.activity_score
FROM input1
LEFT JOIN input2
  ON (input1.email = input2.email OR input1.phone = input2.phone)
WHERE input1.status = 'active'
  AND input2.activity_score > 50

Result: Active users matched by email OR phone, with activity score above 50.

Pro Tips and Best Practices

1. Name Your Merge Nodes Descriptively

Instead of “Merge” or “Merge1”, use names that describe the operation:

• “Join Customers + Orders”
• “Combine API Responses”
• “Merge CRM Data”

This makes complex workflows self-documenting and debugging much easier.

2. Test With Small Datasets First

Before merging thousands of items, test with 3-5 from each input. Verify:

• Matching works correctly
• Output structure is as expected
• No unexpected data loss

Large merges can be slow and hard to debug. Get the logic right with small samples first.

3. Enable Fuzzy Compare for External API Data

APIs often have inconsistent typing. IDs might be strings in one system and numbers in another. Dates might be formatted differently. Enable Fuzzy Compare by default when working with external data, then disable it only if you specifically need strict matching.

4. Handle Empty Inputs Gracefully

Design your workflow to handle cases where one input might be empty:

• Add conditional logic before Merge to check for empty results
• Use Choose Branch mode if one branch might have no data
• Consider whether Merge is needed at all if one input is optional

5. Consider Workflow Structure With If Nodes

When using If nodes before Merge, understand that both branches may execute due to Merge’s waiting behavior. If this causes problems:

• Restructure to avoid Merge after If when possible
• Use Filter instead of If when you only need one path
• Add a second If or Filter after Merge to handle edge cases

6. Use Edit Fields Before Complex Merges

Clean and standardize your data before merging:

• Rename fields to consistent names across inputs
• Extract nested values to top-level fields
• Remove unnecessary fields to reduce confusion

The Edit Fields node is your friend for pre-merge data preparation.

7. Document Complex SQL Queries

When using SQL Query mode with complex logic, add a sticky note in n8n explaining:

• What the query accomplishes
• Why standard Combine options were not sufficient
• Any assumptions about input data structure

Our workflow development services can help design robust merge patterns for complex business requirements. For strategic guidance on workflow architecture, explore our consulting services.

Frequently Asked Questions

Why is Merge only outputting items from Input 1 and ignoring Input 2?

This typically happens with Combine By Position mode when inputs have different item counts. The Merge node only produces as many output items as the shorter input has items. If Input 1 has 5 items and Input 2 has 100 items, you get only 5 output items. To fix this, either switch to Matching Fields mode if items should match by value rather than position, use Append mode if you want all items from both inputs regardless of matching, or ensure both inputs have equal item counts before merging. Check the input panel of the Merge node to verify how many items each input actually received. Sometimes upstream nodes filter more than expected.

How do I combine data from more than two branches in n8n?

For workflows with three or more branches needing to merge, you have several options. First, if using n8n version 1.49.0 or later, the Merge node supports multiple inputs. Open the node, click the + button to add inputs, and connect each branch. Set Mode to Append for simple stacking or SQL Query for complex joining. Second, for older versions, chain multiple Merge nodes: connect branches 1 and 2 to the first Merge, then connect that output and branch 3 to a second Merge. Third, consider whether your workflow design could be simplified. Sometimes multiple branches indicate a pattern that a single loop with conditional logic inside would handle better. Check our workflow best practices guide for architectural patterns.

What is the difference between Merge and Aggregate in n8n?

Merge combines data from separate workflow paths into one stream. Aggregate takes multiple items flowing through a single path and collects them into one item with an array. The key question: is your data coming from different branches (use Merge) or flowing sequentially through one path (use Aggregate)? For example, if you have an If node that splits data and you need both branches later, use Merge. If you have 50 customers from a database query and need to send them as a single batch to an API, use Aggregate. Another way to think about it: Merge is horizontal (side-by-side streams becoming one), Aggregate is vertical (stacking sequential items into an array).

Why are both my If node branches executing when I add a Merge node downstream?

This is expected behavior due to how n8n’s execution model works. The Merge node waits for input from all connected branches before executing. This waiting can trigger execution of nodes in branches that would otherwise not run because the If node did not route data there. It is not a bug but rather a consequence of Merge needing to satisfy all its inputs. To work around this, consider restructuring your workflow to avoid Merge immediately after If nodes, use Choose Branch mode if you only need one branch’s data anyway, add a Filter node after Merge to remove empty results, or split truly independent branches into separate workflows triggered by the main one.

Can I use SQL queries to join data in the Merge node?

Yes. Set the Mode to SQL Query and write your query in the Query field. Input streams become tables named input1, input2, input3, etc. The node uses AlaSQL, a JavaScript SQL engine that supports standard SQL syntax including SELECT, JOIN, WHERE, GROUP BY, UNION, and more. Common patterns include LEFT JOIN for enriching one dataset with another, INNER JOIN for finding matches only, and UNION for combining similar datasets. SQL Query mode is powerful when standard Combine options cannot express your matching logic, such as matching on multiple fields with OR conditions or filtering during the join. Test your queries with small datasets first, as syntax errors stop the workflow.