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.

To count or total stored Records, without loading them into the flow first, use Object - Query with a select/groupBy shape: it aggregates in the database, over every matching Record and over relationships. Use this node for lists the flow already holds.

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 the Records of a Schema that match a filter, with pagination and ordering. Returns the matching Records with their metadata, or, with a select/groupBy shape, rows of chosen fields, aggregates over relationships, and grouped counts and totals. Use this node to retrieve data for processing, display, or downstream operations.

Page not found. It may have moved or may not be published.

Browse documentation