SQL: Add method args to PERCENTILE/PERCENTILE_RANK (#65026)

* Adds the capability to have functions with two optional arguments
* Adds two new optional arguments to `PERCENTILE()` and
  `PERCENTILE_RANK()` functions, namely the method and
  method_parameter which can be: 1) `tdigest` and a double `compression`
  parameter or 2) `hdr` and an integer representing the
  `number_of_digits` parameter.
* Integration tests
* Documentation updates

Closes #63567

Author: Andras Palinkas

docs/reference/sql/functions/aggs.asciidoc

@@ -477,14 +477,18 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggMadScalars]
 [source, sql]
 --------------------------------------------------
 PERCENTILE(
-    field_name,  <1>
-    numeric_exp) <2>
+    field_name,         <1>
+    percentile[,        <2>
+    method[,            <3>
+    method_parameter]]) <4>
 --------------------------------------------------
 
 *Input*:
 
 <1> a numeric field
 <2> a numeric expression (must be a constant and not based on a field)
+<3> optional string literal for the <<search-aggregations-metrics-percentile-aggregation-approximation,percentile algorithm>>. Possible values: `tdigest` or `hdr`. Defaults to `tdigest`.
+<4> optional numeric literal that configures the <<search-aggregations-metrics-percentile-aggregation-approximation,percentile algorithm>>. Configures `compression` for `tdigest` or `number_of_significant_value_digits` for `hdr`. The default is the same as that of the backing algorithm.
 
 *Output*: `double` numeric value
 
@@ -503,21 +507,31 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggPercentile]
 include-tagged::{sql-specs}/docs/docs.csv-spec[aggPercentileScalars]
 --------------------------------------------------
 
+["source","sql",subs="attributes,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/docs/docs.csv-spec[aggPercentileWithPercentileConfig]
+--------------------------------------------------
+
 [[sql-functions-aggs-percentile-rank]]
 ==== `PERCENTILE_RANK`
 
 .Synopsis:
 [source, sql]
 --------------------------------------------------
 PERCENTILE_RANK(
-    field_name,  <1>
-    numeric_exp) <2>
+    field_name,         <1>
+    value[,             <2>
+    method[,            <3>
+    method_parameter]]) <4>
 --------------------------------------------------
 
 *Input*:
 
 <1> a numeric field
 <2> a numeric expression (must be a constant and not based on a field)
+<3> optional string literal for the <<search-aggregations-metrics-percentile-aggregation-approximation,percentile algorithm>>. Possible values: `tdigest` or `hdr`. Defaults to `tdigest`.
+<4> optional numeric literal that configures the <<search-aggregations-metrics-percentile-aggregation-approximation,percentile algorithm>>. Configures `compression` for `tdigest` or `number_of_significant_value_digits` for `hdr`. The default is the same as that of the backing algorithm.
+
 
 *Output*: `double` numeric value
 
@@ -536,6 +550,11 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggPercentileRank]
 include-tagged::{sql-specs}/docs/docs.csv-spec[aggPercentileRankScalars]
 --------------------------------------------------
 
+["source","sql",subs="attributes,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/docs/docs.csv-spec[aggPercentileRankWithPercentileConfig]
+--------------------------------------------------
+
 [[sql-functions-aggs-skewness]]
 ==== `SKEWNESS`
 

x-pack/plugin/ql/src/main/java/org/elasticsearch/xpack/ql/expression/function/FunctionRegistry.java

@@ -420,16 +420,23 @@ protected interface ScalarTriFunctionConfigurationAwareBuilder<T> {
     public static <T extends Function> FunctionDefinition def(Class<T> function,
             FourParametersFunctionBuilder<T> ctorRef, String... names) {
         FunctionBuilder builder = (source, children, distinct, cfg) -> {
-            boolean hasMinimumThree = OptionalArgument.class.isAssignableFrom(function);
-            if (hasMinimumThree && (children.size() > 4 || children.size() < 3)) {
-                throw new QlIllegalArgumentException("expects three or four arguments");
-            } else if (!hasMinimumThree && children.size() != 4) {
+            if (OptionalArgument.class.isAssignableFrom(function)) {
+                if (children.size() > 4 || children.size() < 3) {
+                    throw new QlIllegalArgumentException("expects three or four arguments");
+                }
+            } else if (TwoOptionalArguments.class.isAssignableFrom(function)) {
+                if (children.size() > 4 || children.size() < 2) {
+                    throw new QlIllegalArgumentException("expects minimum two, maximum four arguments");
+                }
+            } else if (children.size() != 4) {
                 throw new QlIllegalArgumentException("expects exactly four arguments");
             }
             if (distinct) {
                 throw new QlIllegalArgumentException("does not support DISTINCT yet it was specified");
             }
-            return ctorRef.build(source, children.get(0), children.get(1), children.get(2), children.size() == 4 ? children.get(3) : null);
+            return ctorRef.build(source, children.get(0), children.get(1), 
+                children.size() > 2 ? children.get(2) : null,
+                children.size() > 3 ? children.get(3) : null);
         };
         return def(function, builder, false, names);
     }

x-pack/plugin/ql/src/main/java/org/elasticsearch/xpack/ql/expression/function/TwoOptionalArguments.java

@@ -0,0 +1,15 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License;
+ * you may not use this file except in compliance with the Elastic License.
+ */
+
+package org.elasticsearch.xpack.ql.expression.function;
+
+/**
+ * Marker interface indicating that a function accepts two optional arguments (the last two).
+ * This is used by the {@link FunctionRegistry} to perform validation of function declaration.
+ */
+public interface TwoOptionalArguments {
+
+}

x-pack/plugin/sql/qa/server/src/main/resources/agg.csv-spec

@@ -22,6 +22,42 @@ F                    |10099.7608
 M                    |10096.2232
 ;
 
+singlePercentileWithCommaTDigestSpecified
+SELECT gender, PERCENTILE(emp_no, 97.76, 'tdigest') p1 FROM test_emp GROUP BY gender;
+
+gender:s             | p1:d
+null                 |10019.0
+F                    |10099.7608
+M                    |10096.2232
+;
+
+singlePercentileWithCommaTDigestWithCompressionSpecified
+SELECT gender, PERCENTILE(emp_no, 97.76, 'tdigest', 50 + 0.2) p1 FROM test_emp GROUP BY gender;
+
+gender:s             | p1:d
+null                 |10019.0
+F                    |10099.7608
+M                    |10096.2232
+;
+
+singlePercentileWithCommaHDRSpecified
+SELECT gender, PERCENTILE(emp_no, 97.76, 'hdr') p1 FROM test_emp GROUP BY gender;
+
+gender:s             | p1:d
+null                 |10016.0
+F                    |10096.0
+M                    |10096.0
+;
+
+singlePercentileWithCommaHDRWithDigitsSpecified
+SELECT gender, PERCENTILE(emp_no, 97.76, 'hdr', 1+1) p1 FROM test_emp GROUP BY gender;
+
+gender:s             | p1:d
+null                 |9984.0
+F                    |10048.0
+M                    |10048.0
+;
+
 multiplePercentilesOneWithCommaOneWithout
 SELECT gender, PERCENTILE(emp_no, 92.45) p1, PERCENTILE(emp_no, 91) p2 FROM test_emp GROUP BY gender;
 
@@ -58,6 +94,24 @@ F                    |17.424242424242426
 M                    |15.350877192982457
 ;
 
+singlePercentileRankWithHDRSpecified
+SELECT gender, PERCENTILE_RANK(emp_no, 10000 + 25, 'hdr') p1 FROM test_emp GROUP BY gender;
+
+gender:s             | p1:d
+null                 |100.0
+F                    |21.21212121212121
+M                    |24.56140350877193
+;
+
+singlePercentileRankHDRWithDigitsSpecified
+SELECT gender, PERCENTILE_RANK(emp_no, 10000 + 25, 'hdr', 4+1) p1 FROM test_emp GROUP BY gender;
+
+gender:s             | p1:d
+null                 |100.0
+F                    |18.181818181818183
+M                    |15.789473684210526
+;
+
 multiplePercentileRanks
 SELECT gender, PERCENTILE_RANK(emp_no, 10030.0) rank1, PERCENTILE_RANK(emp_no, 10025) rank2 FROM test_emp GROUP BY gender;
 

x-pack/plugin/sql/qa/server/src/main/resources/docs/docs.csv-spec

@@ -1511,6 +1511,26 @@ null           |6249.916666666667
 // end::aggPercentileScalars
 ;
 
+aggPercentileWithPercentileConfig
+// tag::aggPercentileWithPercentileConfig
+SELECT
+    languages, 
+    PERCENTILE(salary, 97.3, 'tdigest', 100.0) AS "97.3_TDigest", 
+    PERCENTILE(salary, 97.3, 'hdr', 3) AS "97.3_HDR" 
+FROM emp 
+GROUP BY languages;
+
+   languages   | 97.3_TDigest  |   97.3_HDR    
+---------------+---------------+---------------
+null           |74999.0        |74992.0        
+1              |73717.0        |73712.0        
+2              |73530.238      |69936.0        
+3              |74970.0        |74992.0        
+4              |74572.0        |74608.0        
+5              |66117.118      |56368.0        
+// end::aggPercentileWithPercentileConfig
+;
+
 aggPercentileRank
 // tag::aggPercentileRank
 SELECT languages, PERCENTILE_RANK(salary, 65000) AS rank FROM emp GROUP BY languages;
@@ -1542,6 +1562,26 @@ null           |66.91240875912409
 // end::aggPercentileRankScalars
 ;
 
+aggPercentileRankWithPercentileConfig
+// tag::aggPercentileRankWithPercentileConfig
+SELECT
+    languages,
+    ROUND(PERCENTILE_RANK(salary, 65000, 'tdigest', 100.0), 2) AS "rank_TDigest",
+    ROUND(PERCENTILE_RANK(salary, 65000, 'hdr', 3), 2) AS "rank_HDR"
+FROM emp
+GROUP BY languages;
+
+   languages   | rank_TDigest  |   rank_HDR    
+---------------+---------------+---------------
+null           |73.66          |80.0           
+1              |73.73          |73.33          
+2              |88.88          |89.47          
+3              |79.44          |76.47          
+4              |85.7           |83.33          
+5              |100.0          |95.24          
+// end::aggPercentileRankWithPercentileConfig
+;
+
 aggSkewness
 // tag::aggSkewness
 SELECT MIN(salary) AS min, MAX(salary) AS max, SKEWNESS(salary) AS s FROM emp;

x-pack/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/aggregate/Percentile.java

@@ -6,70 +6,31 @@
 package org.elasticsearch.xpack.sql.expression.function.aggregate;
 
 import org.elasticsearch.xpack.ql.expression.Expression;
-import org.elasticsearch.xpack.ql.expression.Expressions.ParamOrdinal;
-import org.elasticsearch.xpack.ql.expression.Foldables;
-import org.elasticsearch.xpack.ql.expression.function.aggregate.EnclosedAgg;
 import org.elasticsearch.xpack.ql.tree.NodeInfo;
 import org.elasticsearch.xpack.ql.tree.Source;
-import org.elasticsearch.xpack.ql.type.DataType;
-import org.elasticsearch.xpack.ql.type.DataTypes;
-import org.elasticsearch.xpack.sql.type.SqlDataTypeConverter;
 
 import java.util.List;
 
-import static java.util.Collections.singletonList;
-import static org.elasticsearch.xpack.ql.expression.TypeResolutions.isFoldable;
-import static org.elasticsearch.xpack.ql.expression.TypeResolutions.isNumeric;
+public class Percentile extends PercentileAggregate {
 
-public class Percentile extends NumericAggregate implements EnclosedAgg {
-
-    private final Expression percent;
-
-    public Percentile(Source source, Expression field, Expression percent) {
-        super(source, field, singletonList(percent));
-        this.percent = percent;
+    public Percentile(Source source, Expression field, Expression percent, Expression method, Expression methodParameter) {
+        super(source, field, percent, method, methodParameter);
     }
 
     @Override
     protected NodeInfo<Percentile> info() {
-        return NodeInfo.create(this, Percentile::new, field(), percent);
+        return NodeInfo.create(this, Percentile::new, field(), percent(), method(), methodParameter());
     }
 
     @Override
     public Percentile replaceChildren(List<Expression> newChildren) {
         if (newChildren.size() != 2) {
             throw new IllegalArgumentException("expected [2] children but received [" + newChildren.size() + "]");
         }
-        return new Percentile(source(), newChildren.get(0), newChildren.get(1));
-    }
-
-    @Override
-    protected TypeResolution resolveType() {
-        TypeResolution resolution = isFoldable(percent, sourceText(), ParamOrdinal.SECOND);
-        if (resolution.unresolved()) {
-            return resolution;
-        }
-
-        resolution = super.resolveType();
-        if (resolution.unresolved()) {
-            return resolution;
-        }
-
-        return isNumeric(percent, sourceText(), ParamOrdinal.DEFAULT);
+        return new Percentile(source(), newChildren.get(0), newChildren.get(1), method(), methodParameter());
     }
 
     public Expression percent() {
-        return percent;
-    }
-
-    @Override
-    public DataType dataType() {
-        return DataTypes.DOUBLE;
-    }
-
-    @Override
-    public String innerName() {
-        Double value = (Double) SqlDataTypeConverter.convert(Foldables.valueOf(percent), DataTypes.DOUBLE);
-        return Double.toString(value);
+        return parameter();
     }
 }