---
title: ES|QL time series aggregation functions
description: The first STATS under a TS source command supports aggregation functions per time series. These functions accept up to two arguments. The first argument...
url: https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions
products:
  - Elasticsearch
applies_to:
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available since 9.4, Preview from 9.2 to 9.3
---

# ES|QL time series aggregation functions
The first [`STATS`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/commands/stats-by) under a [`TS`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/commands/ts) source command supports
aggregation functions per time series. These functions accept up to two arguments.
The first argument is required and denotes the metric name of the time series.
The second argument is optional and allows specifying a sliding time window for
aggregating metric values. Note that this is orthogonal to time bucketing of
output results, as specified in the BY clause (e.g. through
[`TBUCKET`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/grouping-functions/tbucket)).
For example, the following query calculates the average rate of requests per
host for every minute, using values over a sliding window of 10 minutes:
```esql
TS metrics
  | WHERE TRANGE(1h)
  | STATS AVG(RATE(requests, 10m)) BY TBUCKET(1m), host
```

<applies-switch>
  <applies-item title="stack: preview 9.2-9.3" applies-to="Elastic Stack: Preview from 9.2 to 9.3">
    Accepted window values are currently limited to multiples of the time bucket
    interval in the BY clause. If no window is specified, the time bucket interval
    is implicitly used as a window.
  </applies-item>

  <applies-item title="stack: ga 9.4+" applies-to="Elastic Stack: Generally available since 9.4">
    All window values are accepted, though there are performance optimizations for
    the cases where the window is a multiple of the time bucket interval.It's currently not allowed to mix windows that are smaller than the time bucket
    for one metrics and larger than the time bucket for another metrics, in the same
    query.
  </applies-item>
</applies-switch>

When a time series aggregation function is used **directly** in `STATS` (that is, not
wrapped in an outer aggregation such as `AVG()` or `SUM()`), results are implicitly
grouped by every time series dimension and include a `_timeseries` column. You can
narrow or make this grouping explicit with the
[`WITHOUT`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/grouping-functions/without)
grouping function (<applies-to>Elastic Stack: Generally available since 9.4</applies-to>). Refer to
[Grouping time series](/elastic/docs-builder/docs/3400/reference/query-languages/esql/commands/ts#grouping-time-series)
for details and examples.

## Metric type compatibility

The inner function you pick depends on the field's
[`metric_type`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3400/manage-data/data-store/data-streams/time-series-data-stream-tsds#time-series-metric)
mapping:
- **Counters**: monotonically increasing values that reset on process restart. Use
  [`RATE`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/rate),
  [`INCREASE`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/increase),
  and the other counter-aware functions. These detect resets per time series and compute
  correct deltas; applying a gauge-only function such as `AVG_OVER_TIME` to a counter is
  rarely what you want.
- **Gauges**: point-in-time values that can move up or down. Use
  [`LAST_OVER_TIME`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/last_over_time)
  (the implicit default when no inner function is given),
  [`AVG_OVER_TIME`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/avg_over_time),
  [`MAX_OVER_TIME`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/max_over_time),
  and the other `*_OVER_TIME` variants. Counter functions like `RATE` reject gauge fields.

For the conceptual context behind the counter/gauge split, refer to
[When to use TS vs FROM](/elastic/docs-builder/docs/3400/reference/query-languages/esql/commands/ts#when-to-use-ts-vs-from).
The following time series aggregation functions are supported:
- [`ABSENT_OVER_TIME`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/absent_over_time) <applies-to>Elastic Stack: Preview since 9.2</applies-to> <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
- [`AVG_OVER_TIME`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/avg_over_time) <applies-to>Elastic Stack: Preview since 9.2</applies-to> <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
- [`COUNT_OVER_TIME`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/count_over_time) <applies-to>Elastic Stack: Preview since 9.2</applies-to> <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
- [`COUNT_DISTINCT_OVER_TIME`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/count_distinct_over_time) <applies-to>Elastic Stack: Preview since 9.2</applies-to> <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
- [`DELTA`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/delta) <applies-to>Elastic Stack: Preview since 9.2</applies-to> <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
- [`DERIV`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/deriv) <applies-to>Elastic Stack: Preview since 9.3</applies-to>
- [`FIRST_OVER_TIME`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/first_over_time) <applies-to>Elastic Stack: Preview since 9.2</applies-to> <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
- [`IDELTA`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/idelta) <applies-to>Elastic Stack: Preview since 9.2</applies-to> <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
- [`INCREASE`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/increase) <applies-to>Elastic Stack: Preview since 9.2</applies-to> <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
- [`IRATE`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/irate) <applies-to>Elastic Stack: Preview since 9.2</applies-to> <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
- [`LAST_OVER_TIME`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/last_over_time) <applies-to>Elastic Stack: Preview since 9.2</applies-to> <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
- [`MAX_OVER_TIME`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/max_over_time) <applies-to>Elastic Stack: Preview since 9.2</applies-to> <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
- [`MIN_OVER_TIME`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/min_over_time) <applies-to>Elastic Stack: Preview since 9.2</applies-to> <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
- [`PERCENTILE_OVER_TIME`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/percentile_over_time) <applies-to>Elastic Stack: Preview since 9.3</applies-to>
- [`PRESENT_OVER_TIME`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/present_over_time) <applies-to>Elastic Stack: Preview since 9.2</applies-to> <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
- [`RATE`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/rate) <applies-to>Elastic Stack: Preview since 9.2</applies-to> <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
- [`STDDEV_OVER_TIME`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/stddev_over_time) <applies-to>Elastic Stack: Preview since 9.3</applies-to>
- [`SUM_OVER_TIME`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/sum_over_time) <applies-to>Elastic Stack: Preview since 9.2</applies-to> <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
- [`VARIANCE_OVER_TIME`](https://www.elastic.co/elastic/docs-builder/docs/3400/reference/query-languages/esql/functions-operators/time-series-aggregation-functions/variance_over_time) <applies-to>Elastic Stack: Preview since 9.3</applies-to>