Merging Data with the Merge Node

Hello! Welcome back to our course on n8n.

In our last lesson, we explored the Split In Batches node, which is essential for processing large datasets in manageable groups. A key takeaway was that when you use conditional logic (like an If node) inside a loop, you must use a Merge node to bring the separate paths back together. That was our first glimpse into the power of merging.

Today, we're going to put that node under the microscope. This lesson is dedicated to fulfilling the learning outcome: Merge data from different branches using the Merge node. You'll learn how to combine data from separate processing streams, a fundamental technique for building sophisticated workflows. This is crucial for tasks like enriching data from multiple sources or consolidating the results of parallel operations.

Given your software development background, you can think of the Merge node as n8n's way of performing operations analogous to SQL's UNION and JOIN clauses. We'll cover the different modes it offers and when to use each one.

1. Why and When to Merge Data

In n8n, it's common to split your workflow into multiple branches to perform different tasks in parallel. For example, you might:

• Fetch user data from your database in one branch.
• Fetch that user's recent activity from a separate analytics API in another branch.

At some point, you'll want to combine this information. This is where the Merge node comes in. It's designed to accept inputs from multiple branches, wait for all of them to complete their processing, and then combine their output items according to a specific set of rules.

The Merge node is one of n8n's logic nodes, designed to control the flow and structure of your data.

The Merge node operates in several modes, but the two most important are Append and Combine. Let's explore them in detail.

2. The Append Mode: Stacking Data

The Append mode is the most straightforward. It takes all the items from its inputs and stacks them on top of each other into a single, longer list. If input 1 has 3 items and input 2 has 5 items, the Append mode will output a single list containing 8 items. This is conceptually similar to a UNION ALL in SQL.

To see this in action, the following video provides a clear walkthrough.

A Critical Best Practice: Normalizing Data

The Append mode works perfectly if the items from all branches have the same data structure (or "schema"). But what happens if they don't?

Imagine you're merging customer data from two sources:

• Branch 1 outputs items with fields: name, email
• Branch 2 outputs items with fields: customerName, customerEmail

If you append these directly, you'll get a messy list where some items have name and email (and customerName/customerEmail are undefined), and others have the reverse. This makes it impossible to process them consistently in later nodes.

The solution is to use a Set node (also known as "Edit Fields") in each branch before the Merge node to standardize the field names.

This next video brilliantly demonstrates this exact problem and its solution. It's a crucial pattern for creating clean, maintainable workflows.

Test your understanding!

You are building a workflow that pulls product information from two different e-commerce platforms.

• Branch A (Shopify) outputs items with fields title and price.
• Branch B (WooCommerce) outputs items with fields name and cost.

You want to use the Append mode in a Merge node to create a single list of all products. What must you do to ensure the final list is clean and usable?

Show answer

Before the Merge node, you need to add a Set node to each branch to normalize the field names.

• In Branch A, you could use a Set node to create new fields: productName (from title) and productPrice (from price).
• In Branch B, you would use another Set node to create the same new fields: productName (from name) and productPrice (from cost).

This ensures that all items entering the Merge node have an identical structure, resulting in a clean, combined list.

3. The Combine Mode: Enriching Data

While Append stacks data vertically, the Combine mode joins it horizontally. It's used to enrich items from one branch with data from another, much like an SQL JOIN. This mode has several powerful sub-options.

Combine by Position

This is the simplest Combine method. It merges items based on their index (order) in the input stream. The first item from input 1 is merged with the first item from input 2, the second with the second, and so on. This is useful when you have two parallel streams of data that you know are perfectly correlated by their order.

Combine by Matching Fields

This is the most powerful and commonly used Combine method. It acts like a database JOIN, merging items that share a common value in a specified field (a "key"). For example, you could merge user profile data with user activity data by matching both on a userID field.

To solidify this concept, let's walk through building a simple example yourself.

This hands-on exercise demonstrates how you can enrich one dataset (names) with related information from another (greetings) using a shared key (language). The article also shows a more complex, real-world example of fetching users, filtering them, fetching their posts, and then merging the user and post data together.

Combine by All Possible Combinations

This mode creates a Cartesian product of the inputs. It pairs every item from input 1 with every item from input 2. If you have 3 items in the first branch and 4 in the second, you'll get 12 (3 * 4) combined items. Use this mode with caution, as it can generate a massive number of items very quickly.

4. Other Merge Modes

The Merge node has a couple of other modes that are less common but good to be aware of.

• Choose Branch: This mode waits for all inputs to arrive, then outputs the data from only one of the branches, which you select in the node's parameters. It's a simple way to conditionally route data after parallel processing.
• SQL Query: This advanced mode allows you to write an SQL-like query to merge the inputs, treating input1 and input2 as table names. With your development background, you might find this an intuitive way to perform complex joins directly.

The video below gives a quick overview of these two options.

Conclusion

Mastering the Merge node is a significant step toward building complex, multi-path workflows. You now have the tools to bring together data from various sources and processing branches in a controlled and predictable way.

Key Takeaways:

• The Merge node is used to combine data from two or more separate branches in a workflow.
• Append mode stacks items from all inputs into a single, longer list (like a UNION ALL). It's crucial to normalize data with a Set node before appending if schemas differ.
• Combine mode merges items horizontally to enrich data (like a JOIN).
  • By Position: Merges items based on their order.
  • By Matching Fields: Merges items based on a shared key, which is the most powerful and common method for data enrichment.
• Use All Possible Combinations with caution, as it can rapidly increase the number of items.

In our next lesson, we'll look at a different type of advanced flow control: implementing a manual approval step using the Wait node with a webhook resume URL. This will introduce the concept of "human-in-the-loop" automations, where a workflow can pause and wait for external input before continuing.