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 [`TS`](/reference/query-languages/esql/commands/ts.md) source command,
+[time series aggregate 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/Rate.java

@@ -44,10 +44,16 @@ 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 use extrapolation"
+            + " for each time bucketing 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") },
         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"));
     }