Join

# What is Join node in Node-RED?

The Join node in Node-RED is used to combine sequences of messages into a single message. It is particularly useful when dealing with multiple input streams or when you need to aggregate data from different sources into a single payload.

# Configuring Join node

Mode:
- Automatic: When join node paired with the split node, it will automatically join the messages to reverse the split that was performed.
- Manual: Allows manual selection of how messages should be combined.
  - combine each: Allows selecting which message properties should be combined. Additionally allows to select complete message object to combine.
    - to create: Specifies the output type such as a string, buffer, array, key/value object, or merged object.
    - Send the message:
      - After a number of message parts: Sends the combined message after a specified number of parts have been received.
        
        and every subsequent message: Continues to send messages as they arrive but applies the specified number of parts for each combined message.
      - After a timeout following the first message: Waits for a timeout after receiving the first message part. If more parts arrive within the specified timeout, they are included in the combined message. The timeout can be restarted by sending a message with the msg.restartTimeout property set.
      - After a message with the msg.complete property set: If a message is received with the msg.complete property set, the output message is finalized and sent. This resets any part counts. Additionally, if a message is received with the msg.reset property set, the partly complete message is deleted and not sent, which also resets any part counts.
- Reduce sequence
  - Reduce exp: An expression applied to each message in the sequence to combine them into a single message.
  - Initial value: The starting value used in the combining process.
  - Fix-up exp: An optional expression used after combining the messages.
    - Evaluate in reverse order (last to first): Enabling this option combines messages in reverse order, starting from the last message.

# Usecases

Data Aggregation from Multiple Sensors: Suppose you have several sensors (e.g., temperature, humidity, pressure) sending data independently. You can use the Join node to combine these separate readings into a single message for analysis or storage.
Sequential Operations: When you need to perform a series of operations that depend on each other, you can use the Join node to ensure that all prerequisite data is available before proceeding with the next step.
Creating Complex Data Structures: By combining multiple messages into a single message with nested objects or arrays, the Join node facilitates the creation of complex data structures for applications like dashboard visualizations or machine learning models.
Time-Based Aggregation: If you need to aggregate data over a specific time period (e.g., hourly averages, daily totals), the Join node can accumulate data within that interval and output aggregated results.
Handling Parallel Workflows: In workflows where multiple tasks run concurrently and their results need to be synchronized or aggregated, the Join node helps manage parallel execution and consolidate outputs.
Batch Processing: If you want to process data in batches rather than individually, the Join node can accumulate messages until a specified count or time threshold is reached, then emit a combined message for batch processing.

# Examples

In the example below, the Join node uses automatic mode to rejoin the message split by the Split node.

In the example below, the Join node utilizes manual mode to merge three payload properties into one based on the value of the msg.topic object.

In the example below, the Join node calculates the total number of stocks using the reduce expression.

Node Documentation

Joins sequences of messages into a single message.

There are three modes available:

automatic: When paired with the split node, it will automatically join the messages to reverse the split that was performed.
manual: Join sequences of messages in a variety of ways.
reduce sequence: Apply an expression against all messages in a sequence to reduce it to a single message.

Inputs

partsobject

To automatically join a sequence of messages, they should all have this property set. The split node generates this property but it can be manually created. It has the following properties:

id - an identifier for the group of messages
index - the position within the group
count - the total number of messages in the group
type - the type of message - string/array/object/buffer
ch - for a string or buffer, the data used to the split the message as either the string or an array of bytes
key - for an object, the key of the property this message was created from
len - the length of each message when split using a fixed length value

complete

If set, the node will append the payload, and then send the output message in its current state. If you don't wish to append the payload, delete it from the msg.

reset

If set, the node will clear any partially complete message and not send it.

restartTimeout

If set, and the node has a timeout configured, that timeout will be restarted.

Details

Automatic mode

Automatic mode uses the parts property of incoming messages to determine how the sequence should be joined. This allows it to automatically reverse the action of a split node.

Manual mode

When configured to join in manual mode, the node is able to join sequences of messages into a number of different results:

a string or buffer - created by joining the selected property of each message with the specified join characters or buffer.
an array - created by adding each selected property, or entire message, to the output array.
a key/value object - created by using a property of each message to determine the key under which the required value is stored.
a merged object - created by merging the property of each message under a single object.

The other properties of the output message are taken from the last message received before the result is sent.

A count can be set for how many messages should be received before generating the output message. For object outputs, once this count has been reached, the node can be configured to send a message for each subsequent message received.

A timeout can be set to trigger sending the new message using whatever has been received so far. This timeout can be restarted by sending a message with the msg.restartTimeout property set.

If a message is received with the msg.complete property set, the output message is finalised and sent. This resets any part counts.

If a message is received with the msg.reset property set, the partly complete message is deleted and not sent. This resets any part counts.

Reduce Sequence mode

When configured to join in reduce mode, an expression is applied to each message in a sequence and the result accumulated to produce a single message.

Initial value

The initial value of the accumulated value ($A).

Reduce expression

A JSONata expression that is called for each message in the sequence. The result is passed to the next call of the expression as the accumulated value. In the expression, the following special variables can be used:

$A: the accumulated value,
$I: index of the message in the sequence,
$N: number of messages in the sequence.

Fix-up expression

An optional JSONata expression that is applied after the reduce expression has been applied to all messages in the sequence. In the expression, following special variables can be used:

$A: the accumulated value,
$N: number of messages in the sequence.

By default, the reduce expression is applied in order, from the first to the last message of the sequence. It can optionally be applied in reverse order.

$N is the number of messages that arrive - even if they are identical.

Example: the following settings, given a sequence of numeric values, calculates the average value:

Reduce expression: $A+payload
Initial value: 0
Fix-up expression: $A/$N

Storing messages

This node will buffer messages internally in order to work across sequences. The runtime setting nodeMessageBufferMaxLength can be used to limit how many messages nodes will buffer.