GroupBy@1
Node GroupBy@1 groups the items of an array by a key. The result is an array with one entry { key, items } per distinct key. Use it to process a batch one entity at a time: group the items by the entity id, then iterate over the groups with ForEach@1 and read and write each entity once.
It is a pure in-memory transformation. Do not confuse it with:
- Group@1, a purely structural container of the graphical editor without any effect on the data.
- Distinct@1, which keeps only the first item per key and drops the others.
GroupBy@1keeps all items.
Adapter Prerequisites
- General availability: All adapters support this node type.
Node Configuration
For fields path, targetPath, targetValueWriteMode, targetValueKind and documentMode, see Overview.
transformations:
- type: GroupBy@1
path: $.states # Path to the source array
keyPath: $.controlUuid # Path relative to each item, resolves to a simple value
targetPath: $.stateGroups # Path where the groups are stored
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | Yes | JSON path to the source array |
keyPath | string | No | Path, relative to each item, to the value that defines the group (string, number, boolean). Without keyPath the array must contain scalar values and each value is its own key |
targetPath | string | Yes | JSON path where the groups are stored |
targetValueWriteMode | string | No (Overwrite) | How to write the result (Overwrite, Append, Prepend) |
targetValueKind | string | No (Simple) | The kind of value to write (Simple, Array) |
documentMode | string | No (Extend) | Document mode (Extend, Replace) |
Result
[
{ "key": "uuid-1", "items": [ { ... }, { ... } ] },
{ "key": "uuid-2", "items": [ { ... } ] }
]
- Groups appear in the order of the first occurrence of their key.
- Items keep their original order within a group.
- Items are copied; the source array stays unchanged.
Key Comparison
Keys are compared by value, using the same rules as Distinct@1:
- Strings are compared ordinally (case-sensitive). Strings that look like dates are not parsed, so
2024-01-01and2024-01-01T00:00:00are different keys. - Numbers are compared by value:
1and1.0are the same key. - Types are not converted: the number
1, the string"1"and the booleantrueare three different keys.
Items Without a Key
Items without a simple value at keyPath (path not found, null, an object or array, or an item that is not an object) are skipped. The node does not fail; it writes one warning per run with the number of skipped items.
Empty or Missing Source
If the source is not an array or is empty, nothing is written to targetPath and the pipeline continues (same behavior as Distinct@1).
Example: Process State Changes One Entity at a Time
A batch holds state changes of several controls. Group them by control, then handle each control once:
transformations:
- type: GroupBy@1
path: $.states
keyPath: $.controlUuid
targetPath: $.stateGroups
- type: ForEach@1
path: $.stateGroups
iterationPath: $.stateGroups
transformations:
# inside the loop: $.key.key is the control UUID, $.key.items are its state changes
- type: PrintDebug@1
Input:
{
"states": [
{ "controlUuid": "c-1", "state": "active", "value": 1 },
{ "controlUuid": "c-2", "state": "active", "value": 0 },
{ "controlUuid": "c-1", "state": "totalDay", "value": 12.5 }
]
}
Output ($.stateGroups):
[
{ "key": "c-1", "items": [
{ "controlUuid": "c-1", "state": "active", "value": 1 },
{ "controlUuid": "c-1", "state": "totalDay", "value": 12.5 } ] },
{ "key": "c-2", "items": [
{ "controlUuid": "c-2", "state": "active", "value": 0 } ] }
]
Related Nodes
- Distinct@1: Keep only the first item per key
- Group@1: Structural container of the editor (no runtime effect)
- Flatten@1: Flatten nested array structures