Skip to main content

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@1 keeps 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​

ParameterTypeRequiredDescription
pathstringYesJSON path to the source array
keyPathstringNoPath, 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
targetPathstringYesJSON path where the groups are stored
targetValueWriteModestringNo (Overwrite)How to write the result (Overwrite, Append, Prepend)
targetValueKindstringNo (Simple)The kind of value to write (Simple, Array)
documentModestringNo (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-01 and 2024-01-01T00:00:00 are different keys.
  • Numbers are compared by value: 1 and 1.0 are the same key.
  • Types are not converted: the number 1, the string "1" and the boolean true are 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 } ] }
]
  • 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