diff --git a/docs/reference/query-languages/esql/_snippets/commands/layout/stats-by.md b/docs/reference/query-languages/esql/_snippets/commands/layout/stats-by.md index 4f694b9db59d0..89fcd89a4dff9 100644 --- a/docs/reference/query-languages/esql/_snippets/commands/layout/stats-by.md +++ b/docs/reference/query-languages/esql/_snippets/commands/layout/stats-by.md @@ -51,6 +51,10 @@ The following [aggregation functions](/reference/query-languages/esql/functions- :::{include} ../../lists/aggregation-functions.md ::: +When `STATS` is used under the [`TS`](/reference/query-languages/esql/commands/ts.md) source command, +[time series aggregation functions](/reference/query-languages/esql/functions-operators/time-series-aggregation-functions.md) +are also supported. + The following [grouping functions](/reference/query-languages/esql/functions-operators/grouping-functions.md) are supported: :::{include} ../../lists/grouping-functions.md diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/rate.md b/docs/reference/query-languages/esql/_snippets/functions/description/rate.md index 0de1312951f82..25471c866493c 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/rate.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/rate.md @@ -2,5 +2,5 @@ **Description** -Calculates the rate of a counter field. +Calculates the per-second average rate of increase of a [counter](docs-content://manage-data/data-store/data-streams/time-series-data-stream-tsds.md#time-series-metric). Rate calculations account for breaks in monotonicity, such as counter resets when a service restarts, and extrapolate values within each bucketed time interval. Rate is the most appropriate aggregate function for counters. It is only allowed in a [STATS](/reference/query-languages/esql/commands/stats-by.md) command under a [`TS`](/reference/query-languages/esql/commands/ts.md) source command, to be properly applied per time series. diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/absent_over_time.md b/docs/reference/query-languages/esql/_snippets/functions/layout/absent_over_time.md index 38d6822dab0b6..cd13f23decfc4 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/absent_over_time.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/absent_over_time.md @@ -3,6 +3,7 @@ ## `ABSENT_OVER_TIME` [esql-absent_over_time] ```{applies_to} stack: preview 9.2.0 +serverless: preview ``` **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/avg_over_time.md b/docs/reference/query-languages/esql/_snippets/functions/layout/avg_over_time.md index 88acfef1f7f5d..f01a5a76fd27b 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/avg_over_time.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/avg_over_time.md @@ -3,6 +3,7 @@ ## `AVG_OVER_TIME` [esql-avg_over_time] ```{applies_to} stack: preview 9.2.0 +serverless: preview ``` **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/count_distinct_over_time.md b/docs/reference/query-languages/esql/_snippets/functions/layout/count_distinct_over_time.md index 2bc1e286cab68..2d1c0f5e0384d 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/count_distinct_over_time.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/count_distinct_over_time.md @@ -3,6 +3,7 @@ ## `COUNT_DISTINCT_OVER_TIME` [esql-count_distinct_over_time] ```{applies_to} stack: preview 9.2.0 +serverless: preview ``` **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/count_over_time.md b/docs/reference/query-languages/esql/_snippets/functions/layout/count_over_time.md index 292dff0e10e06..3040e7c0f596a 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/count_over_time.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/count_over_time.md @@ -3,6 +3,7 @@ ## `COUNT_OVER_TIME` [esql-count_over_time] ```{applies_to} stack: preview 9.2.0 +serverless: preview ``` **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/first_over_time.md b/docs/reference/query-languages/esql/_snippets/functions/layout/first_over_time.md index 50462fef0d1ab..e77911f4b7627 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/first_over_time.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/first_over_time.md @@ -3,6 +3,7 @@ ## `FIRST_OVER_TIME` [esql-first_over_time] ```{applies_to} stack: preview 9.2.0 +serverless: preview ``` **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/last_over_time.md b/docs/reference/query-languages/esql/_snippets/functions/layout/last_over_time.md index 0fdb3f6c06912..1a0a2251e17de 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/last_over_time.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/last_over_time.md @@ -3,6 +3,7 @@ ## `LAST_OVER_TIME` [esql-last_over_time] ```{applies_to} stack: preview 9.2.0 +serverless: preview ``` **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/max_over_time.md b/docs/reference/query-languages/esql/_snippets/functions/layout/max_over_time.md index 4d0732a26cded..0cec101fd928b 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/max_over_time.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/max_over_time.md @@ -3,6 +3,7 @@ ## `MAX_OVER_TIME` [esql-max_over_time] ```{applies_to} stack: preview 9.2.0 +serverless: preview ``` **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/min_over_time.md b/docs/reference/query-languages/esql/_snippets/functions/layout/min_over_time.md index 3644fde260d58..3a9e14fd8901b 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/min_over_time.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/min_over_time.md @@ -3,6 +3,7 @@ ## `MIN_OVER_TIME` [esql-min_over_time] ```{applies_to} stack: preview 9.2.0 +serverless: preview ``` **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/present_over_time.md b/docs/reference/query-languages/esql/_snippets/functions/layout/present_over_time.md index 04fb44bc9f672..d7f35b92b46b8 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/present_over_time.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/present_over_time.md @@ -3,6 +3,7 @@ ## `PRESENT_OVER_TIME` [esql-present_over_time] ```{applies_to} stack: preview 9.2.0 +serverless: preview ``` **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/rate.md b/docs/reference/query-languages/esql/_snippets/functions/layout/rate.md index fc62158b7213a..f27eddd78521b 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/rate.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/rate.md @@ -3,6 +3,7 @@ ## `RATE` [esql-rate] ```{applies_to} stack: preview 9.2.0 +serverless: preview ``` **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/sum_over_time.md b/docs/reference/query-languages/esql/_snippets/functions/layout/sum_over_time.md index 647ff06f7181e..db9dd9936f0bf 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/sum_over_time.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/sum_over_time.md @@ -3,6 +3,7 @@ ## `SUM_OVER_TIME` [esql-sum_over_time] ```{applies_to} stack: preview 9.2.0 +serverless: preview ``` **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/lists/time-series-aggregation-functions.md b/docs/reference/query-languages/esql/_snippets/lists/time-series-aggregation-functions.md index 17db563e9dade..802efda2a8042 100644 --- a/docs/reference/query-languages/esql/_snippets/lists/time-series-aggregation-functions.md +++ b/docs/reference/query-languages/esql/_snippets/lists/time-series-aggregation-functions.md @@ -1,11 +1,11 @@ -* [preview] [`ABSENT_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-absent_over_time) -* [preview] [`AVG_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-avg_over_time) -* [preview] [`COUNT_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-count_over_time) -* [preview] [`COUNT_DISTINCT_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-count_distinct_over_time) -* [preview] [`FIRST_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-first_over_time) -* [preview] [`LAST_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-last_over_time) -* [preview] [`MAX_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-max_over_time) -* [preview] [`MIN_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-min_over_time) -* [preview] [`PRESENT_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-present_over_time) -* [preview] [`RATE`](../../functions-operators/time-series-aggregation-functions.md#esql-rate) -* [preview] [`SUM_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-sum_over_time) +* {applies_to}`stack: preview 9.2` {applies_to}`serverless: preview` [`ABSENT_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-absent_over_time) +* {applies_to}`stack: preview 9.2` {applies_to}`serverless: preview` [`AVG_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-avg_over_time) +* {applies_to}`stack: preview 9.2` {applies_to}`serverless: preview` [`COUNT_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-count_over_time) +* {applies_to}`stack: preview 9.2` {applies_to}`serverless: preview` [`COUNT_DISTINCT_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-count_distinct_over_time) +* {applies_to}`stack: preview 9.2` {applies_to}`serverless: preview` [`FIRST_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-first_over_time) +* {applies_to}`stack: preview 9.2` {applies_to}`serverless: preview` [`LAST_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-last_over_time) +* {applies_to}`stack: preview 9.2` {applies_to}`serverless: preview` [`MAX_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-max_over_time) +* {applies_to}`stack: preview 9.2` {applies_to}`serverless: preview` [`MIN_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-min_over_time) +* {applies_to}`stack: preview 9.2` {applies_to}`serverless: preview` [`PRESENT_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-present_over_time) +* {applies_to}`stack: preview 9.2` {applies_to}`serverless: preview` [`RATE`](../../functions-operators/time-series-aggregation-functions.md#esql-rate) +* {applies_to}`stack: preview 9.2` {applies_to}`serverless: preview` [`SUM_OVER_TIME`](../../functions-operators/time-series-aggregation-functions.md#esql-sum_over_time) diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/absent_over_time.json b/docs/reference/query-languages/esql/kibana/definition/functions/absent_over_time.json index 879918c653dda..52f43004884ae 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/absent_over_time.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/absent_over_time.json @@ -224,6 +224,6 @@ "examples" : [ "TS k8s\n| WHERE cluster == \"prod\" AND pod == \"two\"\n| STATS events_received = max(absent_over_time(events_received)) BY pod, time_bucket = tbucket(2 minute)" ], - "preview" : false, + "preview" : true, "snapshot_only" : false } diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/avg_over_time.json b/docs/reference/query-languages/esql/kibana/definition/functions/avg_over_time.json index 5f449bb6459f5..71c81f9e6713b 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/avg_over_time.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/avg_over_time.json @@ -44,6 +44,6 @@ "examples" : [ "TS k8s\n| STATS max_cost=max(avg_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)" ], - "preview" : false, + "preview" : true, "snapshot_only" : false } diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/count_distinct_over_time.json b/docs/reference/query-languages/esql/kibana/definition/functions/count_distinct_over_time.json index fd994aa15537e..0d3204f99270b 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/count_distinct_over_time.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/count_distinct_over_time.json @@ -668,6 +668,6 @@ "examples" : [ "TS k8s\n| STATS distincts=count_distinct(count_distinct_over_time(network.cost)),\n distincts_imprecise=count_distinct(count_distinct_over_time(network.cost, 100))\n BY cluster, time_bucket = bucket(@timestamp,1minute)" ], - "preview" : false, + "preview" : true, "snapshot_only" : false } diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/count_over_time.json b/docs/reference/query-languages/esql/kibana/definition/functions/count_over_time.json index efdc885ee1265..219ebe563b2c2 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/count_over_time.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/count_over_time.json @@ -224,6 +224,6 @@ "examples" : [ "TS k8s\n| STATS count=count(count_over_time(network.cost))\n BY cluster, time_bucket = bucket(@timestamp,1minute)" ], - "preview" : false, + "preview" : true, "snapshot_only" : false } diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/first_over_time.json b/docs/reference/query-languages/esql/kibana/definition/functions/first_over_time.json index 052b2a65e223c..e2cc52285e8e9 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/first_over_time.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/first_over_time.json @@ -44,6 +44,6 @@ "examples" : [ "TS k8s\n| STATS max_cost=max(first_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)" ], - "preview" : false, + "preview" : true, "snapshot_only" : false } diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/last_over_time.json b/docs/reference/query-languages/esql/kibana/definition/functions/last_over_time.json index 0c732d51ea66b..48f96880e0001 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/last_over_time.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/last_over_time.json @@ -44,6 +44,6 @@ "examples" : [ "TS k8s\n| STATS max_cost=max(last_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)" ], - "preview" : false, + "preview" : true, "snapshot_only" : false } diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/max_over_time.json b/docs/reference/query-languages/esql/kibana/definition/functions/max_over_time.json index 340e6543a4e3f..b55684e8094e4 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/max_over_time.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/max_over_time.json @@ -140,6 +140,6 @@ "examples" : [ "TS k8s\n| STATS cost=sum(max_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)" ], - "preview" : false, + "preview" : true, "snapshot_only" : false } diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/min_over_time.json b/docs/reference/query-languages/esql/kibana/definition/functions/min_over_time.json index ab34295c27765..8bc00fd660299 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/min_over_time.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/min_over_time.json @@ -140,6 +140,6 @@ "examples" : [ "TS k8s\n| STATS cost=sum(min_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)" ], - "preview" : false, + "preview" : true, "snapshot_only" : false } diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/present_over_time.json b/docs/reference/query-languages/esql/kibana/definition/functions/present_over_time.json index 87a66d4a49ef5..844663d378495 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/present_over_time.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/present_over_time.json @@ -224,6 +224,6 @@ "examples" : [ "TS k8s\n| WHERE cluster == \"prod\" AND pod == \"two\"\n| STATS events_received = max(present_over_time(events_received)) BY pod, time_bucket = tbucket(2 minute)" ], - "preview" : false, + "preview" : true, "snapshot_only" : false } diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/rate.json b/docs/reference/query-languages/esql/kibana/definition/functions/rate.json index 751619fb00472..9468b7f113ec4 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/rate.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/rate.json @@ -2,7 +2,7 @@ "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.", "type" : "time_series_agg", "name" : "rate", - "description" : "Calculates the rate of a counter field.", + "description" : "Calculates the per-second average rate of increase of a counter. Rate calculations account for breaks in monotonicity, such as counter resets when a service restarts, and extrapolate values within each bucketed time interval. Rate is the most appropriate aggregate function for counters. It is only allowed in a STATS command under a `TS` source command, to be properly applied per time series.", "signatures" : [ { "params" : [ @@ -44,6 +44,6 @@ "examples" : [ "TS k8s\n| STATS max(rate(network.total_bytes_in)) BY time_bucket = bucket(@timestamp,5minute)" ], - "preview" : false, + "preview" : true, "snapshot_only" : false } diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/sum_over_time.json b/docs/reference/query-languages/esql/kibana/definition/functions/sum_over_time.json index 2888b2caded55..85cec3677bc31 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/sum_over_time.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/sum_over_time.json @@ -44,6 +44,6 @@ "examples" : [ "TS k8s\n| STATS sum_cost=sum(sum_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)" ], - "preview" : false, + "preview" : true, "snapshot_only" : false } diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/rate.md b/docs/reference/query-languages/esql/kibana/docs/functions/rate.md index 66cbfffb695ab..bf8504018d01b 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/rate.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/rate.md @@ -1,7 +1,7 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it. ### RATE -Calculates the rate of a counter field. +Calculates the per-second average rate of increase of a [counter](docs-content://manage-data/data-store/data-streams/time-series-data-stream-tsds.md#time-series-metric). Rate calculations account for breaks in monotonicity, such as counter resets when a service restarts, and extrapolate values within each bucketed time interval. Rate is the most appropriate aggregate function for counters. It is only allowed in a [STATS](https://www.elastic.co/docs/reference/query-languages/esql/commands/stats-by) command under a [`TS`](https://www.elastic.co/docs/reference/query-languages/esql/commands/ts) source command, to be properly applied per time series. ```esql TS k8s diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/AbsentOverTime.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/AbsentOverTime.java index bc0e6eff72ec3..072d98a461855 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/AbsentOverTime.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/AbsentOverTime.java @@ -41,6 +41,7 @@ public class AbsentOverTime extends TimeSeriesAggregateFunction { returnType = { "boolean" }, description = "Calculates the absence of a field in the output result over time range.", appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") }, + preview = true, examples = { @Example(file = "k8s-timeseries", tag = "absent_over_time") } ) public AbsentOverTime( diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/AvgOverTime.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/AvgOverTime.java index b1c92c3f6dafd..bfe68696e5806 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/AvgOverTime.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/AvgOverTime.java @@ -43,6 +43,7 @@ public class AvgOverTime extends TimeSeriesAggregateFunction implements Surrogat description = "Calculates the average over time of a numeric field.", type = FunctionType.TIME_SERIES_AGGREGATE, appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") }, + preview = true, examples = { @Example(file = "k8s-timeseries", tag = "avg_over_time") } ) public AvgOverTime( diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/CountDistinctOverTime.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/CountDistinctOverTime.java index f1cce3c144f4f..2396e4e69bad8 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/CountDistinctOverTime.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/CountDistinctOverTime.java @@ -42,6 +42,7 @@ public class CountDistinctOverTime extends TimeSeriesAggregateFunction implement returnType = { "long" }, description = "Calculates the count of distinct values over time for a field.", appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") }, + preview = true, examples = { @Example(file = "k8s-timeseries", tag = "count_distinct_over_time") } ) public CountDistinctOverTime( diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/CountOverTime.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/CountOverTime.java index c392e7438620b..0d75c1f082f74 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/CountOverTime.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/CountOverTime.java @@ -41,6 +41,7 @@ public class CountOverTime extends TimeSeriesAggregateFunction { returnType = { "long" }, description = "Calculates the count over time value of a field.", appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") }, + preview = true, examples = { @Example(file = "k8s-timeseries", tag = "count_over_time") } ) public CountOverTime( diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Delta.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Delta.java index 4e1ae09f936e8..d6455990299a4 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Delta.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Delta.java @@ -45,7 +45,8 @@ public class Delta extends TimeSeriesAggregateFunction implements OptionalArgume type = FunctionType.TIME_SERIES_AGGREGATE, returnType = { "double" }, description = "Calculates the absolute change of a gauge field in a time window.", - appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.UNAVAILABLE) }, + appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") }, + preview = true, note = "Available with the [TS](/reference/query-languages/esql/commands/source-commands.md#esql-ts) command" ) public Delta(Source source, @Param(name = "field", type = { "long", "integer", "double" }) Expression field) { diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/FirstOverTime.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/FirstOverTime.java index 908d4bd97cc32..ca76d521142c7 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/FirstOverTime.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/FirstOverTime.java @@ -53,6 +53,7 @@ public class FirstOverTime extends TimeSeriesAggregateFunction implements Option returnType = { "long", "integer", "double" }, description = "Calculates the earliest value of a field, where recency determined by the `@timestamp` field.", appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") }, + preview = true, examples = { @Example(file = "k8s-timeseries", tag = "first_over_time") } ) public FirstOverTime(Source source, @Param(name = "field", type = { "long", "integer", "double" }) Expression field) { diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Idelta.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Idelta.java index 0553a265b0572..bfd70f17df693 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Idelta.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Idelta.java @@ -47,7 +47,8 @@ public class Idelta extends TimeSeriesAggregateFunction implements OptionalArgum description = "Calculates the idelta of a gauge. idelta is the absolute change between the last two data points (" + "it ignores all but the last two data points in each time period). " + "This function is very similar to delta, but is more responsive to recent changes.", - appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") } + appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") }, + preview = true ) public Idelta(Source source, @Param(name = "field", type = { "long", "integer", "double" }) Expression field) { this(source, field, new UnresolvedAttribute(source, "@timestamp")); diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Increase.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Increase.java index e490ffad181ec..cfdb3123685b6 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Increase.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Increase.java @@ -50,7 +50,8 @@ public class Increase extends TimeSeriesAggregateFunction implements OptionalArg type = FunctionType.TIME_SERIES_AGGREGATE, returnType = { "double" }, description = "Calculates the absolute increase of a counter field in a time window.", - appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") } + appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") }, + preview = true ) public Increase( Source source, diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Irate.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Irate.java index 2195e814e9d4a..3705b3e0a496f 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Irate.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Irate.java @@ -48,6 +48,7 @@ public class Irate extends TimeSeriesAggregateFunction implements OptionalArgume + "it ignores all but the last two data points in each time period). " + "This function is very similar to rate, but is more responsive to recent changes in the rate of increase.", appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") }, + preview = true, examples = { @Example(file = "k8s-timeseries", tag = "irate") } ) public Irate(Source source, @Param(name = "field", type = { "counter_long", "counter_integer", "counter_double" }) Expression field) { diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/LastOverTime.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/LastOverTime.java index 07c7dc988dcba..ccb9695339891 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/LastOverTime.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/LastOverTime.java @@ -54,6 +54,7 @@ public class LastOverTime extends TimeSeriesAggregateFunction implements Optiona returnType = { "long", "integer", "double", "_tsid" }, description = "Calculates the latest value of a field, where recency determined by the `@timestamp` field.", appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") }, + preview = true, examples = { @Example(file = "k8s-timeseries", tag = "last_over_time") } ) public LastOverTime(Source source, @Param(name = "field", type = { "long", "integer", "double", "_tsid" }) Expression field) { diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MaxOverTime.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MaxOverTime.java index 5550d8709aaeb..2bc011eecfc36 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MaxOverTime.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MaxOverTime.java @@ -41,6 +41,7 @@ public class MaxOverTime extends TimeSeriesAggregateFunction { description = "Calculates the maximum over time value of a field.", type = FunctionType.TIME_SERIES_AGGREGATE, appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") }, + preview = true, examples = { @Example(file = "k8s-timeseries", tag = "max_over_time") } ) public MaxOverTime( diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MinOverTime.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MinOverTime.java index 56d3f66239c93..3258688cb1844 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MinOverTime.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MinOverTime.java @@ -41,6 +41,7 @@ public class MinOverTime extends TimeSeriesAggregateFunction { description = "Calculates the minimum over time value of a field.", type = FunctionType.TIME_SERIES_AGGREGATE, appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") }, + preview = true, examples = { @Example(file = "k8s-timeseries", tag = "min_over_time") } ) public MinOverTime( diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/PresentOverTime.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/PresentOverTime.java index d27d172ae6dfc..805a4b09d6da5 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/PresentOverTime.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/PresentOverTime.java @@ -41,6 +41,7 @@ public class PresentOverTime extends TimeSeriesAggregateFunction { returnType = { "boolean" }, description = "Calculates the presence of a field in the output result over time range.", appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") }, + preview = true, examples = { @Example(file = "k8s-timeseries", tag = "present_over_time") } ) public PresentOverTime( diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Rate.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Rate.java index c9e4a2eb68e15..a3406959931be 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Rate.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Rate.java @@ -44,10 +44,17 @@ public class Rate extends TimeSeriesAggregateFunction implements OptionalArgumen @FunctionInfo( type = FunctionType.TIME_SERIES_AGGREGATE, returnType = { "double" }, - description = "Calculates the rate of a counter field.", + description = "Calculates the per-second average rate of increase of a" + + " [counter](docs-content://manage-data/data-store/data-streams/time-series-data-stream-tsds.md#time-series-metric). " + + "Rate calculations account for breaks in monotonicity, such as counter resets when a service restarts, and extrapolate " + + "values within each bucketed time interval. Rate is the most appropriate aggregate function for counters. It is only allowed " + + "in a [STATS](/reference/query-languages/esql/commands/stats-by.md) command under a " + + "[`TS`](/reference/query-languages/esql/commands/ts.md) source command, to be properly applied per time series.", appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") }, + preview = true, examples = { @Example(file = "k8s-timeseries", tag = "rate") } ) + public Rate(Source source, @Param(name = "field", type = { "counter_long", "counter_integer", "counter_double" }) Expression field) { this(source, field, new UnresolvedAttribute(source, "@timestamp")); } diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/SumOverTime.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/SumOverTime.java index 14b125e6c7b87..c8968a63b38dd 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/SumOverTime.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/SumOverTime.java @@ -41,6 +41,7 @@ public class SumOverTime extends TimeSeriesAggregateFunction { description = "Calculates the sum over time value of a field.", type = FunctionType.TIME_SERIES_AGGREGATE, appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") }, + preview = true, examples = { @Example(file = "k8s-timeseries", tag = "sum_over_time") } ) public SumOverTime(