math functions

docs/reference/esql/functions/description/sqrt.asciidoc

@@ -2,4 +2,4 @@
 
 *Description*
 
-Returns the square root of a number.
+Returns the square root of a number. The input can be any numeric value, the return value is always a double. Square roots of negative numbers are NaN. Square roots of infinites are infinite.

docs/reference/esql/functions/description/tau.asciidoc

@@ -2,4 +2,4 @@
 
 *Description*
 
-The ratio of a circle’s circumference to its radius.
+Returns the https://tauday.com/tau-manifesto[ratio] of a circle's circumference to its radius.

docs/reference/esql/functions/examples/sqrt.asciidoc

@@ -0,0 +1,13 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+*Example*
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/math.csv-spec[tag=sqrt]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/math.csv-spec[tag=sqrt-result]
+|===
+

docs/reference/esql/functions/examples/tau.asciidoc

@@ -0,0 +1,13 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+*Example*
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/math.csv-spec[tag=tau]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/math.csv-spec[tag=tau-result]
+|===
+

docs/reference/esql/functions/kibana/definition/sqrt.json

@@ -2,15 +2,15 @@
   "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.",
   "type" : "eval",
   "name" : "sqrt",
-  "description" : "Returns the square root of a number.",
+  "description" : "Returns the square root of a number. The input can be any numeric value, the return value is always a double.\nSquare roots of negative numbers are NaN. Square roots of infinites are infinite.",
   "signatures" : [
     {
       "params" : [
         {
           "name" : "number",
           "type" : "double",
           "optional" : false,
-          "description" : ""
+          "description" : "Numeric expression. If `null`, the function returns `null`."
         }
       ],
       "variadic" : false,
@@ -22,7 +22,7 @@
           "name" : "number",
           "type" : "integer",
           "optional" : false,
-          "description" : ""
+          "description" : "Numeric expression. If `null`, the function returns `null`."
         }
       ],
       "variadic" : false,
@@ -34,7 +34,7 @@
           "name" : "number",
           "type" : "long",
           "optional" : false,
-          "description" : ""
+          "description" : "Numeric expression. If `null`, the function returns `null`."
         }
       ],
       "variadic" : false,
@@ -46,11 +46,14 @@
           "name" : "number",
           "type" : "unsigned_long",
           "optional" : false,
-          "description" : ""
+          "description" : "Numeric expression. If `null`, the function returns `null`."
         }
       ],
       "variadic" : false,
       "returnType" : "double"
     }
+  ],
+  "examples" : [
+    "ROW d = 100.0\n| EVAL s = SQRT(d)"
   ]
 }

docs/reference/esql/functions/kibana/definition/tau.json

@@ -2,11 +2,14 @@
   "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.",
   "type" : "eval",
   "name" : "tau",
-  "description" : "The ratio of a circle’s circumference to its radius.",
+  "description" : "Returns the ratio of a circle's circumference to its radius.",
   "signatures" : [
     {
       "params" : [ ],
       "returnType" : "double"
     }
+  ],
+  "examples" : [
+    "ROW TAU()"
   ]
 }

docs/reference/esql/functions/kibana/docs/sqrt.md

@@ -3,5 +3,10 @@ This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../READ
 -->
 
 ### SQRT
-Returns the square root of a number.
+Returns the square root of a number. The input can be any numeric value, the return value is always a double.
+Square roots of negative numbers are NaN. Square roots of infinites are infinite.
 
+```
+ROW d = 100.0
+| EVAL s = SQRT(d)
+```

docs/reference/esql/functions/kibana/docs/tau.md

@@ -3,5 +3,8 @@ This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../READ
 -->
 
 ### TAU
-The ratio of a circle’s circumference to its radius.
+Returns the ratio of a circle's circumference to its radius.
 
+```
+ROW TAU()
+```

docs/reference/esql/functions/layout/sqrt.asciidoc

@@ -12,3 +12,4 @@ image::esql/functions/signature/sqrt.svg[Embedded,opts=inline]
 include::../parameters/sqrt.asciidoc[]
 include::../description/sqrt.asciidoc[]
 include::../types/sqrt.asciidoc[]
+include::../examples/sqrt.asciidoc[]

docs/reference/esql/functions/layout/tau.asciidoc

@@ -12,3 +12,4 @@ image::esql/functions/signature/tau.svg[Embedded,opts=inline]
 include::../parameters/tau.asciidoc[]
 include::../description/tau.asciidoc[]
 include::../types/tau.asciidoc[]
+include::../examples/tau.asciidoc[]

docs/reference/esql/functions/math-functions.asciidoc

@@ -50,7 +50,7 @@ include::layout/round.asciidoc[]
 include::layout/signum.asciidoc[]
 include::layout/sin.asciidoc[]
 include::layout/sinh.asciidoc[]
-include::sqrt.asciidoc[]
+include::layout/sqrt.asciidoc[]
 include::layout/tan.asciidoc[]
 include::layout/tanh.asciidoc[]
-include::tau.asciidoc[]
+include::layout/tau.asciidoc[]

docs/reference/esql/functions/parameters/sqrt.asciidoc

@@ -3,4 +3,4 @@
 *Parameters*
 
 `number`::
-
+Numeric expression. If `null`, the function returns `null`.

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

@@ -178,7 +178,7 @@ signum        |number                              |"double|integer|long|unsigne
 sin           |angle                               |"double|integer|long|unsigned_long"                                                                                               |An angle, in radians. If `null`, the function returns `null`.
 sinh          |angle                               |"double|integer|long|unsigned_long"                                                                                               |An angle, in radians. If `null`, the function returns `null`.
 split         |[string, delim]                     |["keyword|text", "keyword|text"]                                                                                                  |[, ]
-sqrt          |number                              |"double|integer|long|unsigned_long"                                                                                               |[""]
+sqrt          |number                              |"double|integer|long|unsigned_long"                                                                                               |"Numeric expression. If `null`, the function returns `null`."
 st_centroid_ag|field                               |"geo_point|cartesian_point"                                                                                                       |[""]
 st_contains   |[geomA, geomB]                      |["geo_point|cartesian_point|geo_shape|cartesian_shape", "geo_point|cartesian_point|geo_shape|cartesian_shape"]                    |[Geometry column name or variable of geometry type, Geometry column name or variable of geometry type]
 st_disjoint   |[geomA, geomB]                      |["geo_point|cartesian_point|geo_shape|cartesian_shape", "geo_point|cartesian_point|geo_shape|cartesian_shape"]                    |[Geometry column name or variable of geometry type, Geometry column name or variable of geometry type]
@@ -292,20 +292,20 @@ signum        |Returns the sign of the given number. It returns `-1` for negativ
 sin           |Returns ths {wikipedia}/Sine_and_cosine[Sine] trigonometric function of an angle.
 sinh          |Returns the {wikipedia}/Hyperbolic_functions[hyperbolic sine] of an angle.
 split         |Split a single valued string into multiple strings.
-sqrt          |Returns the square root of a number.
+sqrt          |Returns the square root of a number. The input can be any numeric value, the return value is always a double. Square roots of negative numbers are NaN. Square roots of infinites are infinite.
 st_centroid_ag|The centroid of a spatial field.
 st_contains   |Returns whether the first geometry contains the second geometry.
 st_disjoint   |Returns whether the two geometries or geometry columns are disjoint.
 st_intersects |Returns whether the two geometries or geometry columns intersect.
 st_within     |Returns whether the first geometry is within the second geometry.
 st_x          |Extracts the x-coordinate from a point geometry.
 st_y          |Extracts the y-coordinate from a point geometry.
-starts_with  |Returns a boolean that indicates whether a keyword string starts with another string
+starts_with   |Returns a boolean that indicates whether a keyword string starts with another string
 substring     |Returns a substring of a string, specified by a start position and an optional length
 sum           |The sum of a numeric field.
 tan           |Returns the {wikipedia}/Sine_and_cosine[Tangent] trigonometric function of an angle.
 tanh          |Returns the {wikipedia}/Hyperbolic_functions[Tangent] hyperbolic function of an angle.
-tau           |The ratio of a circle’s circumference to its radius.
+tau           |Returns the https://tauday.com/tau-manifesto[ratio] of a circle's circumference to its radius.
 to_base64     |Encode a string to a base64 string.
 to_bool       |Converts an input value to a boolean value.
 to_boolean    |Converts an input value to a boolean value.

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Sqrt.java

@@ -10,6 +10,7 @@
 import org.elasticsearch.compute.ann.Evaluator;
 import org.elasticsearch.compute.operator.EvalOperator.ExpressionEvaluator;
 import org.elasticsearch.xpack.esql.EsqlIllegalArgumentException;
+import org.elasticsearch.xpack.esql.expression.function.Example;
 import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
 import org.elasticsearch.xpack.esql.expression.function.Param;
 import org.elasticsearch.xpack.esql.expression.function.scalar.UnaryScalarFunction;
@@ -27,8 +28,20 @@
 import static org.elasticsearch.xpack.ql.expression.TypeResolutions.isNumeric;
 
 public class Sqrt extends UnaryScalarFunction {
-    @FunctionInfo(returnType = "double", description = "Returns the square root of a number.")
-    public Sqrt(Source source, @Param(name = "number", type = { "double", "integer", "long", "unsigned_long" }) Expression n) {
+    @FunctionInfo(
+        returnType = "double",
+        description = "Returns the square root of a number. The input can be any numeric value, the return value is always a double.\n"
+            + "Square roots of negative numbers are NaN. Square roots of infinites are infinite.",
+        examples = @Example(file = "math", tag = "sqrt")
+    )
+    public Sqrt(
+        Source source,
+        @Param(
+            name = "number",
+            type = { "double", "integer", "long", "unsigned_long" },
+            description = "Numeric expression. If `null`, the function returns `null`."
+        ) Expression n
+    ) {
         super(source, n);
     }
 

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Tau.java

@@ -7,6 +7,7 @@
 
 package org.elasticsearch.xpack.esql.expression.function.scalar.math;
 
+import org.elasticsearch.xpack.esql.expression.function.Example;
 import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
 import org.elasticsearch.xpack.ql.expression.Expression;
 import org.elasticsearch.xpack.ql.tree.Source;
@@ -19,7 +20,11 @@
 public class Tau extends DoubleConstantFunction {
     public static final double TAU = Math.PI * 2;
 
-    @FunctionInfo(returnType = "double", description = "The ratio of a circle’s circumference to its radius.")
+    @FunctionInfo(
+        returnType = "double",
+        description = "Returns the https://tauday.com/tau-manifesto[ratio] of a circle's circumference to its radius.",
+        examples = @Example(file = "math", tag = "tau")
+    )
     public Tau(Source source) {
         super(source);
     }

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/TauTests.java

@@ -12,11 +12,10 @@
 
 import org.elasticsearch.compute.data.Block;
 import org.elasticsearch.compute.data.DoubleBlock;
+import org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase;
 import org.elasticsearch.xpack.esql.expression.function.TestCaseSupplier;
-import org.elasticsearch.xpack.esql.expression.function.scalar.AbstractScalarFunctionTestCase;
 import org.elasticsearch.xpack.ql.expression.Expression;
 import org.elasticsearch.xpack.ql.tree.Source;
-import org.elasticsearch.xpack.ql.type.DataType;
 import org.elasticsearch.xpack.ql.type.DataTypes;
 import org.hamcrest.Matcher;
 
@@ -25,7 +24,7 @@
 
 import static org.hamcrest.Matchers.equalTo;
 
-public class TauTests extends AbstractScalarFunctionTestCase {
+public class TauTests extends AbstractFunctionTestCase {
     public TauTests(@Name("TestCase") Supplier<TestCaseSupplier.TestCase> testCaseSupplier) {
         this.testCase = testCaseSupplier.get();
     }
@@ -47,16 +46,6 @@ protected Expression build(Source source, List<Expression> args) {
         return new Tau(Source.EMPTY);
     }
 
-    @Override
-    protected List<ArgumentSpec> argSpec() {
-        return List.of();
-    }
-
-    @Override
-    protected DataType expectedType(List<DataType> argTypes) {
-        return DataTypes.DOUBLE;
-    }
-
     @Override
     protected void assertSimpleWithNulls(List<Object> data, Block value, int nullBlock) {
         assertThat(((DoubleBlock) value).asVector().getDouble(0), equalTo(Tau.TAU));