Group By Node

Group By Node

Overview

The Group By Node takes an array of items and builds a hierarchical object by grouping records on one or more fields.
It is useful when you need to pivot or aggregate data by equipment, line, product, or any other dimension before sending it to dashboards, reports, or downstream logic.

The node:

• Accepts an array (either directly from $input or via an expression).
• Groups data by an ordered list of fields (supporting dot notation).
• Produces a nested object where each level corresponds to a grouping field.
• Optionally removes grouping keys from the final items for cleaner output.

Configuration Reference

Parameters Tab

Grouping Configuration

Settings Tab

Settings Configuration

Parameters (Dynamic Data)

Field	Type	Default	Description
Group By Fields	array<string>	[]	Ordered list of field names used for hierarchical grouping. At least one field is required.
Input Field	string	"" (meaning {{$input}})	Expression that must evaluate to an array to group.
Support Dot Notation	boolean	true	Enables dot-notation lookups such as user.department.
Missing Field Behavior	string	"empty"	How to handle missing grouping fields: "empty", "null", or "skip".
Include Grouping Fields	boolean	false	Include grouping fields in the output items (when false, they are removed).

Grouping Field Examples

• fieldName
• user.department (with dot notation enabled)
• equipment.line

Input Field Examples

• {{$input}} – Use the entire input as the array.
• {{$input.data}} – Use data property of the input.
• {{$inputs["Aggregate"].results}} – Use the results from a specific upstream node.

Settings (Static Configuration)

Field	Type	Default	Description
Retry on Fail	boolean	false	Retry when grouping fails due to transient issues.
On Error	string	"stopPipeline"	"stopPipeline" fails the branch; "continueExecution" returns an empty object instead of failing.
Notes	string	""	Internal documentation about the grouping strategy.
Display Note in Pipeline	boolean	false	Shows notes directly on the canvas near the node.

---

Usage Examples

Example 1: Group Production Events by Line

Input array:

[
  { "line": "Line-A", "event": "start", "timestamp": 1700000000000 },
  { "line": "Line-A", "event": "stop", "timestamp": 1700000100000 },
  { "line": "Line-B", "event": "start", "timestamp": 1700000200000 }
]

Configuration:

Field	Value
Group By Fields	["line"]
Input Field	{{$input}}
Support Dot Notation	false
Missing Field Behavior	"empty"
Include Grouping Fields	false

Output:

{
  "Line-A": [
    { "event": "start", "timestamp": 1700000000000 },
    { "event": "stop", "timestamp": 1700000100000 }
  ],
  "Line-B": [
    { "event": "start", "timestamp": 1700000200000 }
  ]
}

Example 2: Group by Line and Station with Dot Notation

Input array:

[
  { "meta": { "line": "Line-A", "station": "Station-1" }, "value": 10 },
  { "meta": { "line": "Line-A", "station": "Station-1" }, "value": 12 },
  { "meta": { "line": "Line-A", "station": "Station-2" }, "value": 9 }
]

Configuration:

Field	Value
Group By Fields	["meta.line", "meta.station"]
Input Field	{{$input}}
Support Dot Notation	true
Missing Field Behavior	"skip"
Include Grouping Fields	false

Output:

{
  "Line-A": {
    "Station-1": [
      { "value": 10 },
      { "value": 12 }
    ],
    "Station-2": [
      { "value": 9 }
    ]
  }
}

Example 3: Using a Nested Input Field

Upstream node produces:

{
  "data": [
    { "product": "Widget-A", "status": "pass" },
    { "product": "Widget-A", "status": "fail" },
    { "product": "Widget-B", "status": "pass" }
  ]
}

Configuration:

Field	Value
Group By Fields	["product", "status"]
Input Field	{{$input.data}}
Support Dot Notation	false
Missing Field Behavior	"empty"
Include Grouping Fields	true

Result groups the nested data array by product and status while keeping those fields in each leaf item.

---

When to Use Group By

Use the Group By node when:

• You need to pivot or aggregate arrays into hierarchical structures for dashboards or reports.
• You want a declarative configuration for grouping (field list, dot notation, missing-field strategy) instead of custom scripting.
• You are preparing data for downstream nodes that expect structured groupings (e.g., summary functions, Smart Connector calls, or UNS publishing).