Running Aggregates Reference
This page is the formal specification for Report Forge running aggregate functions. For the configuration guide see Running Aggregates. For a step-by-step tutorial see Running Aggregates Tutorial.
Function definitions
running_sum
Returns: The cumulative sum of the source field's values from the first row to the current row, in sort order.
Formula: running_sum[n] = Σ value[1..n]
Source field type: Number, Currency, Percent, or Computed (outputting a numeric type).
Null handling: Null values are treated as zero in the accumulation. The running sum continues past null rows without interruption.
Example:
| Row | Period Cost | running_sum |
|---|---|---|
| 1 | 100 | 100 |
| 2 | null | 100 |
| 3 | 200 | 300 |
| 4 | 150 | 450 |
running_avg
Returns: The cumulative average of the source field's values from the first row to the current row, in sort order. This is a cumulative average, not a rolling window average.
Formula: running_avg[n] = Σ value[1..n] / count_non_null[1..n]
Null handling: Null values are excluded from both the numerator and denominator. The count of non-null values is used.
Example:
| Row | Period Cost | Non-null count | running_avg |
|---|---|---|---|
| 1 | 100 | 1 | 100.0 |
| 2 | null | 1 | 100.0 |
| 3 | 200 | 2 | 150.0 |
| 4 | 150 | 3 | 150.0 |
running_count
Returns: The cumulative count of non-null values in the source field from the first row to the current row, in sort order.
Formula: running_count[n] = count(non_null value[1..n])
Source field type: Any field type — counts non-null occurrences.
Null handling: Null values do not increment the count.
Example:
| Row | Risk Description | running_count |
|---|---|---|
| 1 | "Foundation issue" | 1 |
| 2 | null | 1 |
| 3 | "Wet season" | 2 |
| 4 | "Access delay" | 3 |
running_min
Returns: The minimum value seen in the source field from the first row to the current row, in sort order.
Formula: running_min[n] = MIN(value[1..n])
Null handling: Null values are ignored. The minimum is the lowest non-null value seen so far.
Example:
| Row | Period Cost | running_min |
|---|---|---|
| 1 | 300 | 300 |
| 2 | 100 | 100 |
| 3 | null | 100 |
| 4 | 200 | 100 |
running_max
Returns: The maximum value seen in the source field from the first row to the current row, in sort order.
Formula: running_max[n] = MAX(value[1..n])
Null handling: Null values are ignored. The maximum is the highest non-null value seen so far.
Example:
| Row | Period Cost | running_max |
|---|---|---|
| 1 | 100 | 100 |
| 2 | 300 | 300 |
| 3 | null | 300 |
| 4 | 200 | 300 |
Sort order
Running aggregates are evaluated in the sort order defined by the Sort field and Sort direction settings.
| Requirement | Behaviour |
|---|---|
| Sort field must be specified | Yes — without an explicit sort field, row order is undefined and results are non-deterministic |
| Stable sort required | Yes — if multiple rows have the same sort field value, add a tie-breaker sort field (e.g. row ID) |
| Sort direction | Ascending or Descending — controls which row is "first" in the accumulation |
| Multi-level sort | Supported — the running aggregate follows the primary sort, then secondary sort for ties |
Reset on group behaviour
When the component has grouping enabled, the Reset on group setting controls accumulation across group boundaries.
| Reset on group | Behaviour |
|---|---|
| On (default) | Accumulation resets to the initial state at the start of each group. Produces a per-group running aggregate. |
| Off | Accumulation continues across group boundaries. Produces a global running aggregate ignoring groups. |
Reset values by function:
| Function | Reset value |
|---|---|
running_sum | Resets to 0 |
running_avg | Resets numerator to 0 and non-null count to 0 |
running_count | Resets to 0 |
running_min | Resets to null (takes the first non-null value in the new group) |
running_max | Resets to null (takes the first non-null value in the new group) |
Filter interaction
Running aggregates are computed after filters are applied. Rows excluded by a filter are not included in the accumulation.
Implication: A running_sum with a filter Period = 2026 does not include 2025 values, even if they exist in the data source. The running total starts from the first visible (unfiltered) row.
When this is the desired behaviour: Period-specific cumulative totals (e.g. cumulative spend within the current year).
When this causes issues: If you need a running total that includes pre-filter data (e.g. a cost-to-complete that must include all prior spend regardless of year filter), use a report variable with an unfiltered expression instead.
Running aggregate vs. standard aggregate
| Concept | Running aggregate | Standard aggregate |
|---|---|---|
| Result per row | Different value per row | Same value for all rows |
| Changes with row | Yes — increases/changes with each row | No — a single summary value |
| Available in | Table columns, chart series | Table footer, KPI card, chart series |
| Use for | Cumulative trends, running floors/ceilings | Single summary statistics |
Edge cases
All values are null
If all source field values in the data range are null:
| Function | Result |
|---|---|
running_sum | 0 for all rows |
running_avg | null for all rows |
running_count | 0 for all rows |
running_min | null for all rows |
running_max | null for all rows |
Single row
A running aggregate over a single row is identical to the standard aggregate for that row.
Negative values
Running aggregates handle negative values correctly. running_sum can decrease when source values are negative.
| Row | Period Cost | running_sum |
|---|---|---|
| 1 | 100 | 100 |
| 2 | -30 | 70 |
| 3 | 50 | 120 |
Percent fields
Percent fields are stored as decimals (0.75 = 75%). Running aggregates operate on the stored decimal value, not the display percentage.
running_avg on a Percent field returns a decimal (e.g. 0.825), formatted with the % suffix as 82.5% in the output.
Component availability
| Component type | running_sum | running_avg | running_count | running_min | running_max |
|---|---|---|---|---|---|
| Table column | ✓ | ✓ | ✓ | ✓ | ✓ |
| Line chart series | ✓ | ✓ | ✓ | ✓ | ✓ |
| Bar chart series (combo) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Area chart series | ✓ | ✓ | ✓ | ✓ | ✓ |
| KPI card value | — | — | — | — | — |
| Gauge | — | — | — | — | — |
| CSV export | ✓ | ✓ | ✓ | ✓ | ✓ |
| Excel export | ✓ (as values) | ✓ (as values) | ✓ (as values) | ✓ (as values) | ✓ (as values) |
Related
- Running Aggregates — configuration guide
- Running Aggregates Tutorial — step-by-step cumulative cost trend tutorial
- Expression Reference — alternative expression-based aggregation functions
- Parameters and Calculated Fields — expression-based alternatives