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 (from an upstream node via $node["NodeName"] or other 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

Parameter	Type	Default	Required	Constraints	Description
Group By Fields	string[]	[]	Yes	At least 1 field	Field names to group by.
Input Field	string	""	No	Expression	Input data source expression.
Support Dot Notation	boolean	true	No	--	Enable nested field access.
Missing Field Behavior	select	"empty"	No	empty / null / skip	What to do when a grouping field is missing.
Include Grouping Fields	boolean	false	No	--	Include grouping fields in each group's output.

Grouping Field Examples

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

Input Field Examples

• {{ $node["Fetch Data"] }} -- Use the entire output of "Fetch Data" as the array.
• {{ $node["Fetch Data"].data }} -- Use data property from "Fetch Data".
• {{ $node["Aggregate"].results }} -- Use the results from a specific upstream node named "Aggregate".

Settings

Setting	Options	Default	Description
Timeout (seconds)	number	Pipeline default	Maximum execution time for this node (1--600).
Retry on Timeout	Pipeline Default / Enabled / Disabled	Pipeline Default	Whether to retry on timeout.
Retry on Fail	Pipeline Default / Enabled / Disabled	Pipeline Default	Whether to retry on failure. When Enabled, shows Advanced Retry Configuration.
On Error	Pipeline Default / Stop Pipeline / Continue Execution	Pipeline Default	Behavior when node fails after all retries.

Advanced Retry Configuration

Only visible when Retry on Fail is set to Enabled.

Field	Type	Default	Range	Description
Max Attempts	number	3	1--10	Maximum retry attempts.
Initial Delay (ms)	number	1000	100--30,000	Wait before first retry.
Max Delay (ms)	number	120000	1,000--300,000	Upper bound for backoff delay.
Multiplier	number	2.0	1.0--5.0	Exponential backoff multiplier.
Jitter Factor	number	0.1	0--0.5	Random jitter.

---

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	{{ $node["Read Events"] }}
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	{{ $node["Read Sensors"] }}
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	{{ $node["Quality Check"].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).