# running_total

> AQL Function: Calculate a metric from starting of time (visible data by default) to the current period

## Definition
Calculate a metric from the starting of time to the current period. This function is used to calculate a running total of a metric along specified dimensions.

By default, the running total will be calculated after filtering (`keep_filters: true`). To calculate a running total of all data, ignoring any filter on the running dimensions, you can add a `keep_filters: false` parameter to the function. Here is a comparison between `keep_filters: true` and `keep_filters: false`:

**Syntax**
```aml
running_total(measure)
running_total(measure, running_dimension, ...)
running_total(measure, running_dimension, ..., keep_filters: false)
running_total(measure, running_dimension, ..., fill_missing: true)
```

```aml title="Examples"
running_total(orders.total_orders, orders.created_at)

// with pipe
orders.total_orders | running_total(orders.created_at | year())

// with multiple running dimensions
running_total(orders.total_orders, orders.created_at, orders.status)

// with keep_filters: false
running_total(orders.total_orders, orders.created_at, keep_filters: false)

// fill missing values due to pivot
running_total(orders.total_orders, orders.created_at, fill_missing: true)
```

**Input**

- `measure`: The measure that you want to turn into a running measure.
- `running_dimension` (**optional**, **repeatable**): The dimension you want your aggregation to run along. If not specified, the returned measure will run along all date dimensions that in your exploration
- `keep_filters:` (**optional**): A boolean value that specifies whether to keep the filters applied on the running dimensions. Default is `true`.
- `fill_missing` (**optional**): A boolean value that specifies whether to fill the missing values due to pivot mechanism. Default is `false`

**Output**

New measure that runs along the specified dimension(s)

## Sample Usages {#sample-usages}

In the following examples, let’s assume that we have an `orders` model with the following fields

```aml
Model orders {
  dimension id {}
  dimension created_at {}

  measure total_orders {
    definition: @aql count(orders.id);;
  }
}
```

#### Simple running sum
Below is an example of how to define a running total measure to calculate cumulative orders on a monthly basis
```aml
orders.total_orders | running_total(orders.created_at)
```

#### Running dimension is not included in exploration
If the specified running dimension is not included in the exploration, the returned value will be the same as the original measure before applying the `running_total()` function
```aml
orders.total_orders | running_total(orders.created_at)
```

#### Running dimension is coarser than grouping dimensions

You have a running total metric that runs along a time dimension in `year` grain as below

```aml
orders.total_orders | running_total(orders.created_at | year())
```

If the dimension included in the exploration has a finer granularity than the specified running dimension, the value will be repeated for any record that shares the same coarser granularity

In this case, the running total will still be calculated for the whole year, and the yearly value will be repeated for every month existing in the data:

#### Fill missing values due to Pivot mechanism

For example, you have a table with `order statuses` and `order dates`, running totals are only calculated for the statuses present on a given day in table form (it can’t fill missing statuses because there are no rows for them)

![](https://media.holistics.io/71afe25f-missing-values.png)

To fill missing values in this case, you can use `fill_missing: true`

```ts
running_total(
  total_orders,
  fill_missing: true
)
```

![](https://media.holistics.io/f872c9cd-fill-missing.png)

## See also

- [`period_to_date()`](/reference/aql/period_to_date)
- [`exact_period()`](/reference/aql/exact_period)
- [`relative_period()`](/reference/aql/relative_period)
- [`trailing_period()`](/reference/aql/trailing_period)
- [Time Comparisons](/as-code/aql/learn/time-comparisons)