ESQL: make order in TOP optional (#135932)

- Make optional the 3rd param to the TOP agg function, and default it to "asc" if omitted
- Add a capability
- Add a csv test
- Randomly drop the order field during unit test cases where the order is ascending
- Documentation changes

Resolves #133964

Author: mouhc1ne

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

@@ -300,3 +300,15 @@ FROM books
                                                     The Lord of the Rings Poster Collection: Six Paintings by Alan Lee (No. 1) | he Lo |                                                                [J. R. R. Tolkien, Alan Lee] | Alan Lee
 A Gentle Creature and Other Stories: White Nights, A Gentle Creature, and The Dream of a Ridiculous Man (The World's Classics) |  Gent |                                        [W. J. Leatherbarrow, Fyodor Dostoevsky, Alan Myers] | Alan Myers
 ;
+
+
+topWithOptionalOrder
+required_capability: agg_top
+required_capability: agg_top_with_optional_order_field
+
+FROM employees | STATS top_salaries = TOP(salary, 3);
+
+top_salaries:integer
+[25324, 25945, 25976]
+;
+

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

@@ -307,6 +307,11 @@ public enum Cap {
          */
         AGG_TOP_STRING_SUPPORT,
 
+        /**
+         * Make optional the order field in the TOP agg command, and default it to "ASC".
+         */
+        AGG_TOP_WITH_OPTIONAL_ORDER_FIELD,
+
         /**
          * {@code CASE} properly handling multivalue conditions.
          */

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

@@ -31,6 +31,7 @@
 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.OptionalArgument;
 import org.elasticsearch.xpack.esql.expression.function.Param;
 import org.elasticsearch.xpack.esql.io.stream.PlanStreamInput;
 import org.elasticsearch.xpack.esql.planner.ToAggregator;
@@ -50,7 +51,12 @@
 import static org.elasticsearch.xpack.esql.expression.Foldables.TypeResolutionValidator.forPostOptimizationValidation;
 import static org.elasticsearch.xpack.esql.expression.Foldables.TypeResolutionValidator.forPreOptimizationValidation;
 
-public class Top extends AggregateFunction implements ToAggregator, SurrogateExpression, PostOptimizationVerificationAware {
+public class Top extends AggregateFunction
+    implements
+        OptionalArgument,
+        ToAggregator,
+        SurrogateExpression,
+        PostOptimizationVerificationAware {
     public static final NamedWriteableRegistry.Entry ENTRY = new NamedWriteableRegistry.Entry(Expression.class, "Top", Top::new);
 
     private static final String ORDER_ASC = "ASC";
@@ -71,12 +77,13 @@ public Top(
         ) Expression field,
         @Param(name = "limit", type = { "integer" }, description = "The maximum number of values to collect.") Expression limit,
         @Param(
+            optional = true,
             name = "order",
             type = { "keyword" },
-            description = "The order to calculate the top values. Either `asc` or `desc`."
+            description = "The order to calculate the top values. Either `asc` or `desc`, and defaults to `asc` if omitted."
         ) Expression order
     ) {
-        this(source, field, Literal.TRUE, limit, order);
+        this(source, field, Literal.TRUE, limit, order == null ? Literal.keyword(source, ORDER_ASC) : order);
     }
 
     public Top(Source source, Expression field, Expression filter, Expression limit, Expression order) {