Item Lists

Sort, limit, deduplicate, split, concatenate, and summarize items

Overview

The Item Lists tool provides 6 bulk operations on item collections: sort (simple or random), limit (first/last N), removeDuplicates (by all/selected/excluded fields), splitOutItems (explode arrays into separate items), concatenateItems (merge fields from all items into one), and summarize (aggregate with count, sum, min, max, average, concatenate, append, countUnique — grouped by split-by fields). These are bulk operations that process ALL input items at once.

Category: Core Nodes
Tool Name: item_lists
Version: 1

Appearance: Icon: lucide-List | Color: #ff6d5a

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.

Operations

Operation	Value	Description
Concatenate Items	concatenateItems	Merge fields from all items into one
Limit	limit	Remove items if there are too many
Remove Duplicates	removeDuplicates	Remove duplicate items
Sort	sort	Change the order of items
Split Out Items	splitOutItems	Turn array into separate items
Summarize	summarize	Aggregate items (pivot table)

Parameters

Concatenate Items (concatenateItems)

Parameter	Type	Required	Default	Description
Aggregate	options	No	aggregateIndividualFields	How the items are merged together.
				Options: aggregateIndividualFields (collect named fields into arrays), aggregateAllItemData (put every input item into one field)
Fields To Aggregate	fixedCollection	No	{}	The fields to collect from every item, and how to name them on the output. (shown when Aggregate is aggregateIndividualFields)
— Input Field Name	string	No	—	Name of the field to read from each item. Supports dot-notation for nested fields.
— Rename Field	boolean	No	false	Give the collected values a different name on the output item.
— Output Field Name	string	No	—	The name to write the collected values under. (shown when Rename Field is true)
— Merge Lists	boolean	No	false	If the field is an array, merge into the aggregate instead of nesting.
Destination Field Name	string	No	data	Name of the field that receives the full list of input items. (shown when Aggregate is aggregateAllItemData)

Limit (limit)

Parameter	Type	Required	Default	Description
Max Items	number	No	10	The maximum number of items to keep.
Keep	options	No	firstItems	Which items to keep when there are more than Max Items.
				Options: firstItems, lastItems

Remove Duplicates (removeDuplicates)

Parameter	Type	Required	Default	Description
Compare	options	No	allFields	How two items are compared to decide whether they are duplicates.
				Options: allFields, allFieldsExcept, selectedFields
Fields To Compare	string	No	—	Comma-separated list of the only fields to compare. (shown when Compare is selectedFields)
Fields To Exclude	string	No	—	Comma-separated list of fields to ignore when comparing. (shown when Compare is allFieldsExcept)

Sort (sort)

Parameter	Type	Required	Default	Description
Sort Type	options	No	simple	Sort by field values, or shuffle the items into a random order.
				Options: simple, random
Sort Fields	fixedCollection	No	{}	The fields to sort by, applied in the order you list them. (shown when Sort Type is simple)
— Field Name	string	No	—	Name of the field to sort on. Supports dot-notation for nested fields.
— Order	options	No	ascending	Sort direction for this field.
				Options: ascending, descending

Split Out Items (splitOutItems)

Parameter	Type	Required	Default	Description
Field To Split Out	string	Yes	—	The field holding the array (or object) to turn into separate items.
Include	options	No	noOtherFields	Which of the item’s other fields to carry onto each new item.
				Options: noOtherFields, allOtherFields, selectedOtherFields
Fields To Include	string	No	—	Comma-separated list of the other fields to carry over. (shown when Include is selectedOtherFields)

Summarize (summarize)

Parameter	Type	Required	Default	Description
Fields to Summarize	fixedCollection	No	{}	The aggregations to compute for each group.
— Aggregation	options	No	count	The aggregation to apply to the field.
				Options: append, average, concatenate, count, countUnique, max, min, sum
— Field	string	No	—	Field to aggregate (leave empty for count).
Fields to Split By	string	No	—	Group items by these fields before summarizing.

All Operations

Parameter	Type	Required	Default	Description
Options	collection	No	{}	Extra settings; which ones apply depends on the operation.
— Disable Dot Notation	boolean	No	false	If true, field names with dots are treated literally.
— Remove Other Fields	boolean	No	false	When deduplicating by selected fields, only keep those fields. (shown when Operation is removeDuplicates and Compare is selectedFields)
— Destination Field Name	string	No	—	Write each split-out element under this name instead of the original field name. (shown when Operation is splitOutItems)
— Put Output in Field	string	No	—	Write the merged list under this name instead of Destination Field Name. (shown when Operation is concatenateItems)
— Output Format	options	No	separateItems	Whether each group becomes its own item or all groups land on one item. (shown when Operation is summarize)
				Options: separateItems, singleItem
— Separator	string	No	,	Separator for concatenate aggregation. (shown when Operation is summarize)
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

This node is a bulk node: it reads every input item, applies the operation to the whole collection in memory, and writes a fresh set of output items. Output items carry JSON only — binary data is not forwarded, so attach files after this node, not before it.

How many items come out depends on the operation:

Operation	Output items
sort	The same items, reordered. Count is unchanged.
limit	At most Max Items — the first or last of them, per Keep.
removeDuplicates	One item per distinct value. Duplicates after the first are dropped.
splitOutItems	One item per element of the split field, so one input item can become many. An item whose field is neither an array nor an object passes through untouched.
concatenateItems	Exactly one item for the whole run.
summarize	One item per group with separateItems, or a single item with singleItem.

Field naming, per operation:

• concatenateItems with aggregateIndividualFields — the single output item has one field per entry in Fields To Aggregate, each holding an array of the values found across all items. The field keeps its input name unless Rename Field is on, in which case Output Field Name is used. With Merge Lists on, an array value is spread into the aggregate rather than nested. If Fields To Aggregate is empty the items pass through unchanged.
• concatenateItems with aggregateAllItemData — the single output item is { "<Destination Field Name>": [ …every input item… ] }, or the name from Put Output in Field when that is set.
• splitOutItems — each element is written to Destination Field Name when set, otherwise to the name of Field To Split Out. With allOtherFields the rest of the item is copied alongside it; with selectedOtherFields only Fields To Include are copied; with noOtherFields the element is the only field.
• summarize — each output item carries the Fields to Split By values plus one field per aggregation, named <aggregation>_<field> (for example sum_revenue, average_score). An aggregation with no Field is named after the aggregation alone (count). min, max, sum and average consider numeric values only and return null when a group has none. With singleItem the whole set is wrapped as { "results": [ … ] } on one item.
• removeDuplicates — the surviving item is the original item, unless Remove Other Fields is on with selectedFields, in which case only the compared fields are kept.

Usage Examples

• Sort items by price descending
• Keep only first 10 items
• Remove duplicate contacts
• Split array field into separate items
• Summarize sales by region

Example Configuration

Sort by two fields, most important first:

{
  "type": "item_lists",
  "parameters": {
    "operation": "sort",
    "sortType": "simple",
    "sortFieldsUi": {
      "sortField": [
        {
          "fieldName": "priority",
          "order": "descending"
        },
        {
          "fieldName": "name",
          "order": "ascending"
        }
      ]
    }
  }
}

Keep only the first five items:

{
  "type": "item_lists",
  "parameters": {
    "operation": "limit",
    "maxItems": 5,
    "keep": "firstItems"
  }
}

Deduplicate on two fields only:

{
  "type": "item_lists",
  "parameters": {
    "operation": "removeDuplicates",
    "compare": "selectedFields",
    "fieldsToCompare": "email,phone"
  }
}

Explode an array field, carrying two other fields onto each new item:

{
  "type": "item_lists",
  "parameters": {
    "operation": "splitOutItems",
    "fieldToSplitOut": "skills",
    "include": "selectedOtherFields",
    "fieldsToInclude": "name,department"
  }
}

Collect one field from every item into a single list:

{
  "type": "item_lists",
  "parameters": {
    "operation": "concatenateItems",
    "aggregate": "aggregateIndividualFields",
    "fieldsToAggregate": {
      "fieldToAggregate": [
        {
          "fieldToAggregate": "tags",
          "renameField": true,
          "outputFieldName": "allTags",
          "mergeLists": true
        }
      ]
    }
  }
}

Put every input item into one field:

{
  "type": "item_lists",
  "parameters": {
    "operation": "concatenateItems",
    "aggregate": "aggregateAllItemData",
    "destinationFieldName": "allData"
  }
}

Build a pivot table grouped by two fields:

{
  "type": "item_lists",
  "parameters": {
    "operation": "summarize",
    "fieldsToSplitBy": "department,status",
    "fieldsToSummarize": {
      "values": [
        {
          "aggregation": "count",
          "field": "employeeId"
        },
        {
          "aggregation": "sum",
          "field": "salary"
        }
      ]
    }
  }
}

Deduplicate while ignoring volatile fields:

{
  "type": "item_lists",
  "parameters": {
    "operation": "removeDuplicates",
    "compare": "allFieldsExcept",
    "fieldsToExclude": "id,createdAt",
    "options": {
      "disableDotNotation": false
    }
  }
}

Report on revenue by region and quarter:

{
  "type": "item_lists",
  "parameters": {
    "operation": "summarize",
    "fieldsToSplitBy": "region,quarter",
    "fieldsToSummarize": {
      "values": [
        {
          "aggregation": "count",
          "field": "orderId"
        },
        {
          "aggregation": "sum",
          "field": "revenue"
        },
        {
          "aggregation": "average",
          "field": "customerSatisfaction"
        }
      ]
    }
  }
}

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

Sort, limit, deduplicate, split, concatenate, and summarize item arrays — bulk operations on all items at once.

Behavior notes

• This is a whole-branch operation. The node collects every item that reaches it before it does anything, so it cannot start producing output until the upstream branch has finished. Field names are read once for the node run, not per item.
• Field names are literal, not expressions. Fields To Compare, Field To Split Out, Fields to Split By and the rest take plain field names — with dot-notation for nested paths — rather than {{ … }} expressions.
• Dot-notation is on by default. A field whose name genuinely contains a dot is only reachable with Options → Disable Dot Notation turned on, which then applies to every field name in the node.
• Deduplication compares values, not identity. Two items match when the compared portion is deeply equal, so field order does not matter but a differing timestamp or id does — use allFieldsExcept to ignore those.
• Attach files after this node. Binary data does not survive the operation, so put Item Lists before the node that fetches or builds the file, not after it.