Split Out

Loop through array items one by one

Overview

Separates a single item containing an array into multiple individual items. Essential for processing API responses where data is returned as a list within a single object.

Category: Core Nodes
Tool Name: split_out
Version: 1

Appearance: Icon: splitOut | Color: #ec4899

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool does not require any credentials.

Parameters

Parameter	Type	Required	Default	Description
Field To Split Out	string	Yes	—	The name of the field containing the array to split. Use dot notation for nested fields (e.g., ‘results.items’, ‘data.records’). Supports expressions like {{ $json.arrayFieldName }}.
Include	options	Yes	noOtherFields	Determines which other fields from the original item are included in each split output item.
				Options: noOtherFields (only include the data from the split array), allOtherFields (include all other fields from the original item in each split item), selectedOtherFields (include only specific fields from the original item)
Fields To Include	string	No	—	Comma-separated list of field names to include when ‘Include’ is set to ‘Selected Other Fields’. Supports dot notation for nested fields (e.g., ‘id, metadata.timestamp, user.name’). (shown when Include is selectedOtherFields)
Options	collection	No	{}	Additional options for controlling split behavior.
— Destination Field Name	string	No	—	If set, places the split data under this field name instead of at the root level. For example, setting ‘item’ would output { item: <splitData> } instead of <splitData> directly.
— Disable Dot Notation	boolean	No	false	When enabled, dots in field names are treated literally rather than as nested path separators. Enable this if your field names contain actual dots.
— Include Binary	boolean	No	false	When enabled, binary data (if any) from the input item is passed through to all split output items.
Max Concurrency	number	No	100	Maximum number of input items to process concurrently.

Output Data

This node changes how many items are in flight: one input item becomes one output item per element of the array at Field To Split Out. An input item whose array is empty produces no output items at all, and an input item whose named field is missing or is not an array is an item error. Binary data is forwarded to every split item only when Include Binary is on.

Each output item is built like this:

• With Destination Field Name set, the element is placed whole under that name — { "item": <element> }.
• With no Destination Field Name, an element that is a plain object is merged at the root of the output item, so its own keys become the item’s fields. Anything else — a string, number, boolean, or nested array — is wrapped under the key value.
• Whatever Include selects is added alongside: nothing (noOtherFields), every other field of the original item (allOtherFields — the split field itself is removed), or just the fields named in Fields To Include (selectedOtherFields).

Every output item also carries _splitMeta, describing where it came from:

{
  "_splitMeta": {
    "sourcePointer": "...",
    "sourceField": "data.users",
    "arrayIndex": 0,
    "arrayLength": 3
  }
}

sourceField is the resolved path that was split, arrayIndex is the element’s position in that array and arrayLength its total length — useful for numbering or for detecting the last item downstream. sourcePointer is an internal reference to the item this one was split from.

Reference the split element downstream by expression, e.g. {{ $json.id }} when elements are objects, or {{ $json.value }} when they are not.

Usage Examples

• loop through each item in the list
• process every element one by one
• split the array into individual items
• iterate over the results
• go through each row separately

Example Configuration

Basic split, no other fields:

{
  "type": "split_out",
  "parameters": {
    "fieldToSplitOut": "data.users",
    "include": "noOtherFields"
  }
}

Split with all other fields:

{
  "type": "split_out",
  "parameters": {
    "fieldToSplitOut": "results.items",
    "include": "allOtherFields",
    "maxConcurrency": 50
  }
}

Split with selected fields only:

{
  "type": "split_out",
  "parameters": {
    "fieldToSplitOut": "response.records",
    "include": "selectedOtherFields",
    "fieldsToInclude": "id, metadata.timestamp, status"
  }
}

Advanced split with options:

{
  "type": "split_out",
  "parameters": {
    "fieldToSplitOut": "api.data.entries",
    "include": "selectedOtherFields",
    "fieldsToInclude": "requestId, user.email",
    "options": {
      "destinationFieldName": "item",
      "disableDotNotation": false,
      "includeBinary": true
    }
  }
}

Split an API response containing multiple records:

{
  "type": "split_out",
  "parameters": {
    "fieldToSplitOut": "data.results",
    "include": "allOtherFields"
  }
}

Split an array but preserve only essential metadata:

{
  "type": "split_out",
  "parameters": {
    "fieldToSplitOut": "orders.items",
    "include": "selectedOtherFields",
    "fieldsToInclude": "orderId, customerId, timestamp"
  }
}

Split deeply nested arrays with a custom output structure:

{
  "type": "split_out",
  "parameters": {
    "fieldToSplitOut": "response.data.transactions.list",
    "include": "noOtherFields",
    "options": {
      "destinationFieldName": "transaction",
      "includeBinary": false
    }
  }
}

When field names contain actual dots rather than path separators:

{
  "type": "split_out",
  "parameters": {
    "fieldToSplitOut": "data.records",
    "include": "selectedOtherFields",
    "fieldsToInclude": "user.email.address, config.api.key",
    "options": {
      "disableDotNotation": true
    }
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Takes an array field within each item and splits it into separate output items, one per array element. Use when a previous tool produced items containing arrays that need to be processed individually. Produces N items from each input item, where N is the length of the specified array field.