[[esql-pow]]
=== `POW`
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=powDI]
----
[%header.monospaced.styled,format=dsv,separator=|]
|===
include::{esql-specs}/math.csv-spec[tag=powDI-result]
|===

==== Type rules

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 or the exponent are 64-bit (long or unsigned long), the result will be a long
* Otherwise, the result will be a 32-bit integer (this covers 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]
|===

NOTE: The actual power function is performed using double precision values for all cases.
This means that for very large non-floating point values there is a small chance that the
operation can lead to slightly different answers than expected.
However, a more likely outcome of very large non-floating point values is numerical overflow.

==== Arithmetic errors

Arithmetic errors and numeric overflow do not result in an error. Instead, the result will be `null`
and a warning for the `ArithmeticException` added.
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-warning]
|===
[%header.monospaced.styled,format=dsv,separator=|]
|===
include::{esql-specs}/math.csv-spec[tag=powULOverrun-result]
|===

If it is desired to protect against numerical overruns, use `to_double` on either 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]
|===

==== Fractional exponents

The exponent can be a fraction, which is similar to performing a root.
For example, the exponent of `0.5` will give the square root of the base:

[source.merge.styled,esql]
----
include::{esql-specs}/math.csv-spec[tag=powID-sqrt]
----
[%header.monospaced.styled,format=dsv,separator=|]
|===
include::{esql-specs}/math.csv-spec[tag=powID-sqrt-result]
|===

==== Table of supported input and output types

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

|===