Time-series docs changes

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 nested 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

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)

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(

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(

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(

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(

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) {

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) {

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"));

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,

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) {

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) {

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(

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(

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(

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 changes 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"));
     }

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(