Merge node

Merge Node

Overview

The Merge Node consolidates payloads from two or more upstream branches into a single output. It always waits until every connected input delivers data, then merges the values according to the selected mode. Use it to fan-in parallel branches, stitch together batched results, or normalize multiple feeds for downstream processing.

---

Core Functionality

1. Wait-All Synchronization

• A single logical input port accepts multiple edges.
• Execution is forced into wait_all; the node fires only after every upstream branch completes.
• Validation ensures at least two connections exist to prevent misconfigured merges.

2. Flexible Merge Modes

• append (default) concatenates all incoming arrays or items in deterministic order (sources sorted alphabetically by node name).
• combine zips items positionally, producing composite objects; unmatched positions can be preserved or dropped.
• Other modes remain reserved for future releases and are rejected during validation if selected.

3. Auto-Normalization

• Each inbound payload is coerced into an array before processing, regardless of original shape.
• Mixed primitives and objects are supported—scalars become single-element arrays.
• In combine mode, fields are prefixed with the source identifier (such as input_0_field) to avoid collisions.

4. Output Metadata

• The merged output includes metadata keys like mergeMode, inputCount, itemCount, and processed_by="merge" for observability.
• Downstream nodes receive a single array representing the merged content.

5. Standard Settings

• Inherits core execution settings (Retry on Fail, On Error) and documentation options.
• Input settings are fixed (syncMode = wait_all, waitTimeout = 30s) and not user-editable.

---

Configuration Reference

Parameters Tab

Parameters Configuration

Settings Tab

Settings Configuration

Parameters (Dynamic Data)

Field	Type	Default	Description
Merge Mode	string	"append"	Merge strategy ("append" or "combine").
Combine By	string	"position"	Used when Mode is "combine"; currently only "position" is supported. “By position” aligns elements that share the same index across every upstream list—first with first, second with second—and stitches each aligned set into a single record.
Keep Unmatched Items	boolean	true	When true, extra rows from longer inputs are kept and missing sources remain empty in the merged result. When false, any row missing data from one or more sources is discarded so only fully matched positions are emitted.

Settings (Static Configuration)

Field	Type	Default	Description
Retry on Fail	boolean	false	Retries merge execution when infrastructure errors occur.
On Error	string	"Stop Pipeline"	"Stop Pipeline" fails the run, "Continue Execution" emits an error packet, "Retry Node" repeats under retry rules.
Notes	string	""	Describe the fan-in purpose and expected structure.
Display Note in Pipeline	boolean	false	Shows the note on the canvas for quick reference.

---

Usage Examples

Example 1: Append Finished Goods

Field	Value
Mode	Append
Notes	Combine pallets from parallel pack lines.

Line A emits [{"palletId":"A-101"},{"palletId":"A-102"}] while Line B emits [{"palletId":"B-201"}]. The merge node delivers a single array with all pallets in alphabetical order by source, ready for warehouse dispatch.

Example 2: Combine Torque and Temperature Samples

Field	Value
Mode	Combine
Combine By	By Position
Keep Unmatched Items	true
Notes	Zip torque and temperature readings for SPC.

Torque stream → [{"torqueNm":32.4},{"torqueNm":31.8}]
Temperature stream → [{"tempC":145.2},{"tempC":146.1},{"tempC":144.7}]

Output:

- input_0_torqueNm: 32.4
  input_1_tempC: 145.2
- input_0_torqueNm: 31.8
  input_1_tempC: 146.1
- input_1_tempC: 144.7

Leaving Keep Unmatched Items at true preserves the final temperature sample even without a torque partner.

Example 3: Align Inspection Flags with Counts

Field	Value
Mode	combine
Combine By	position
Keep Unmatched Items	false
On Error	Continue Execution

Inspection node outputs [{"station":"Laser","flag":"OK"},{"station":"Vision","flag":"REVIEW"}]. A counter node provides [{"count":120},{"count":118}]. Combined results yield paired objects such as { input_0_station: "Laser", input_0_flag: "OK", input_1_count: 120 }. Because Keep Unmatched Items is false, any extra counts or flags are discarded to maintain alignment.