Add doc for min/max_over_time (#130269)

Add the initial docs structure for the TS command and time-series aggregation.
More content will be added later.

docs/reference/query-languages/esql/_snippets/commands/layout/ts.md

@@ -0,0 +1,28 @@
+## `TS` [esql-ts]
+
+The `TS` command is similar to the `FROM` source command,
+but with two key differences: it targets only [time-series indices](docs-content://manage-data/data-store/data-streams/time-series-data-stream-tsds.md)
+and enables the use of time-series aggregation functions
+with the [STATS](/reference/query-languages/esql/commands/processing-commands.md#esql-stats-by) command.
+
+**Syntax**
+
+```esql
+TS index_pattern [METADATA fields]
+```
+
+**Parameters**
+
+`index_pattern`
+:   A list of indices, data streams or aliases. Supports wildcards and date math.
+
+`fields`
+:   A comma-separated list of [metadata fields](/reference/query-languages/esql/esql-metadata-fields.md) to retrieve.
+
+**Examples**
+
+```esql
+TS metrics
+| STATS sum(last_over_time(memory_usage))
+```
+

docs/reference/query-languages/esql/_snippets/functions/description/avg_over_time.md

@@ -0,0 +1,11 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Description**
+
+The average over time of a numeric field.
+
+::::{note}
+Available with the [TS](/reference/query-languages/esql/commands/source-commands.md#esql-ts) command in snapshot builds
+::::
+
+

docs/reference/query-languages/esql/_snippets/functions/description/max_over_time.md

@@ -0,0 +1,11 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Description**
+
+The maximum over time value of a field.
+
+::::{note}
+Available with the [TS](/reference/query-languages/esql/commands/source-commands.md#esql-ts) command in snapshot builds
+::::
+
+

docs/reference/query-languages/esql/_snippets/functions/description/min_over_time.md

@@ -0,0 +1,11 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Description**
+
+The minimum over time value of a field.
+
+::::{note}
+Available with the [TS](/reference/query-languages/esql/commands/source-commands.md#esql-ts) command in snapshot builds
+::::
+
+

docs/reference/query-languages/esql/_snippets/functions/examples/avg_over_time.md

@@ -0,0 +1,17 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Example**
+
+```esql
+TS k8s
+| STATS max_cost=max(avg_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
+```
+
+| max_cost:double | cluster:keyword | time_bucket:datetime |
+| --- | --- | --- |
+| 12.375 | prod | 2024-05-10T00:17:00.000Z |
+| 12.375 | qa | 2024-05-10T00:01:00.000Z |
+| 12.25 | prod | 2024-05-10T00:19:00.000Z |
+| 12.0625 | qa | 2024-05-10T00:06:00.000Z |
+
+

docs/reference/query-languages/esql/_snippets/functions/examples/max_over_time.md

@@ -0,0 +1,17 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Example**
+
+```esql
+TS k8s
+| STATS cost=sum(max_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
+```
+
+| cost:double | cluster:keyword | time_bucket:datetime |
+| --- | --- | --- |
+| 32.75 | qa | 2024-05-10T00:17:00.000Z |
+| 32.25 | staging | 2024-05-10T00:09:00.000Z |
+| 31.75 | qa | 2024-05-10T00:06:00.000Z |
+| 29.0 | prod | 2024-05-10T00:19:00.000Z |
+
+

docs/reference/query-languages/esql/_snippets/functions/examples/min_over_time.md

@@ -0,0 +1,16 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Example**
+
+```esql
+TS k8s
+| STATS cost=sum(min_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
+```
+
+| cost:double | cluster:keyword | time_bucket:datetime |
+| --- | --- | --- |
+| 29.0 | prod | 2024-05-10T00:19:00.000Z |
+| 27.625 | qa | 2024-05-10T00:06:00.000Z |
+| 24.25 | qa | 2024-05-10T00:09:00.000Z |
+
+

docs/reference/query-languages/esql/_snippets/functions/layout/avg_over_time.md

@@ -0,0 +1,26 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+## `AVG_OVER_TIME` [esql-avg_over_time]
+```{applies_to}
+stack: unavailable
+```
+
+**Syntax**
+
+:::{image} ../../../images/functions/avg_over_time.svg
+:alt: Embedded
+:class: text-center
+:::
+
+
+:::{include} ../parameters/avg_over_time.md
+:::
+
+:::{include} ../description/avg_over_time.md
+:::
+
+:::{include} ../types/avg_over_time.md
+:::
+
+:::{include} ../examples/avg_over_time.md
+:::

docs/reference/query-languages/esql/_snippets/functions/layout/max_over_time.md

@@ -0,0 +1,26 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+## `MAX_OVER_TIME` [esql-max_over_time]
+```{applies_to}
+stack: unavailable
+```
+
+**Syntax**
+
+:::{image} ../../../images/functions/max_over_time.svg
+:alt: Embedded
+:class: text-center
+:::
+
+
+:::{include} ../parameters/max_over_time.md
+:::
+
+:::{include} ../description/max_over_time.md
+:::
+
+:::{include} ../types/max_over_time.md
+:::
+
+:::{include} ../examples/max_over_time.md
+:::

docs/reference/query-languages/esql/_snippets/functions/layout/min_over_time.md

@@ -0,0 +1,26 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+## `MIN_OVER_TIME` [esql-min_over_time]
+```{applies_to}
+stack: unavailable
+```
+
+**Syntax**
+
+:::{image} ../../../images/functions/min_over_time.svg
+:alt: Embedded
+:class: text-center
+:::
+
+
+:::{include} ../parameters/min_over_time.md
+:::
+
+:::{include} ../description/min_over_time.md
+:::
+
+:::{include} ../types/min_over_time.md
+:::
+
+:::{include} ../examples/min_over_time.md
+:::

docs/reference/query-languages/esql/_snippets/functions/parameters/avg_over_time.md

@@ -0,0 +1,7 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Parameters**
+
+`number`
+:   Expression that outputs values to average.
+

docs/reference/query-languages/esql/_snippets/functions/parameters/max_over_time.md

@@ -0,0 +1,7 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Parameters**
+
+`field`
+:   
+

docs/reference/query-languages/esql/_snippets/functions/parameters/min_over_time.md

@@ -0,0 +1,7 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Parameters**
+
+`field`
+:   
+

docs/reference/query-languages/esql/_snippets/functions/types/avg_over_time.md

@@ -0,0 +1,10 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Supported types**
+
+| number | result |
+| --- | --- |
+| double | double |
+| integer | double |
+| long | double |
+

docs/reference/query-languages/esql/_snippets/functions/types/max_over_time.md

@@ -0,0 +1,17 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Supported types**
+
+| field | result |
+| --- | --- |
+| boolean | boolean |
+| date | date |
+| date_nanos | date_nanos |
+| double | double |
+| integer | integer |
+| ip | ip |
+| keyword | keyword |
+| long | long |
+| text | keyword |
+| version | version |
+

docs/reference/query-languages/esql/_snippets/functions/types/min_over_time.md

@@ -0,0 +1,17 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Supported types**
+
+| field | result |
+| --- | --- |
+| boolean | boolean |
+| date | date |
+| date_nanos | date_nanos |
+| double | double |
+| integer | integer |
+| ip | ip |
+| keyword | keyword |
+| long | long |
+| text | keyword |
+| version | version |
+

docs/reference/query-languages/esql/_snippets/lists/aggregation-functions.md

@@ -1,10 +1,13 @@
 * [`AVG`](../../functions-operators/aggregation-functions.md#esql-avg)
+* [unavailable] [`AVG_OVER_TIME`](../../functions-operators/aggregation-functions.md#esql-avg_over_time)
 * [`COUNT`](../../functions-operators/aggregation-functions.md#esql-count)
 * [`COUNT_DISTINCT`](../../functions-operators/aggregation-functions.md#esql-count_distinct)
 * [`MAX`](../../functions-operators/aggregation-functions.md#esql-max)
+* [unavailable] [`MAX_OVER_TIME`](../../functions-operators/aggregation-functions.md#esql-max_over_time)
 * [`MEDIAN`](../../functions-operators/aggregation-functions.md#esql-median)
 * [`MEDIAN_ABSOLUTE_DEVIATION`](../../functions-operators/aggregation-functions.md#esql-median_absolute_deviation)
 * [`MIN`](../../functions-operators/aggregation-functions.md#esql-min)
+* [unavailable] [`MIN_OVER_TIME`](../../functions-operators/aggregation-functions.md#esql-min_over_time)
 * [`PERCENTILE`](../../functions-operators/aggregation-functions.md#esql-percentile)
 * [preview] [`ST_CENTROID_AGG`](../../functions-operators/aggregation-functions.md#esql-st_centroid_agg)
 * [preview] [`ST_EXTENT_AGG`](../../functions-operators/aggregation-functions.md#esql-st_extent_agg)

docs/reference/query-languages/esql/_snippets/lists/source-commands.md

@@ -1,3 +1,4 @@
 * [`FROM`](../../commands/source-commands.md#esql-from)
+* [`TS`](../../commands/source-commands.md#esql-ts)
 * [`ROW`](../../commands/source-commands.md#esql-row)
 * [`SHOW`](../../commands/source-commands.md#esql-show)

docs/reference/query-languages/esql/commands/source-commands.md

@@ -20,6 +20,9 @@ An {{esql}} source command produces a table, typically with data from {{es}}. An
 :::{include} ../_snippets/commands/layout/from.md
 :::
 
+:::{include} ../_snippets/commands/layout/ts.md
+:::
+
 :::{include} ../_snippets/commands/layout/row.md
 :::
 

docs/reference/query-languages/esql/functions-operators/aggregation-functions.md

@@ -15,6 +15,9 @@ The [`STATS`](/reference/query-languages/esql/commands/processing-commands.md#es
 :::{include} ../_snippets/functions/layout/avg.md
 :::
 
+:::{include} ../_snippets/functions/layout/avg_over_time.md
+:::
+
 :::{include} ../_snippets/functions/layout/count.md
 :::
 
@@ -24,6 +27,9 @@ The [`STATS`](/reference/query-languages/esql/commands/processing-commands.md#es
 :::{include} ../_snippets/functions/layout/max.md
 :::
 
+:::{include} ../_snippets/functions/layout/max_over_time.md
+:::
+
 :::{include} ../_snippets/functions/layout/median.md
 :::
 
@@ -33,6 +39,9 @@ The [`STATS`](/reference/query-languages/esql/commands/processing-commands.md#es
 :::{include} ../_snippets/functions/layout/min.md
 :::
 
+:::{include} ../_snippets/functions/layout/min_over_time.md
+:::
+
 :::{include} ../_snippets/functions/layout/percentile.md
 :::
 

docs/reference/query-languages/esql/images/functions/avg_over_time.svg

@@ -0,0 +1 @@
+<svg version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" width="372" height="46" viewbox="0 0 372 46"><defs><style type="text/css">.c{fill:none;stroke:#222222;}.k{fill:#000000;font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;font-size:20px;}.s{fill:#e4f4ff;stroke:#222222;}.syn{fill:#8D8D8D;font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;font-size:20px;}</style></defs><path class="c" d="M0 31h5m176 0h10m32 0h10m92 0h10m32 0h5"/><rect class="s" x="5" y="5" width="176" height="36"/><text class="k" x="15" y="31">AVG_OVER_TIME</text><rect class="s" x="191" y="5" width="32" height="36" rx="7"/><text class="syn" x="201" y="31">(</text><rect class="s" x="233" y="5" width="92" height="36" rx="7"/><text class="k" x="243" y="31">number</text><rect class="s" x="335" y="5" width="32" height="36" rx="7"/><text class="syn" x="345" y="31">)</text></svg>

docs/reference/query-languages/esql/images/functions/max_over_time.svg

@@ -0,0 +1 @@
+<svg version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" width="360" height="46" viewbox="0 0 360 46"><defs><style type="text/css">.c{fill:none;stroke:#222222;}.k{fill:#000000;font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;font-size:20px;}.s{fill:#e4f4ff;stroke:#222222;}.syn{fill:#8D8D8D;font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;font-size:20px;}</style></defs><path class="c" d="M0 31h5m176 0h10m32 0h10m80 0h10m32 0h5"/><rect class="s" x="5" y="5" width="176" height="36"/><text class="k" x="15" y="31">MAX_OVER_TIME</text><rect class="s" x="191" y="5" width="32" height="36" rx="7"/><text class="syn" x="201" y="31">(</text><rect class="s" x="233" y="5" width="80" height="36" rx="7"/><text class="k" x="243" y="31">field</text><rect class="s" x="323" y="5" width="32" height="36" rx="7"/><text class="syn" x="333" y="31">)</text></svg>

docs/reference/query-languages/esql/images/functions/min_over_time.svg

@@ -0,0 +1 @@
+<svg version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" width="360" height="46" viewbox="0 0 360 46"><defs><style type="text/css">.c{fill:none;stroke:#222222;}.k{fill:#000000;font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;font-size:20px;}.s{fill:#e4f4ff;stroke:#222222;}.syn{fill:#8D8D8D;font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;font-size:20px;}</style></defs><path class="c" d="M0 31h5m176 0h10m32 0h10m80 0h10m32 0h5"/><rect class="s" x="5" y="5" width="176" height="36"/><text class="k" x="15" y="31">MIN_OVER_TIME</text><rect class="s" x="191" y="5" width="32" height="36" rx="7"/><text class="syn" x="201" y="31">(</text><rect class="s" x="233" y="5" width="80" height="36" rx="7"/><text class="k" x="243" y="31">field</text><rect class="s" x="323" y="5" width="32" height="36" rx="7"/><text class="syn" x="333" y="31">)</text></svg>

docs/reference/query-languages/esql/kibana/definition/functions/avg_over_time.json

@@ -0,0 +1,50 @@
+{
+  "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" : "avg_over_time",
+  "description" : "The average over time of a numeric field.",
+  "note" : "Available with the TS command in snapshot builds",
+  "signatures" : [
+    {
+      "params" : [
+        {
+          "name" : "number",
+          "type" : "double",
+          "optional" : false,
+          "description" : "Expression that outputs values to average."
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "double"
+    },
+    {
+      "params" : [
+        {
+          "name" : "number",
+          "type" : "integer",
+          "optional" : false,
+          "description" : "Expression that outputs values to average."
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "double"
+    },
+    {
+      "params" : [
+        {
+          "name" : "number",
+          "type" : "long",
+          "optional" : false,
+          "description" : "Expression that outputs values to average."
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "double"
+    }
+  ],
+  "examples" : [
+    "TS k8s\n| STATS max_cost=max(avg_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)"
+  ],
+  "preview" : false,
+  "snapshot_only" : true
+}

docs/reference/query-languages/esql/kibana/definition/functions/max_over_time.json

@@ -0,0 +1,134 @@
+{
+  "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" : "max_over_time",
+  "description" : "The maximum over time value of a field.",
+  "note" : "Available with the TS command in snapshot builds",
+  "signatures" : [
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "boolean",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "boolean"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "date",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "date"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "date_nanos",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "date_nanos"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "double",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "double"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "integer",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "integer"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "ip",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "ip"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "keyword",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "keyword"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "long",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "long"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "text",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "keyword"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "version",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "version"
+    }
+  ],
+  "examples" : [
+    "TS k8s\n| STATS cost=sum(max_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)"
+  ],
+  "preview" : false,
+  "snapshot_only" : true
+}

docs/reference/query-languages/esql/kibana/definition/functions/min_over_time.json

@@ -0,0 +1,134 @@
+{
+  "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" : "min_over_time",
+  "description" : "The minimum over time value of a field.",
+  "note" : "Available with the TS command in snapshot builds",
+  "signatures" : [
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "boolean",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "boolean"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "date",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "date"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "date_nanos",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "date_nanos"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "double",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "double"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "integer",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "integer"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "ip",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "ip"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "keyword",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "keyword"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "long",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "long"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "text",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "keyword"
+    },
+    {
+      "params" : [
+        {
+          "name" : "field",
+          "type" : "version",
+          "optional" : false,
+          "description" : ""
+        }
+      ],
+      "variadic" : false,
+      "returnType" : "version"
+    }
+  ],
+  "examples" : [
+    "TS k8s\n| STATS cost=sum(min_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)"
+  ],
+  "preview" : false,
+  "snapshot_only" : true
+}

docs/reference/query-languages/esql/kibana/docs/functions/avg_over_time.md

@@ -0,0 +1,10 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+### AVG OVER TIME
+The average over time of a numeric field.
+
+```esql
+TS k8s
+| STATS max_cost=max(avg_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
+```
+Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds

docs/reference/query-languages/esql/kibana/docs/functions/max_over_time.md

@@ -0,0 +1,10 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+### MAX OVER TIME
+The maximum over time value of a field.
+
+```esql
+TS k8s
+| STATS cost=sum(max_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
+```
+Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds

docs/reference/query-languages/esql/kibana/docs/functions/min_over_time.md

@@ -0,0 +1,10 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+### MIN OVER TIME
+The minimum over time value of a field.
+
+```esql
+TS k8s
+| STATS cost=sum(min_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
+```
+Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds

x-pack/plugin/esql/qa/testFixtures/src/main/resources/k8s-timeseries.csv-spec

@@ -169,13 +169,19 @@ null                                     | three       | 2024-05-10T00:01:00.000
 max_over_time
 required_capability: metrics_command
 required_capability: max_over_time
-TS k8s | STATS cost=sum(max_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute) | SORT cost DESC, time_bucket DESC, cluster | LIMIT 10;
+// tag::max_over_time[]
+TS k8s 
+| STATS cost=sum(max_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute) 
+// end::max_over_time[]
+| SORT cost DESC, time_bucket DESC, cluster | LIMIT 10;
 
+// tag::max_over_time-result[]
 cost:double | cluster:keyword | time_bucket:datetime    
 32.75       | qa              | 2024-05-10T00:17:00.000Z
 32.25       | staging         | 2024-05-10T00:09:00.000Z
 31.75       | qa              | 2024-05-10T00:06:00.000Z
 29.0        | prod            | 2024-05-10T00:19:00.000Z
+// end::max_over_time-result[]
 28.625      | qa              | 2024-05-10T00:09:00.000Z
 24.625      | qa              | 2024-05-10T00:18:00.000Z
 23.25       | qa              | 2024-05-10T00:11:00.000Z
@@ -187,12 +193,18 @@ cost:double | cluster:keyword | time_bucket:datetime
 min_over_time
 required_capability: metrics_command
 required_capability: min_over_time
-TS k8s | STATS cost=sum(min_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute) | SORT cost DESC, time_bucket DESC, cluster | LIMIT 10;
+// tag::min_over_time[]
+TS k8s 
+| STATS cost=sum(min_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute) 
+// end::min_over_time[]
+| SORT cost DESC, time_bucket DESC, cluster | LIMIT 10;
 
+// tag::min_over_time-result[]
 cost:double | cluster:keyword | time_bucket:datetime    
 29.0        | prod            | 2024-05-10T00:19:00.000Z
 27.625      | qa              | 2024-05-10T00:06:00.000Z
 24.25       | qa              | 2024-05-10T00:09:00.000Z
+// end::min_over_time-result[]
 23.125      | staging         | 2024-05-10T00:08:00.000Z
 22.5        | prod            | 2024-05-10T00:13:00.000Z
 18.625      | qa              | 2024-05-10T00:04:00.000Z
@@ -205,13 +217,19 @@ cost:double | cluster:keyword | time_bucket:datetime
 max_of_avg_over_time
 required_capability: metrics_command
 required_capability: avg_over_time
-TS k8s | STATS max_cost=max(avg_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute) | SORT max_cost DESC, time_bucket DESC, cluster | LIMIT 10;
+// tag::avg_over_time[]
+TS k8s
+| STATS max_cost=max(avg_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute) 
+// end::avg_over_time[]
+| SORT max_cost DESC, time_bucket DESC, cluster | LIMIT 10;
 
+// tag::avg_over_time-result[]
 max_cost:double | cluster:keyword | time_bucket:datetime    
 12.375          | prod            | 2024-05-10T00:17:00.000Z
 12.375          | qa              | 2024-05-10T00:01:00.000Z
 12.25           | prod            | 2024-05-10T00:19:00.000Z
 12.0625         | qa              | 2024-05-10T00:06:00.000Z
+// end::avg_over_time-result[]
 11.875          | prod            | 2024-05-10T00:15:00.000Z
 11.875          | qa              | 2024-05-10T00:09:00.000Z
 11.625          | prod            | 2024-05-10T00:12:00.000Z

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionType.java

@@ -21,6 +21,13 @@ public enum FunctionType {
      * For example, {@code MAX} in {@code | STATS MAX(LENGTH(string))}.
      */
     AGGREGATE,
+
+    /**
+     * Functions that can only appear in the aggregate" position of a {@code STATS}
+     * started with TS.
+     * For example, {@code MAX_OVER_TIME} in {@code | STATS MAX(MAX_OVER_TIME(string))}.
+     */
+    TIME_SERIES_AGGREGATE,
     /**
      * Functions that can only appear in the "grouping" position of a {@code STATS}.
      * For example, {@code CATEGORIZE} in {@code | STATS MAX(a) BY CATEGORIZE(message)}.

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/AvgOverTime.java

@@ -14,6 +14,9 @@ import org.elasticsearch.xpack.esql.core.expression.Literal;
 import org.elasticsearch.xpack.esql.core.tree.NodeInfo;
 import org.elasticsearch.xpack.esql.core.tree.Source;
 import org.elasticsearch.xpack.esql.core.type.DataType;
+import org.elasticsearch.xpack.esql.expression.function.Example;
+import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesTo;
+import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesToLifecycle;
 import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
 import org.elasticsearch.xpack.esql.expression.function.FunctionType;
 import org.elasticsearch.xpack.esql.expression.function.Param;
@@ -33,7 +36,14 @@ public class AvgOverTime extends TimeSeriesAggregateFunction {
         AvgOverTime::new
     );
 
-    @FunctionInfo(returnType = "double", description = "The average over time of a numeric field.", type = FunctionType.AGGREGATE)
+    @FunctionInfo(
+        returnType = "double",
+        description = "The average over time of a numeric field.",
+        type = FunctionType.TIME_SERIES_AGGREGATE,
+        appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.UNAVAILABLE) },
+        note = "Available with the [TS](/reference/query-languages/esql/commands/source-commands.md#esql-ts) command in snapshot builds",
+        examples = { @Example(file = "k8s-timeseries", tag = "avg_over_time") }
+    )
     public AvgOverTime(
         Source source,
         @Param(

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MaxOverTime.java

@@ -14,6 +14,9 @@ import org.elasticsearch.xpack.esql.core.expression.Literal;
 import org.elasticsearch.xpack.esql.core.tree.NodeInfo;
 import org.elasticsearch.xpack.esql.core.tree.Source;
 import org.elasticsearch.xpack.esql.core.type.DataType;
+import org.elasticsearch.xpack.esql.expression.function.Example;
+import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesTo;
+import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesToLifecycle;
 import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
 import org.elasticsearch.xpack.esql.expression.function.FunctionType;
 import org.elasticsearch.xpack.esql.expression.function.Param;
@@ -36,7 +39,10 @@ public class MaxOverTime extends TimeSeriesAggregateFunction {
     @FunctionInfo(
         returnType = { "boolean", "double", "integer", "long", "date", "date_nanos", "ip", "keyword", "long", "version" },
         description = "The maximum over time value of a field.",
-        type = FunctionType.AGGREGATE
+        type = FunctionType.TIME_SERIES_AGGREGATE,
+        appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.UNAVAILABLE) },
+        note = "Available with the [TS](/reference/query-languages/esql/commands/source-commands.md#esql-ts) command in snapshot builds",
+        examples = { @Example(file = "k8s-timeseries", tag = "max_over_time") }
     )
     public MaxOverTime(
         Source source,

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MinOverTime.java

@@ -14,6 +14,9 @@ import org.elasticsearch.xpack.esql.core.expression.Literal;
 import org.elasticsearch.xpack.esql.core.tree.NodeInfo;
 import org.elasticsearch.xpack.esql.core.tree.Source;
 import org.elasticsearch.xpack.esql.core.type.DataType;
+import org.elasticsearch.xpack.esql.expression.function.Example;
+import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesTo;
+import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesToLifecycle;
 import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
 import org.elasticsearch.xpack.esql.expression.function.FunctionType;
 import org.elasticsearch.xpack.esql.expression.function.Param;
@@ -36,7 +39,10 @@ public class MinOverTime extends TimeSeriesAggregateFunction {
     @FunctionInfo(
         returnType = { "boolean", "double", "integer", "long", "date", "date_nanos", "ip", "keyword", "long", "version" },
         description = "The minimum over time value of a field.",
-        type = FunctionType.AGGREGATE
+        type = FunctionType.TIME_SERIES_AGGREGATE,
+        appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.UNAVAILABLE) },
+        note = "Available with the [TS](/reference/query-languages/esql/commands/source-commands.md#esql-ts) command in snapshot builds",
+        examples = { @Example(file = "k8s-timeseries", tag = "min_over_time") }
     )
     public MinOverTime(
         Source source,

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java

@@ -1058,6 +1058,7 @@ public abstract class DocsV3Support {
                 builder.field("type", switch (info.type()) {
                     case SCALAR -> "scalar";
                     case AGGREGATE -> "agg";
+                    case TIME_SERIES_AGGREGATE -> "time_series_agg";
                     case GROUPING -> "grouping";
                 });
             }

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/aggregate/AvgOverTimeTests.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+package org.elasticsearch.xpack.esql.expression.function.aggregate;
+
+import com.carrotsearch.randomizedtesting.annotations.Name;
+import com.carrotsearch.randomizedtesting.annotations.ParametersFactory;
+
+import org.elasticsearch.xpack.esql.core.expression.Expression;
+import org.elasticsearch.xpack.esql.core.tree.Source;
+import org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase;
+import org.elasticsearch.xpack.esql.expression.function.TestCaseSupplier;
+
+import java.util.List;
+import java.util.function.Supplier;
+
+public class AvgOverTimeTests extends AbstractFunctionTestCase {
+    public AvgOverTimeTests(@Name("TestCase") Supplier<TestCaseSupplier.TestCase> testCaseSupplier) {
+        this.testCase = testCaseSupplier.get();
+    }
+
+    @ParametersFactory
+    public static Iterable<Object[]> parameters() {
+        return AvgTests.parameters();
+    }
+
+    @Override
+    protected Expression build(Source source, List<Expression> args) {
+        return new AvgOverTime(source, args.get(0));
+    }
+}

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MaxOverTimeTests.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+package org.elasticsearch.xpack.esql.expression.function.aggregate;
+
+import com.carrotsearch.randomizedtesting.annotations.ParametersFactory;
+
+import org.elasticsearch.xpack.esql.core.expression.Expression;
+import org.elasticsearch.xpack.esql.core.tree.Source;
+import org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase;
+import org.elasticsearch.xpack.esql.expression.function.TestCaseSupplier;
+
+import java.util.List;
+import java.util.function.Supplier;
+
+public class MaxOverTimeTests extends AbstractFunctionTestCase {
+    public MaxOverTimeTests(Supplier<TestCaseSupplier.TestCase> testCaseSupplier) {
+        testCase = testCaseSupplier.get();
+    }
+
+    @ParametersFactory
+    public static Iterable<Object[]> parameters() {
+        return MinTests.parameters();
+    }
+
+    @Override
+    protected Expression build(Source source, List<Expression> args) {
+        return new MinOverTime(source, args.get(0));
+    }
+}

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MinOverTimeTests.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+package org.elasticsearch.xpack.esql.expression.function.aggregate;
+
+import com.carrotsearch.randomizedtesting.annotations.ParametersFactory;
+
+import org.elasticsearch.xpack.esql.core.expression.Expression;
+import org.elasticsearch.xpack.esql.core.tree.Source;
+import org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase;
+import org.elasticsearch.xpack.esql.expression.function.TestCaseSupplier;
+
+import java.util.List;
+import java.util.function.Supplier;
+
+public class MinOverTimeTests extends AbstractFunctionTestCase {
+    public MinOverTimeTests(Supplier<TestCaseSupplier.TestCase> testCaseSupplier) {
+        testCase = testCaseSupplier.get();
+    }
+
+    @ParametersFactory
+    public static Iterable<Object[]> parameters() {
+        return MaxTests.parameters();
+    }
+
+    @Override
+    protected Expression build(Source source, List<Expression> args) {
+        return new MaxOverTime(source, args.get(0));
+    }
+}