Skip to content

Merge#

Use the Merge node to combine data from two streams, once data of both streams is available.

Major changes in 0.194.0

This node was overhauled in Ensemble 0.194.0. This document reflects the latest version of the node. If you're using an older version of Ensemble, you can find the previous version of this document here.

Merge mode#

You can specify how the Merge node should combine data from different branches. The following options are available:

Append#

Keep data from both inputs. The output contains items from Input 1, followed by all items from Input 2.

Combine#

Combine data from both inputs. Choose a Combination Mode to control how Ensemble merges the data.

Merge by fields#

Compare items by field values. Enter the fields you want to compare in Fields to Match.

Ensemble's default behavior is to keep matching items. You can change this using the Output Type setting:

  • Keep matches: merge items that match.
  • Keep non-matches: merge items that don't match.
  • Enrich Input 1: keep all data from Input 1, and add matching data from Input 2.
  • Enrich Input 2: keep all data from Input 2, and add matching data from Input 1.
Field value clashes#

If both items at an index have a field with the same name, this is a clash. For example, if all items in both Input 1 and Input 2 have a field named language, these fields clash. By default, Ensemble prioritizes Input 2, meaning if language has a value in Input 2, Ensemble uses that value when merging the items.

You can change this behavior:

  1. Select Add Option > Clash Handling.
  2. Choose which input to prioritize, or choose Always Add Input Number to Field Names to keep all fields and values, with the input number appended to the field name to show which input it came from.
Multiple matches#

Matching by field can generate multiple matches if the inputs contain duplicate data. To handle this, select Add Option > Multiple Matches. Then choose:

  • Include All Matches: output multiple items (one for each match).
  • Include First Match Only: keep the first item, discard subsequent items.

Merge by position#

Combine items based on their order. The item at index 0 in Input 1 merges with the item at index 0 in Input 2, and so on.

Inputs with different numbers of items#

If there are more items in one input than the other, the default behavior is to leave out the items without a match. Choose Add Option > Include Any Unpaired Items to keep the unmatched items.

Field value clashes#

If both items at an index have a field with the same name, this is a clash. For example, if all items in both Input 1 and Input 2 have a field named language, these fields clash. By default, Ensemble prioritizes Input 2, meaning if language has a value in Input 2, Ensemble uses that value when merging the items.

You can change this behavior:

  1. Select Add Option > Clash Handling.
  2. Choose which input to prioritize, or choose Always Add Input Number to Field Names to keep all fields and values, with the input number appended to the field name to show which input it came from.

Multiplex#

Output all possible item combinations, while merging fields with the same name.

Field value clashes#

If both items at an index have a field with the same name, this is a clash. For example, if all items in both Input 1 and Input 2 have a field named language, these fields clash. By default, Ensemble prioritizes Input 2, meaning if language has a value in Input 2, Ensemble uses that value when merging the items.

You can change this behavior:

  1. Select Add Option > Clash Handling.
  2. Choose which input to prioritize, or choose Always Add Input Number to Field Names to keep all fields and values, with the input number appended to the field name to show which input it came from.

Options#

When combining branches, you can set Options:

For all modes:

  • Clash handling: choose how to merge when branches clash, or when there are sub-fields.
  • Fuzzy compare: whether to tolerate type differences when comparing fields (enabled), or not (disabled, default). For example, when you enable this, Ensemble treats "3" and 3 as the same.

When merging by field:

  • Disable dot notation: this prevents accessing child fields using parent.child in the field name.
  • Multiple matches: choose how Ensemble handles multiple matches when comparing branches.

When merging by position:

Include Any Unpaired Items: choose whether to keep or discard unpaired items.

Choose branch#

Choose which input to keep. This option always waits until the data from both inputs is available. You can keep the data from Input 1 or Input 2, or you can output a single empty item. The node outputs the data from the chosen input, without changing it.

Merging branches with uneven numbers of items#

The items passed into Input 1 of the Merge node will take precedence. For example, if the Merge node receives five items in Input 1 and 10 items in Input 2, it only processes five items. The remaining five items from Input 2 aren't processed.

Branch execution with If and Merge nodes#

/// info | 0.236.0 and below Ensemble removed this execution behavior in version 1.0. This section applies to pathways using the v0 (legacy) Pathway execution order. By default, this is all pathways built before version 1.0. You can change the execution order in your Pathway settings. /// If you add a Merge node to a Pathway containing an If node, it can result in both output branches of the If node executing.

The Merge node is triggered by one branch, then goes and executes the other branch.

For example, in the screenshot below there's a Pathway containing a Edit Fields node, If node, and Merge node. The standard If node behavior is to execute one branch (in the screenshot, this is the true output). However, due to the Merge node, both branches execute, despite the If node not sending any data down the false branch.

Try it out: A step by step example#

Create a Pathway with some example input data to try out the Merge node.

Set up sample data using the Code nodes#

  1. Add a Code node to the canvas and connect it to the Start node.
  2. Paste the following JavaScript code snippet in the JavaScript Code field: 
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
    return [
  {
    json: {
      name: 'Stefan',
      language: 'de',
    }
  },
  {
    json: {
      name: 'Jim',
      language: 'en',
    }
  },
  {
    json: {
      name: 'Hans',
      language: 'de',
    }
  }
];
  3. Add a second Code node, and connect it to the Start node.
  4. Paste the following JavaScript code snippet in the JavaScript Code field: 
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
    return [
	  {
    json: {
      greeting: 'Hello',
      language: 'en',
    }
  },
  {
    json: {
      greeting: 'Hallo',
      language: 'de',
    }
  }
];

Try out different merge modes#

Add the Merge node. Connect the first Code node to Input 1, and the second Code node to Input 2. Run the Pathway to load data into the Merge node.

Now try different options in Mode to see how it affects the output data.

Append#

Select Mode > Append, then select Execute node.

Merge by fields#

You can merge these two data inputs so that each person gets the correct greeting for their language.

  1. Select Mode > Merge By Fields.
  2. In both Input 1 Field and Input 2 Field, enter language. This tells Ensemble to combine the data by matching the values in the language field in each data set.
  3. Select Execute node.

Merge by position#

Select Mode > Merge By Position, then select Execute node.

Keep unpaired items#

If you want to keep all items, select Add Option > Include Any Unpaired Items, then enable Include Any Unpaired Items.

Multiplex#

Select Mode > Multiplex, then select Execute node.