Add doc for agg_over_time

Author: dnhatn

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

@@ -167,9 +167,13 @@ 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) 
+// tag::max_over_time[]
+| SORT cost DESC, time_bucket DESC, cluster | LIMIT 10;
 
 cost:double | cluster:keyword | time_bucket:datetime    
 32.75       | qa              | 2024-05-10T00:17: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/MaxOverTime.java

@@ -14,6 +14,7 @@
 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.FunctionInfo;
 import org.elasticsearch.xpack.esql.expression.function.FunctionType;
 import org.elasticsearch.xpack.esql.expression.function.Param;
@@ -36,7 +37,8 @@ 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,
+        examples = { @Example(file = "k8s-timeseries", tag = "max_over_time") }
     )
     public MaxOverTime(
         Source source,

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

@@ -1058,6 +1058,7 @@ void renderKibanaFunctionDefinition(
                 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/MaxOverTimeTests.java

@@ -0,0 +1,33 @@
+/*
+ * 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;
+
+import org.elasticsearch.xpack.esql.core.expression.Expression;
+import org.elasticsearch.xpack.esql.core.tree.Source;
+import org.elasticsearch.xpack.esql.expression.function.aggregate.Max;
+import org.elasticsearch.xpack.esql.expression.function.aggregate.MaxOverTime;
+import org.elasticsearch.xpack.esql.expression.function.aggregate.MaxTests;
+
+import java.util.List;
+import java.util.function.Supplier;
+
+import static org.hamcrest.Matchers.equalTo;
+
+public class MaxOverTimeTests extends MaxTests {
+    public MaxOverTimeTests(Supplier<TestCaseSupplier.TestCase> testCaseSupplier) {
+        super(testCaseSupplier);
+    }
+
+    @Override
+    protected Expression build(Source source, List<Expression> args) {
+        MaxOverTime maxOverTime = new MaxOverTime(source, args.get(0));
+        Max perTimeSeriesAggregation = maxOverTime.perTimeSeriesAggregation();
+        assertThat(super.build(source, args), equalTo(perTimeSeriesAggregation));
+        return perTimeSeriesAggregation;
+    }
+}