List - Aggregate

Type identifier: list:aggregate Category: List Operations

Description

Aggregates list data using count, countDistinct, sum, avg, min, and max. Supports optional grouping and can return either the first aggregate row or the full result list.

Input Handles

Handle	Data Type	Required	Description
`source`	`array`	Yes	Source list to aggregate

Output Handles

Handle	Data Type	Description
`results`	`object` or `array`	Aggregation output (`object` if `firstOnly`, else array of rows)

Configuration Options

Property	Type	Required	Default	Description
`label`	`string`	Yes	`"List - Aggregate"`	Display label for the node
`schemaId`	`string` (CUID2)	No	`undefined`	Optional source schema identifier
`source`	`array`	Yes (runtime)	`undefined`	Input handle definition for source list
`groupBy`	`Array<{ id, path, alias }>`	No	`[]`	Grouping fields and output aliases
`aggregations`	`Array<{ id, function, sourcePath?, alias, distinct? }>`	Yes	`[{ id: "agg1", function: "count", alias: "count" }]`	Aggregation operations
`firstOnly`	`boolean`	No	`true`	Return first row object instead of full array

Supported Aggregation Functions

count
countDistinct
sum
avg
min
max

Behaviour

Execution Flow

Validates that source exists and at least one aggregation is configured.
Reads the list from the source input.
Validates source is a non-null array.
Groups rows by groupBy fields (or a single group when ungrouped).
Computes all configured aggregation functions per group.
Returns first row (firstOnly: true) or all rows (firstOnly: false).

Aggregation Details

count: number of rows in group.
countDistinct: unique value count for sourcePath; without sourcePath, same as count. Duration values that compare equal count as one value, so P1M, P30D and PT720H are a single distinct value.
sum: numeric sum; returns 0 when no numeric values are present.
avg: numeric average; returns null when no numeric values are present.
min / max: numeric min/max. When the field holds no numeric values, durations are compared instead, using the same 30-day rule as filtering and sorting — see Schema Field Types Reference — Sorting and Filtering. The duration is returned exactly as stored, so a minimum of P1M comes back as P1M rather than P30D; values that tie fall back to the stored text. Returns null when neither numeric nor duration values are present.

Edge Cases

Scenario	Behaviour
Empty source array with no `groupBy`	Returns one aggregate row (for example `{ count: 0 }`)
`sum`/`avg`/`min`/`max` without `sourcePath`	Throws `MISSING_FIELD_PATH`
Source resolves to `null`/`undefined`	Throws `INVALID_SOURCE_DATA`
Source resolves to non-array	Throws `INVALID_SOURCE`
No aggregations configured	Throws `NO_AGGREGATIONS`

Examples

Count All Rows

{
  "type": "list:aggregate",
  "data": {
    "label": "Count All",
    "groupBy": [],
    "aggregations": [{ "id": "agg1", "function": "count", "alias": "count" }],
    "firstOnly": true
  }
}

Possible output:

{ "count": 42 }

Grouped Sum

{
  "type": "list:aggregate",
  "data": {
    "label": "Total by Category",
    "groupBy": [{ "id": "grp1", "path": "category", "alias": "category" }],
    "aggregations": [{ "id": "agg1", "function": "sum", "sourcePath": "amount", "alias": "total" }],
    "firstOnly": false
  }
}

Possible output:

[
  { "category": "A", "total": 120 },
  { "category": "B", "total": 85 }
]

Data - Expression

Evaluates a mathematical or logical expression with variables. Supports arithmetic, string manipulation, date/time operations, similarity functions, and array operations. Use this node for calculations, transformations, and complex data logic.

List - Filter

Filters, sorts, and paginates an array of items. Apply filter conditions to select matching items, sort by multiple fields, remove duplicates, and limit results.

List - Map

Iterates over each item in a list and runs the nodes connected to the trigger output for each one. Creates a scoped context for each iteration where the current item is available. Collects results from all iterations into an output list. Supports both parallel and sequential modes.

Object - Query

Queries Records based on filter criteria. Supports complex filtering, pagination, and ordering. Returns matching Records with metadata. Results can be processed, displayed, or passed to downstream nodes.