elasticsearch/docs/reference/query-languages/esql/_snippets/math-functions-orig.md

{{esql}} mathematical functions [esql-math-functions]

{{esql}} supports these mathematical functions:

:::{include} lists/math-functions.md :::

ABS [esql-abs]

Syntax

:::{image} ../../../../images/abs.svg :alt: Embedded :class: text-center :::

Parameters

number : Numeric expression. If null, the function returns null.

Description

Returns the absolute value.

Supported types

number	result
double	double
integer	integer
long	long
unsigned_long	unsigned_long

Examples

ROW number = -1.0
| EVAL abs_number = ABS(number)

number:double	abs_number:double
-1.0	1.0

FROM employees
| KEEP first_name, last_name, height
| EVAL abs_height = ABS(0.0 - height)

first_name:keyword	last_name:keyword	height:double	abs_height:double
Alejandro	McAlpine	1.48	1.48
Amabile	Gomatam	2.09	2.09
Anneke	Preusig	1.56	1.56

ACOS [esql-acos]

Syntax

:::{image} ../../../../images/acos.svg :alt: Embedded :class: text-center :::

Parameters

number : Number between -1 and 1. If null, the function returns null.

Description

Returns the arccosine of n as an angle, expressed in radians.

Supported types

number	result
double	double
integer	double
long	double
unsigned_long	double

Example

ROW a=.9
| EVAL acos=ACOS(a)

a:double	acos:double
.9	0.45102681179626236

ASIN [esql-asin]

Syntax

:::{image} ../../../../images/asin.svg :alt: Embedded :class: text-center :::

Parameters

number : Number between -1 and 1. If null, the function returns null.

Description

Returns the arcsine of the input numeric expression as an angle, expressed in radians.

Supported types

number	result
double	double
integer	double
long	double
unsigned_long	double

Example

ROW a=.9
| EVAL asin=ASIN(a)

a:double	asin:double
.9	1.1197695149986342

ATAN [esql-atan]

Syntax

:::{image} ../../../../images/atan.svg :alt: Embedded :class: text-center :::

Parameters

number : Numeric expression. If null, the function returns null.

Description

Returns the arctangent of the input numeric expression as an angle, expressed in radians.

Supported types

number	result
double	double
integer	double
long	double
unsigned_long	double

Example

ROW a=12.9
| EVAL atan=ATAN(a)

a:double	atan:double
12.9	1.4934316673669235

ATAN2 [esql-atan2]

Syntax

:::{image} ../../../../images/atan2.svg :alt: Embedded :class: text-center :::

Parameters

y_coordinate : y coordinate. If null, the function returns null.

x_coordinate : x coordinate. If null, the function returns null.

Description

The angle between the positive x-axis and the ray from the origin to the point (x , y) in the Cartesian plane, expressed in radians.

Supported types

y_coordinate	x_coordinate	result
double	double	double
double	integer	double
double	long	double
double	unsigned_long	double
integer	double	double
integer	integer	double
integer	long	double
integer	unsigned_long	double
long	double	double
long	integer	double
long	long	double
long	unsigned_long	double
unsigned_long	double	double
unsigned_long	integer	double
unsigned_long	long	double
unsigned_long	unsigned_long	double

Example

ROW y=12.9, x=.6
| EVAL atan2=ATAN2(y, x)

y:double	x:double	atan2:double
12.9	0.6	1.5243181954438936

CBRT [esql-cbrt]

Syntax

:::{image} ../../../../images/cbrt.svg :alt: Embedded :class: text-center :::

Parameters

number : Numeric expression. If null, the function returns null.

Description

Returns the cube root of a number. The input can be any numeric value, the return value is always a double. Cube roots of infinities are null.

Supported types

number	result
double	double
integer	double
long	double
unsigned_long	double

Example

ROW d = 1000.0
| EVAL c = cbrt(d)

d: double	c:double
1000.0	10.0

CEIL [esql-ceil]

Syntax

:::{image} ../../../../images/ceil.svg :alt: Embedded :class: text-center :::

Parameters

number : Numeric expression. If null, the function returns null.

Description

Round a number up to the nearest integer.

::::{note} This is a noop for long (including unsigned) and integer. For double this picks the closest double value to the integer similar to Math.ceil. ::::

Supported types

number	result
double	double
integer	integer
long	long
unsigned_long	unsigned_long

Example

ROW a=1.8
| EVAL a=CEIL(a)

a:double
2

COS [esql-cos]

Syntax

:::{image} ../../../../images/cos.svg :alt: Embedded :class: text-center :::

Parameters

angle : An angle, in radians. If null, the function returns null.

Description

Returns the cosine of an angle.

Supported types

angle	result
double	double
integer	double
long	double
unsigned_long	double

Example

ROW a=1.8
| EVAL cos=COS(a)

a:double	cos:double
1.8	-0.2272020946930871

COSH [esql-cosh]

Syntax

:::{image} ../../../../images/cosh.svg :alt: Embedded :class: text-center :::

Parameters

number : Numeric expression. If null, the function returns null.

Description

Returns the hyperbolic cosine of a number.

Supported types

number	result
double	double
integer	double
long	double
unsigned_long	double

Example

ROW a=1.8
| EVAL cosh=COSH(a)

a:double	cosh:double
1.8	3.1074731763172667

E [esql-e]

Syntax

:::{image} ../../../../images/e.svg :alt: Embedded :class: text-center :::

Parameters

Description

Returns Euler’s number.

Supported types

result
double

Example

ROW E()

E():double
2.718281828459045

EXP [esql-exp]

Syntax

:::{image} ../../../../images/exp.svg :alt: Embedded :class: text-center :::

Parameters

number : Numeric expression. If null, the function returns null.

Description

Returns the value of e raised to the power of the given number.

Supported types

number	result
double	double
integer	double
long	double
unsigned_long	double

Example

ROW d = 5.0
| EVAL s = EXP(d)

d: double	s:double
5.0	148.413159102576603

FLOOR [esql-floor]

Syntax

:::{image} ../../../../images/floor.svg :alt: Embedded :class: text-center :::

Parameters

number : Numeric expression. If null, the function returns null.

Description

Round a number down to the nearest integer.

::::{note} This is a noop for long (including unsigned) and integer. For double this picks the closest double value to the integer similar to Math.floor. ::::

Supported types

number	result
double	double
integer	integer
long	long
unsigned_long	unsigned_long

Example

ROW a=1.8
| EVAL a=FLOOR(a)

a:double
1

HYPOT [esql-hypot]

Syntax

:::{image} ../../../../images/hypot.svg :alt: Embedded :class: text-center :::

Parameters

number1 : Numeric expression. If null, the function returns null.

number2 : Numeric expression. If null, the function returns null.

Description

Returns the hypotenuse of two numbers. The input can be any numeric values, the return value is always a double. Hypotenuses of infinities are null.

Supported types

number1	number2	result
double	double	double
double	integer	double
double	long	double
double	unsigned_long	double
integer	double	double
integer	integer	double
integer	long	double
integer	unsigned_long	double
long	double	double
long	integer	double
long	long	double
long	unsigned_long	double
unsigned_long	double	double
unsigned_long	integer	double
unsigned_long	long	double
unsigned_long	unsigned_long	double

Example

ROW a = 3.0, b = 4.0
| EVAL c = HYPOT(a, b)

a:double	b:double	c:double
3.0	4.0	5.0

LOG [esql-log]

Syntax

:::{image} ../../../../images/log.svg :alt: Embedded :class: text-center :::

Parameters

base : Base of logarithm. If null, the function returns null. If not provided, this function returns the natural logarithm (base e) of a value.

number : Numeric expression. If null, the function returns null.

Description

Returns the logarithm of a value to a base. The input can be any numeric value, the return value is always a double. Logs of zero, negative numbers, and base of one return null as well as a warning.

Supported types

base	number	result
double	double	double
double	integer	double
double	long	double
double	unsigned_long	double
double		double
integer	double	double
integer	integer	double
integer	long	double
integer	unsigned_long	double
integer		double
long	double	double
long	integer	double
long	long	double
long	unsigned_long	double
long		double
unsigned_long	double	double
unsigned_long	integer	double
unsigned_long	long	double
unsigned_long	unsigned_long	double
unsigned_long		double

Examples

ROW base = 2.0, value = 8.0
| EVAL s = LOG(base, value)

base: double	value: double	s:double
2.0	8.0	3.0

row value = 100
| EVAL s = LOG(value);

value: integer	s:double
100	4.605170185988092

LOG10 [esql-log10]

Syntax

:::{image} ../../../../images/log10.svg :alt: Embedded :class: text-center :::

Parameters

number : Numeric expression. If null, the function returns null.

Description

Returns the logarithm of a value to base 10. The input can be any numeric value, the return value is always a double. Logs of 0 and negative numbers return null as well as a warning.

Supported types

number	result
double	double
integer	double
long	double
unsigned_long	double

Example

ROW d = 1000.0
| EVAL s = LOG10(d)

d: double	s:double
1000.0	3.0

PI [esql-pi]

Syntax

:::{image} ../../../../images/pi.svg :alt: Embedded :class: text-center :::

Parameters

Description

Returns Pi, the ratio of a circle’s circumference to its diameter.

Supported types

result
double

Example

ROW PI()

PI():double
3.141592653589793

POW [esql-pow]

Syntax

:::{image} ../../../../images/pow.svg :alt: Embedded :class: text-center :::

Parameters

base : Numeric expression for the base. If null, the function returns null.

exponent : Numeric expression for the exponent. If null, the function returns null.

Description

Returns the value of base raised to the power of exponent.

::::{note} It is still possible to overflow a double result here; in that case, null will be returned. ::::

Supported types

base	exponent	result
double	double	double
double	integer	double
double	long	double
double	unsigned_long	double
integer	double	double
integer	integer	double
integer	long	double
integer	unsigned_long	double
long	double	double
long	integer	double
long	long	double
long	unsigned_long	double
unsigned_long	double	double
unsigned_long	integer	double
unsigned_long	long	double
unsigned_long	unsigned_long	double

Examples

ROW base = 2.0, exponent = 2
| EVAL result = POW(base, exponent)

base:double	exponent:integer	result:double
2.0	2	4.0

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:

ROW base = 4, exponent = 0.5
| EVAL s = POW(base, exponent)

base:integer	exponent:double	s:double
4	0.5	2.0

ROUND [esql-round]

Syntax

:::{image} ../../../../images/round.svg :alt: Embedded :class: text-center :::

Parameters

number : The numeric value to round. If null, the function returns null.

decimals : The number of decimal places to round to. Defaults to 0. If null, the function returns null.

Description

Rounds a number to the specified number of decimal places. Defaults to 0, which returns the nearest integer. If the precision is a negative number, rounds to the number of digits left of the decimal point.

Supported types

number	decimals	result
double	integer	double
double	long	double
double		double
integer	integer	integer
integer	long	integer
integer		integer
long	integer	long
long	long	long
long		long
unsigned_long	integer	unsigned_long
unsigned_long	long	unsigned_long
unsigned_long		unsigned_long

Example

FROM employees
| KEEP first_name, last_name, height
| EVAL height_ft = ROUND(height * 3.281, 1)

first_name:keyword	last_name:keyword	height:double	height_ft:double
Arumugam	Ossenbruggen	2.1	6.9
Kwee	Schusler	2.1	6.9
Saniya	Kalloufi	2.1	6.9

SIGNUM [esql-signum]

Syntax

:::{image} ../../../../images/signum.svg :alt: Embedded :class: text-center :::

Parameters

number : Numeric expression. If null, the function returns null.

Description

Returns the sign of the given number. It returns -1 for negative numbers, 0 for 0 and 1 for positive numbers.

Supported types

number	result
double	double
integer	double
long	double
unsigned_long	double

Example

ROW d = 100.0
| EVAL s = SIGNUM(d)

d: double	s:double
100	1.0

SIN [esql-sin]

Syntax

:::{image} ../../../../images/sin.svg :alt: Embedded :class: text-center :::

Parameters

angle : An angle, in radians. If null, the function returns null.

Description

Returns the sine of an angle.

Supported types

angle	result
double	double
integer	double
long	double
unsigned_long	double

Example

ROW a=1.8
| EVAL sin=SIN(a)

a:double	sin:double
1.8	0.9738476308781951

SINH [esql-sinh]

Syntax

:::{image} ../../../../images/sinh.svg :alt: Embedded :class: text-center :::

Parameters

number : Numeric expression. If null, the function returns null.

Description

Returns the hyperbolic sine of a number.

Supported types

number	result
double	double
integer	double
long	double
unsigned_long	double

Example

ROW a=1.8
| EVAL sinh=SINH(a)

a:double	sinh:double
1.8	2.94217428809568

SQRT [esql-sqrt]

Syntax

:::{image} ../../../../images/sqrt.svg :alt: Embedded :class: text-center :::

Parameters

number : Numeric expression. If null, the function returns null.

Description

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 and infinities are null.

Supported types

number	result
double	double
integer	double
long	double
unsigned_long	double

Example

ROW d = 100.0
| EVAL s = SQRT(d)

d: double	s:double
100.0	10.0

TAN [esql-tan]

Syntax

:::{image} ../../../../images/tan.svg :alt: Embedded :class: text-center :::

Parameters

angle : An angle, in radians. If null, the function returns null.

Description

Returns the tangent of an angle.

Supported types

angle	result
double	double
integer	double
long	double
unsigned_long	double

Example

ROW a=1.8
| EVAL tan=TAN(a)

a:double	tan:double
1.8	-4.286261674628062

TANH [esql-tanh]

Syntax

:::{image} ../../../../images/tanh.svg :alt: Embedded :class: text-center :::

Parameters

number : Numeric expression. If null, the function returns null.

Description

Returns the hyperbolic tangent of a number.

Supported types

number	result
double	double
integer	double
long	double
unsigned_long	double

Example

ROW a=1.8
| EVAL tanh=TANH(a)

a:double	tanh:double
1.8	0.9468060128462683

TAU [esql-tau]

Syntax

:::{image} ../../../../images/tau.svg :alt: Embedded :class: text-center :::

Parameters

Description

Returns the ratio of a circle’s circumference to its radius.

Supported types

result
double

Example

ROW TAU()

TAU():double
6.283185307179586