---
title: 'Aggregate'
description: 'Roll up an array into a single number or grouped totals.'
---
# Aggregate

Takes an array of values and returns a scalar summary (sum / count / avg /
min / max) or a grouped map (groupBy).

## When to use

- Reporting nodes: "Total revenue for this batch = sum of amount."
- Summary metrics after a Loop: "How many items passed? How many failed?"
- Grouping a flat list by a category field for downstream per-group
  processing.

## Configuration

| Field | Required | What it does |
|---|---|---|
| `arrayPath` | Yes | Data reference pointing to the array to aggregate. |
| `operation` | Yes | `sum`, `count`, `avg`, `min`, `max`, or `groupBy`. |
| `field` | See table | Which field on each array element to aggregate. Not required for `count`. |
| `groupByField` | See table | Which field to group by. Required only for `groupBy`. |

### Operation reference

| Operation | Uses `field` | Returns |
|---|---|---|
| `sum` | Yes | Numeric sum of `field` across all elements |
| `count` | No | Count of elements |
| `avg` | Yes | Numeric mean of `field` |
| `min` | Yes | Minimum value of `field` |
| `max` | Yes | Maximum value of `field` |
| `groupBy` | Yes (`groupByField`) | `{ [group]: [...elements] }` |

## What it outputs

```
{
  value: <the scalar result, or the grouped map>,
  operation: "sum",
  sourceCount: 142
}
```

Downstream nodes reference `{{aggregate.data.value}}`.

## Example: total revenue by country

```
Loop results → Aggregate
  arrayPath: {{loop.data.results}}
  operation: groupBy
  groupByField: country
→ Transform
  mappings: [
    { targetKey: "us_total", sourceExpression: "{{agg.data.value.US.length}}" },
    …
  ]
```

## Gotchas

- **Non-numeric `field`** with `sum`/`avg`/`min`/`max` is silently
  ignored. Check your data shape first.
- **Empty array** returns `{ value: 0, … }` for numeric ops, `[]` for
  `groupBy`'s empty groups.