Join

Joins sequences of messages into a single message.

Where and why do we use the Join node?

The Join node combines multiple messages into one. It's the counterpart to the Split node and can automatically reverse a split operation, or you can configure it to merge messages from different sources based on specific rules. This is essential when you need to aggregate data from multiple sources, reassemble split sequences, or reduce message streams into summary values.

Modes of operation

The Join node operates in three different modes, each suited for different use cases.

Automatic Mode

When paired with the Split node, automatically joins messages to reverse the split that was performed. Uses the msg.parts property of incoming messages to determine how the sequence should be joined.

The msg.parts property should contain:

• id - identifier for the message group
• index - position within the group
• count - total number of messages in the group
• type - the message type (string, array, object, or buffer)
• ch - for strings or buffers, the delimiter used to split
• key - for objects, the property key this message came from
• len - the length when split using fixed length

Manual Mode

Configure how to join sequences by selecting which message property to join and choosing the output format:

• String or buffer - joins the selected property with specified join characters or buffer
• Array - adds each selected property or entire message to an output array
• Key/value object - uses a property of each message as the key for storing the required value
• Merged object - merges the property of each message under a single object

You can define when to send the combined message:

• After a specific number of message parts
• After a timeout following the first message
• After receiving a message with msg.complete property set

Reduce Sequence Mode

Applies a JSONata expression to each message in a sequence and accumulates the result to produce a single message. This is useful for calculations like sums, averages, or any custom aggregation logic.

The reduce expression runs for each message with special variables available:

• $A - the accumulated value
• $I - index of the message in the sequence
• $N - number of messages in the sequence

An optional fix-up expression can be applied after all messages have been processed to perform final calculations.

How the node handles messages

The Join node buffers messages internally to work across sequences. The Node-RED runtime setting nodeMessageBufferMaxLength limits how many messages can be buffered to prevent memory issues.

If you send a message with the msg.reset property set, the node clears the partly complete message without sending it and resets any part counts. When using manual mode with timeout, send a message with msg.restartTimeout set to restart the timeout.

For manual mode, the other properties of the output message come from the last message received before sending.

Examples

Automatic mode

This example shows automatic mode. The Split node breaks an array into individual messages, then Join automatically reassembles them back into the original array.

Manual mode

Here manual mode combines three separate sensor readings into one object. Each message has a different msg.topic (temperature, humidity, pressure) and those topics become the keys in the output object.

Reduce sequence mode

This example uses reduce mode to calculate total inventory. The expression $A+payload.quantity adds each item's quantity to the running total, starting from 0.

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.