Improve documentation for pow function and refined type rules

docs/reference/esql/functions/pow.asciidoc

@@ -1,13 +1,85 @@
 [[esql-pow]]
 === `POW`
-Returns the the value of a base (first argument) raised to a power (second
-argument).
+Returns the value of a base (first argument) raised to the power of an exponent (second argument).
+Both arguments must be numeric.
 
 [source.merge.styled,esql]
 ----
-include::{esql-specs}/math.csv-spec[tag=pow]
+include::{esql-specs}/math.csv-spec[tag=powDI]
 ----
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
-include::{esql-specs}/math.csv-spec[tag=pow-result]
+include::{esql-specs}/math.csv-spec[tag=powDI-result]
+|===
+
+The type of the returned value is determined by the types of the base and exponent.
+The following rules are applied to determine the result type:
+
+* If either of the base or exponent are of a floating point type, the result will be a double
+* Otherwise, if either the base of the exponent are 64-bit (long or unsigned long), the result will be a long
+* Otherwise, the result will be a 32-bit integer (all other numeric types, including int, short and byte)
+
+For example, using simple integers as arguments will lead to an integer result:
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/math.csv-spec[tag=powII]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/math.csv-spec[tag=powII-result]
+|===
+
+Numeric overruns do not result in an error. For example:
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/math.csv-spec[tag=powULOverrun]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/math.csv-spec[tag=powULOverrun-result]
+|===
+
+If it is desired to protect against numeric overruns, use `to_double` on any one of the arguments:
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/math.csv-spec[tag=pow2d]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/math.csv-spec[tag=pow2d-result]
+|===
+
+For clarity, the following table describes the output result type for all combinations of numeric input types:
+
+[cols="1,1,1"]
+|===
+|Base | Exponent | Result
+
+|double/float/half_float
+|*footnote:all[All numeric types]
+|double
+
+|*footnote:all[]
+|double/float/half_float
+|double
+
+|long/unsigned long
+|*footnote:all_but_float[All except double/float/half_float]
+|long
+
+|*footnote:all_but_float[]
+|long/unsigned long
+|long
+
+|*footnote:all_but_float_and_64[All except floating point and 64-bit types]
+|*footnote:all_but_float_and_64[]
+|int
+
+|*footnote:all_but_float_and_64[]
+|*footnote:all_but_float_and_64[]
+|int
+
 |===

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

@@ -222,30 +222,38 @@ d:i | l:double
 ;
 
 powDoubleDouble
-// tag::pow[]
 ROW base = 2.0, exponent = 2.0
 | EVAL s = POW(base, exponent)
-// end::pow[]
 ;
 
-// tag::pow-result[]
 base:double | exponent:double | s:double
 2.0         | 2.0             | 4.0
-// end::pow-result[]
 ;
 
 powDoubleInt
-row base = 2.0, exponent = 2 | eval s = pow(base, exponent);
+// tag::powDI[]
+ROW base = 2.0, exponent = 2
+| EVAL result = POW(base, exponent)
+// end::powDI[]
+;
 
-base:double | exponent:integer | s:double
+// tag::powDI-result[]
+base:double | exponent:integer | result:double
 2.0         | 2                | 4.0
+// end::powDI-result[]
 ;
 
 powIntInt
-row base = 2, exponent = 2 | eval s = pow(base, exponent);
+// tag::powII[]
+ROW base = 2, exponent = 2
+| EVAL s = POW(base, exponent)
+// end::powII[]
+;
 
+// tag::powII-result[]
 base:integer | exponent:integer | s:integer
 2            | 2                | 4
+// end::powII-result[]
 ;
 
 powIntIntPlusInt
@@ -305,10 +313,27 @@ x:long
 ;
 
 powULIntOverrun
-row x = pow(9223372036854775808, 1);
+// tag::powULOverrun[]
+ROW x = POW(9223372036854775808, 1)
+// end::powULOverrun[]
+;
 
+// tag::powULOverrun-result[]
 x:long
 0
+// end::powULOverrun-result[]
+;
+
+powULInt_2d
+// tag::pow2d[]
+ROW x = POW(9223372036854775808, TO_DOUBLE(1))
+// end::pow2d[]
+;
+
+// tag::pow2d-result[]
+x:double
+9.223372036854776E18
+// end::pow2d-result[]
 ;
 
 powULLong