Group by
Description
Pure function grouping an array of model values into a map of arrays, keyed by one field every element carries. Pick the field on the node; a dotted path (customer.id) groups by a field of a nested model. Keys are strings at run time whatever the field's declared type. Fails when the chosen field is null on an element — group with For each and Map array append instead when the key can be absent.
When to use
Use Group by as the one-node form of the For each + Map array append loop: pick a field
on the node — from whatever model the connected array carries — and it buckets every
element by that field’s value in a single step. A dotted path such as customer.id
walks into a nested model to reach the field.
Reach for Map array append inside a For each instead when the key is computed rather than read straight from a field — a year extracted from a date, an uppercased name, two fields concatenated — or when the key field can be null on some elements. Group by fails the whole pipeline if the chosen field is null on any element, because map keys are strings and a null key could only share the empty string’s bucket, silently merging it with genuinely-empty keys. A null or empty input array is different: it yields an empty map rather than failing.
The output is exactly the shape a local variable declared with the “Map of arrays” kind holds, so it feeds straight into Map keys to iterate the groups or Map get to read one bucket directly.
Pins
Input pins
| Pin | Type | Default | Notes |
|---|---|---|---|
| Array | generic[] | — | The array of model values to group. The element type resolves at design-time from the connected source, and its fields populate the field picker used to choose the grouping key on the node itself — the key is node configuration, not a wired pin. A dotted path such as customer.id walks into a nested model. A null or empty array yields an empty map rather than failing. |
Output pins
| Pin | Type | Notes |
|---|---|---|
| Result | string{generic[]} | A map of arrays, one bucket per distinct value of the chosen field, holding every element that carried that value. Keys are always strings at run time, whatever type the field declares — grouping by an integer field gives keys like "2025". This is exactly the shape a local variable declared with the 'Map of arrays' kind holds. |
Example
Group a list of orders by customer ID without an explicit loop. Wire the orders array
into the Array input of Group by, then pick customer.id as the grouping field on the
node — a dotted path, since the customer is a nested model on each order. The Result
output is a map of arrays keyed by customer ID as a string. Wire it into Map keys and a
For each to log each customer’s order count, or wire a specific customer ID into Map get
to read that customer’s orders directly.