Merge

flow.merge Logic v0.1.0

Combine the items of multiple inputs — append, combine by matching fields / position / all combinations, or choose one branch.

Ports

Direction	Port	Label
Input	`input1`	Input 1
Input	`input2`	Input 2
Output	`output`	Output

Input handles follow `numberInputs` (Input 1 … Input N, 2–10). Combine-by-matching-fields always uses exactly two inputs.

Properties

Property	Type	Default	Description
Mode `mode`	`select`	`"append"`	Append all inputs, combine matching items together, or output one chosen branch unchanged. `appendcombinechooseBranch`
Combine by `combineBy`	`select`	`"combineByFields"`	How items from the inputs are paired up before merging. `combineByFieldscombineByPositioncombineAll` Shown when `mode === "combine"`
Number of inputs `numberInputs`	`int`	`2`	How many inputs to merge (2–10). Combine by matching fields always uses exactly 2. Shown when `!isCombineFields(c)`
Fields to match `fieldsToMatch`	`json`	`[{"field1":"id","field2":"id"}]`	List of { field1, field2 } — the field on Input 1 and the field on Input 2 that must be equal for two items to match. Shown when `mode === "combine" && (combineBy ?? "combineByFields") === "combineByFields"`
Output type `joinMode`	`select`	`"keepMatches"`	Which items to output: only matches, only non-matches, everything, or all of one input enriched with the other. `keepMatcheskeepNonMatcheskeepEverythingenrichInput1enrichInput2` Shown when `mode === "combine" && (combineBy ?? "combineByFields") === "combineByFields"`
Output data from `outputDataFrom`	`select`	`"both"`	For matched items, output the merged pair or only one input's data. `bothinput1input2` Shown when `isCombineFields(c) && (joinMode ?? "keepMatches") === "keepMatches"`
Multiple matches `multipleMatches`	`select`	`"all"`	Output every matching pair, or only the first match per item. `allfirst` Shown when `mode === "combine" && (combineBy ?? "combineByFields") === "combineByFields"`
Fuzzy compare `fuzzyCompare`	`boolean`	`false`	Loosely compare values, so e.g. the number 3 and the string "3" are treated as equal. Shown when `mode === "combine" && (combineBy ?? "combineByFields") === "combineByFields"`
Disable dot notation `disableDotNotation`	`boolean`	`false`	Treat field names literally instead of interpreting dots as nested paths. Shown when `mode === "combine" && (combineBy ?? "combineByFields") === "combineByFields"`
Include unpaired items `includeUnpaired`	`boolean`	`false`	When the inputs differ in length, also output the left-over (unpaired) items. Shown when `mode === "combine" && combineBy === "combineByPosition"`
Clash handling `clashHandling`	`select`	`"preferInput2"`	When merged items share a field name, choose which value wins — or keep both by suffixing the input number. `preferInput1preferInput2addSuffix` Shown when `mode === "combine"`
Output `chooseBranchOutput`	`select`	`"input1"`	Which input's data to output unchanged, or a single empty item. `input1input2empty` Shown when `mode === "chooseBranch"`

Examples

Join two branches by position

An earlier revision of the Telegram Echo demo forked the trigger into a timestamp branch and joined the results back — combineByPosition pairs item n of Input 1 with item n of Input 2:

{
  "id": "join",
  "type": "flow.merge",
  "config": {
    "mode": "combine",
    "combineBy": "combineByPosition",
    "numberInputs": 2,
    "includeUnpaired": true,
    "clashHandling": "preferInput2"
  }
}

Join two datasets by key

{
  "mode": "combine",
  "combineBy": "combineByFields",
  "fieldsToMatch": [{ "field1": "id", "field2": "orderId" }],
  "joinMode": "keepMatches",
  "outputDataFrom": "both"
}

joinMode gives you the SQL-ish family: keep matches (inner), keep non-matches, keep everything (enrich), with outputDataFrom choosing both sides or one.

Tips

Input order is deterministic. The engine orders by target port — input1 is Input 1, always — so “which branch wins on a field clash” (clashHandling) is a real, stable choice.
append mode simply concatenates all inputs’ items; chooseBranch passes one input through untouched (or a single empty item) — useful as an explicit synchronization point.
Merge emits a list. If exactly one item comes out and the next node wants the bare item, follow with Limit and its unwrapSingle option.
fuzzyCompare treats 3 and "3" as equal when matching fields.

This page is generated from the node registry by gen-node-docs.mjs on every site build — ports, properties, defaults and visibility rules cannot drift from the code. The examples above are hand-authored and merged in.