Loading

ES|QL time series aggregation functions

The first STATS under a 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). 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:

TS metrics
  | WHERE TRANGE(1h)
  | STATS AVG(RATE(requests, 10m)) BY TBUCKET(1m), host

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.

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.

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 grouping function ( ). Refer to Grouping time series for details and examples.

The inner function you pick depends on the field's metric_type mapping:

  • Counters: monotonically increasing values that reset on process restart. Use RATE, 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 (the implicit default when no inner function is given), AVG_OVER_TIME, 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.

The following time series aggregation functions are supported:

  • ABSENT_OVER_TIME

    Calculates the absence of a field over a time range.

  • AVG_OVER_TIME

    Calculates the average over time of a numeric field.

  • COUNT_OVER_TIME

    Calculates the count over time value of a field.

  • COUNT_DISTINCT_OVER_TIME

    Calculates the count of distinct values over time for a field.

  • DELTA

    Calculates the absolute change of a gauge field in a time window.

  • DERIV

    Calculates the derivative over time of a numeric field using linear regression.

  • FIRST_OVER_TIME

    Calculates the earliest value of a field over a time window.

  • IDELTA

    Calculates the absolute change between the last two data points of a gauge.

  • INCREASE

    Calculates the absolute increase of a counter field in a time window.

  • IRATE

    Calculates the per-second rate of increase between the last two data points.

  • LAST_OVER_TIME

    Calculates the latest value of a field over a time window.

  • MAX_OVER_TIME

    Calculates the maximum value of a field over a time window.

  • MIN_OVER_TIME

    Calculates the minimum value of a field over a time window.

  • PERCENTILE_OVER_TIME

    Calculates the percentile over time of a field.

  • PRESENT_OVER_TIME

    Calculates the presence of a field over a time range.

  • RATE

    Calculates the per-second average rate of increase of a counter.

  • STDDEV_OVER_TIME

    Calculates the population standard deviation over time of a numeric field.

  • SUM_OVER_TIME

    Calculates the sum over time value of a field.

  • VARIANCE_OVER_TIME

    Calculates the population variance over time of a numeric field.