Split

Splits a message into a sequence of messages.

Where and why do we use the Split node?

The Split node breaks one message into multiple messages. This is essential when you receive bulk data that needs individual processing. For example, a SQL query might return hundreds of rows, or an API might send multiple sensor readings in one payload. The Split node turns that single message into a stream of messages you can process one at a time.

Modes of operation

The Split node's behavior depends on what type of data is in msg.payload:

String/Buffer

Splits on a specified character (default is \n for newlines), a buffer sequence, or into fixed lengths. You can use spaces for words, commas for CSV data, or any character. Also supports multi-character strings and buffer sequences.

Array

Splits into individual array elements, or into arrays of a fixed length. Useful when APIs have batch size limits and you need to chunk data into smaller groups.

Object

Sends one message for each key-value pair. By default, the key name goes into msg.topic and the value goes into msg.payload.

How the node handles messages

Each output message gets a msg.parts property with information about how it was split from the original. This lets the Join node reassemble the sequence back into a single message.

The property contains:

• id - identifier for the message group
• index - position within the group
• count - total messages in the group (not set in streaming mode since the total is unknown)
• type - the original data type (string, array, object, or buffer)
• ch - for strings or buffers, the delimiter used to split the message
• key - for objects, the key name this message came from (also copied to msg.topic by default)
• len - when using fixed length splitting, the length of each segment

Streaming mode

In streaming mode, the node processes incomplete data across multiple messages. Say a serial device sends newline-terminated commands but a message ends mid-command. The node splits and sends the complete parts, then holds the incomplete part and prepends it to the next message that arrives.

Because streaming mode doesn't know how many messages to expect, it doesn't set msg.parts.count. This means you can't use it with the Join node in automatic mode, since Join needs to know when the sequence is complete.

Examples

Splitting arrays

Arrays are the simplest case. Feed in an array and get one message per element. Here an array [1, 2, 3, 4] becomes four messages.

Regrouping elements

Sometimes you need to chunk data into smaller groups. Say an API only accepts 20 records at a time but you have 100. Set Fixed length of to split the array into chunks of that size.

With input [1, 2, 3, 4, 5] and Fixed length of set to 2, you get three messages: [1, 2], [3, 4], and [5].

Splitting strings

The default string split uses \n (newline) as the delimiter, which splits text by line. This works for processing logs, CSV data, or any line-based format.

Here we split a list of European cities, one per line.

Splitting by word

Change the delimiter to a space and you can split sentences into words. Put a space character in the Split using field. It won't be visible in the form but it's there.

Splitting objects

When you split an object, you get one message per key-value pair. The key goes into msg.topic and the value goes into msg.payload.

This example splits a simple object mapping words to numbers.

Node Documentation

Splits a message into a sequence of messages.

Inputs

payloadobject | string | array | buffer

The behaviour of the node is determined by the type of msg.payload:

• string/buffer - the message is split using the specified character (default: \n), buffer sequence or into fixed lengths.
• array - the message is split into either individual array elements, or arrays of a fixed-length.
• object - a message is sent for each key/value pair of the object.

Outputs

partsobject

This property contains information about how the message was split from the original message. If passed to the join node, the sequence can be reassembled into a single message. The property has the following properties:

• id - an identifier for the group of messages
• index - the position within the group
• count - if known, the total number of messages in the group. See 'streaming mode' below.
• 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. The node can be configured to also copy this value to another message properties, such as msg.topic.
• len - the length of each message when split using a fixed length value

Details

This node makes it easy to create a flow that performs common actions across a sequence of messages before, using the join node, recombining the sequence into a single message.

It uses the msg.parts property to track the individual parts of a sequence.

Streaming mode

The node can also be used to reflow a stream of messages. For example, a serial device that sends newline-terminated commands may deliver a single message with a partial command at its end. In 'streaming mode', this node will split a message and send each complete segment. If there is a partial segment at the end, the node will hold on to it and prepend it to the next message that is received.

When operating in this mode, the node will not set the msg.parts.count property as it does not know how many messages to expect in the stream. This means it cannot be used with the join node in its automatic mode.