Mathematical functions

Functions executing mathematical calculations.

abs

Returns the absolute value of numeric_expression. Returns NULL if numeric_expression evaluates to NULL.

Syntax

abs(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression for which to calculate the absolute value.

Name	Type	Mandatory	Default	Constraints	Description
expression	double, long	yes			The numeric expression for which to calculate the absolute value.

Example

1data record(x = -42.13),
2     record(x = 0),
3     record(x = 6.8545)
4| fieldsAdd abs(x)

Query result

x	abs(x)
`-42.13`	`42.13`
`0`	`0`
`6.8545`	`6.8545`

acos

Computes arc cosine of expression. The returned angle is in the range 0.0 through pi. Returns null if expression evaluates to NULL.

Syntax

acos(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression, angle in radians for which to calculate the acos.

Name	Type	Mandatory	Default	Constraints	Description
expression	double, long	yes			The numeric expression, angle in radians for which to calculate the acos.

Example

1data record(x = -1),
2     record(x = 0),
3     record(x = 1)
4| fieldsAdd acos(x)

Query result

x	acos(x)
`-1`	`3.1416`
`0`	`1.5708`
`1`	`0`

asin

Computes arc sine of expression. The returned angle is in the range -pi/2 through pi/2. Returns null if <expression> evaluates to NULL.

Syntax

asin(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression, angle in radians for which to calculate the asin.

Name	Type	Mandatory	Default	Constraints	Description
expression	double, long	yes			The numeric expression, angle in radians for which to calculate the asin.

Example

1data record(x = -1),
2     record(x = 0),
3     record(x = 1)
4| fieldsAdd asin(x)

Query result

x	asin(x)
`-1`	`-1.5708`
`0`	`0`
`1`	`1.5708`

atan

Computes the arc tangent of expression. The returned angle is in the range -p/2 through pi/2. Returns null if expression evaluates to NULL.

Syntax

atan(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression, angle in radians for which to calculate the atan.

Name	Type	Mandatory	Default	Constraints	Description
expression	double, long	yes			The numeric expression, angle in radians for which to calculate the atan.

Example

1data record(x = -1),
2     record(x = 0),
3     record(x = 1)
4| fieldsAdd atan(x)

Query result

x	atan(x)
`-1`	`-0.7854`
`0`	`0`
`1`	`0.7854`

atan2

Computes the angle theta from the conversion of rectangular coordinates (x, y) to polar coordinates (r, theta). Returns null if either of the expressions evaluates to NULL.

Syntax

atan2(ordinate, abscissa)
Parameters

Name Type Mandatory Default Constraints Description
ordinate
double, long
yes
The ordinate coordinate.
abscissa
double, long
yes
The abscissa coordinate.

Name	Type	Mandatory	Default	Constraints	Description
ordinate	double, long	yes			The ordinate coordinate.
abscissa	double, long	yes			The abscissa coordinate.

Example

1data record(x = 1, y = 1),
2     record(x = 2, y = 3),
3     record(x = 4, y = 5)
4| fieldsAdd atan2(x, y)

Query result

x	y	atan2(x, y)
`1`	`1`	`0.7854`
`2`	`3`	`0.588`
`4`	`5`	`0.6747`

bin

Rounds values down to a multiple of a given numeric bin size.

Used frequently in combination with summarize , by: ..... If it encounters a scattered set of values, they will be grouped into a smaller set of specific values.

Syntax

bin(expression, interval)

Parameters

Name	Type	Mandatory	Default	Constraints	Description
expression	timestamp, long, double, duration	yes			The expression that should be aligned.
interval	duration, double, long	yes		statically evaluated	The interval by which to align the expression.
at	timestamp, number,duration	no	0	non zero, matched to the expression	The offset to which each interval should be shifted.

Example 1

1data record(x = -42.13),
2     record(x = 0),
3     record(x = 6.8545),
4     record(x = 27)
5| fieldsAdd bin(x, 10), bin(x, 10, at:5)

Query result

x	bin(x, 10)	bin(x, 10, at:5)
`-42.13`	`-50`	`-45`
`0`	`0`	`-5`
`6.8545`	`0`	`5`
`27`	`20`	`25`

Example 2

1data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400")),
2     record(timestamp = toTimestamp("2022-12-24T18:13:23.672-0400")),
3     record(timestamp = toTimestamp("2023-01-27T23:21:11.459-0400"))
4| fieldsAdd bin(timestamp, 1m), bin(timestamp, 1d)

Query result

timestamp	bin(timestamp, 1m)	bin(timestamp, 1d)
`2019-08-01T13:30:00.000Z`	`2019-08-01T13:30:00.000Z`	`2019-08-01T00:00:00.000Z`
`2022-12-24T22:13:23.672Z`	`2022-12-24T22:13:00.000Z`	`2022-12-24T00:00:00.000Z`
`2023-01-28T03:21:11.459Z`	`2023-01-28T03:21:00.000Z`	`2023-01-28T00:00:00.000Z`

Example 3

In this example, we align the timestamp to noon.
```
1data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400"))
2| fieldsAdd bin(timestamp, 1d, at: 12h)
```
Query result

timestamp bin(timestamp, 1d, at:12h)
2019-08-01T13:30:00.000Z
2019-08-01T12:00:00.000Z

ceil

Calculates the smallest (closest to negative infinity) double value greater than or equal to the numeric_expression; is equal to a mathematical integer. Returns null if numeric_expression evaluates to NULL. The return type is of the same type as the input parameter.

Syntax

ceil(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression to be rounded up.

Name	Type	Mandatory	Default	Constraints	Description
expression	double, long	yes			The numeric expression to be rounded up.

Example

1data record(x = -0.5),
2     record(x = 0),
3     record(x = 0.5)
4| fieldsAdd ceil(x)

Query result

x	ceil(x)
`-0.5`	`0`
`0`	`0`
`0.5`	`1`

cos

Computes the trigonometric cosine of an angle expression (in radians). Returns null if expression evaluates to NULL.

Syntax

cos(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression, angle in radians for which to calculate the sin.

Name	Type	Mandatory	Default	Constraints	Description
expression	double, long	yes			The numeric expression, angle in radians for which to calculate the sin.

Example

1data record(x = -pi()),
2     record(x = 0),
3     record(x = pi())
4| fieldsAdd cos(x)

Query result

x	cos(x)
`-3.1416`	`-1`
`0`	`1`
`3.1416`	`-1`

cosh

Computes the hyperbolic cosine of an angle <expression>. Returns null if <expression> evaluates to NULL.

Syntax

cosh(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression, angle in radians for which to calculate the cosh.

Name	Type	Mandatory	Default	Constraints	Description
expression	double, long	yes			The numeric expression, angle in radians for which to calculate the cosh.

Example

1data record(x = -1),
2     record(x = 0),
3     record(x = 1)
4| fieldsAdd cosh(x)

Query result

x	cosh(x)
`-1`	`1.5431`
`0`	`1`
`1`	`1.5431`

cbrt

Calculates the real cubic root of a numeric expression.

Syntax

cbrt (numeric_expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression for which to calculate the real cubic root.

Name	Type	Mandatory	Default	Constraints	Description
expression	double, long	yes			The numeric expression for which to calculate the real cubic root.

Example

In this example, we display the real cubic root of -8.

1data record(x = -8),
2     record(x = -42.13),
3     record(x = 0),
4     record(x = 6.8545)
5| fieldsAdd cbrt(x)

Query result

x	cbrt(x)
`-8`	`-2`
`-42.13`	`-3.4796`
`0`	`0`
`6.8545`	`1.8996`

degreeToRadian

Converts the numeric expression of an angle in degrees to an approximately equivalent angle as expressed in radians. Returns null if numeric_expr evaluates to NULL.

Syntax

degreeToRadian(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The angle to be converted from radians to degrees.

Name	Type	Mandatory	Default	Constraints	Description
expression	double, long	yes			The angle to be converted from radians to degrees.

Example

1data record(degree = 90),
2     record(degree = 180)
3| fieldsAdd degreeToRadian(degree)

Query result

degree	degreeToRadian(degree)
`90`	`1.5708`
`180`	`3.1416`

e

Returns Euler’s number.

Syntax

e()
Example

In this example, we display the value of Euler's number in the eNumber field.
```
1data record()
2| fieldsAdd e()
```
Query result

e()
2.7183

e()
`2.7183`

exp

Calculates the exponential function e^x, where e is the Euler's number and x is a numeric expression.

Syntax

exp(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression for which to calculate the exponential function.
Example

In this example, we display the exponential function of 1.
```
1data record(x = 1),
2     record(x = 4)
3| fieldsAdd exp(x)
```
Query result

x exp(x)
1
2.7183
4
54.5982

Name	Type	Mandatory	Default	Constraints	Description
expression	double, long	yes			The numeric expression for which to calculate the exponential function.

x	exp(x)
`1`	`2.7183`
`4`	`54.5982`

floor

Calculates the largest (closest to positive infinity) double value less than or equal to the numeric_expression; and is equal to a mathematical integer. Returns NULL if numeric_expression evaluates to NULL. The return type is of the same type as the input parameter.

Syntax

floor(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression to be rounded down.

Name	Type	Mandatory	Default	Constraints	Description
expression	double, long	yes			The numeric expression to be rounded down.

Example

1data record(x = -0.5),
2     record(x = 0),
3     record(x = 0.5)
4| fieldsAdd floor(x)

Query result

x	floor(x)
`-0.5`	`-1`
`0`	`0`
`0.5`	`0`

hypotenuse

Returns sqrt(x^2 + y^2). Returns null if expression evaluates to NULL.

Syntax

hypotenuse(x, y)
Parameters

Name Type Mandatory Default Constraints Description
x
double, long
yes
Length of the first of the catheti.

Name	Type	Mandatory	Default	Constraints	Description
x	double, long	yes			Length of the first of the catheti.

Example

1data record(x = 1, y = 2),
2     record(x = 3, y = 4),
3     record(x = 5, y = 6)
4| fieldsAdd hypotenuse(x, y)

Query result

x	y	hypotenuse(x, y)
`1`	`2`	`2.2361`
`3`	`4`	`5`
`5`	`6`	`7.8102`

log

Calculates the natural logarithm (the base is e, the Euler's number) of a numeric expression.

Syntax

log(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression for which to calculate the natural logarithm (base e).

Name	Type	Mandatory	Default	Constraints	Description
expression	double, long	yes			The numeric expression for which to calculate the natural logarithm (base e).

Example

1data record(x = e()),
2     record(x = 0),
3     record(x = 1),
4     record(x = 6.8545)
5| fieldsAdd log(x)

Query result

x	log(x)
`2.7183`	`1`
`0`	null
`1`	`0`
`6.8545`	`1.9249`

log1p

Calculates log(1+x), where log is the natural logarithm and x is a numeric expression.

Syntax

log1p(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression for which to add one and calculate the natural logarithm (base e).

Name	Type	Mandatory	Default	Constraints	Description
expression	double, long	yes			The numeric expression for which to add one and calculate the natural logarithm (base e).

Example

1data record(x = 0),
2     record(x = 6.8545)
3| fieldsAdd log1p(x)

Query result

x	log1p(x)
`0`	`0`
`6.8545`	`2.0611`

log10

Calculates the decadic (common) logarithm (the base is 10) of a numeric expression.

Syntax

log10(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression for which to calculate the decadic logarithm (base 10).

Name	Type	Mandatory	Default	Constraints	Description
expression	double, long	yes			The numeric expression for which to calculate the decadic logarithm (base 10).

Example

1data record(x = 6.8545),
2     record(x = 100)
3| fieldsAdd log10(x)

Query result

x	log10(x)
`6.8545`	`0.836`
`100`	`2`

pi

Returns the constant value of PI (Archimedes’ number).

Syntax

pi()
Example
```
1data record()
2| fieldsAdd pi()
```
Query result

pi()
3.1416

pi()
`3.1416`

power

Raises a numeric expression to a given power.

Syntax

power(base, exponent)

Parameters

Name	Type	Mandatory	Default	Constraints	Description
base	double, long	yes			The numeric expression acting as the base of the power calculation.
exponent	double, long	yes			The numeric expression acting as the exponent of the power calculation.

Example

In this example, we raise 2 to 3rd power.

1data record(base = 2, exponent = 4),
2     record(base = 3, exponent = 5)
3| fieldsAdd power(base, exponent)

Query result

base	exponent	power(base, exponent)
`2`	`4`	`16`
`3`	`5`	`243`

radianToDegree

Converts the numeric expression of an angle in radians to an approximately equivalent angle as expressed in degrees. Returns null if numeric_expr evaluates to NULL.

Syntax

radianToDegree(numeric_expr)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The angle to be converted from radians to degrees.

Name	Type	Mandatory	Default	Constraints	Description
expression	double, long	yes			The angle to be converted from radians to degrees.

Example

1data record(radian = pi() / 2),
2     record(radian = pi())
3| fieldsAdd radianToDegree(radian)

Query result

radian	radianToDegree(radian)
`1.5708`	`90`
`3.1416`	`180`

random

Creates a random double value. Generated values aren't deterministic. The value range of the generated double value is between 0.0 (inclusive) and 1.0 (exclusive).

Syntax

random()
Example
```
1data record()
2| fieldsAdd random()
```
Query result

random()
0.563

random()
`0.563`

range

Aligns the given value/timestamp to value range based on the provided alignment parameter. The range function is similar to the bin function, but produces a range instead, then provides information about the start and the end of the bin the value is aligned to.

Syntax

range(expression, interval [, at])

Parameters

Name	Type	Mandatory	Default	Constraints	Description
expressions	expression	yes			The numeric, timestamp or duration expression that should be aligned into bins.
interval	expression	yes		numeric_expression, duration_expression	The size of bins produced and the values that are aligned to it.
at	expression	no	0, EPOCH		The starting value for the first bin that is produced.

Example 1

1data record(x = -42.13),
2     record(x = 0),
3     record(x = 6.8545),
4     record(x = 27)
5| fieldsAdd range(x, 10),
6            range(x, 10, at: 5)

Query result

x	range(x, 10)	range(x, 10, at:5)
`-42.13`	start: `-50` end: `-40`	start: `-45` end: `-35`
`0`	start: `0` end: `10`	start: `-5` end: `5`
`6.8545`	start: `0` end: `10`	start: `5` end: `15`
`27`	start: `20` end: `30`	start: `25` end: `35`

Example 2

1data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400")),
2     record(timestamp = toTimestamp("2022-12-24T18:13:23.672-0400")),
3     record(timestamp = toTimestamp("2023-01-27T23:21:11.459-0400"))
4| fieldsAdd range(timestamp, 1m),
5            range(timestamp, 1d)

Query result

timestamp	range(timestamp, 1m)	range(timestamp, 1d)
`2019-08-01T13:30:00.000Z`	start: `2019-08-01T13:30:00.000Z` end: `2019-08-01T13:31:00.000Z`	start: `2019-08-01T00:00:00.000Z` end: `2019-08-02T00:00:00.000Z`
`2022-12-24T22:13:23.672Z`	start: `2022-12-24T22:13:00.000Z` end: `2022-12-24T22:14:00.000Z`	start: `2022-12-24T00:00:00.000Z` end: `2022-12-25T00:00:00.000Z`
`2023-01-28T03:21:11.459Z`	start: `2023-01-28T03:21:00.000Z` end: `2023-01-28T03:22:00.000Z`	start: `2023-01-28T00:00:00.000Z` end: `2023-01-29T00:00:00.000Z`

Example 3

1data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400"))
2| fieldsAdd bin(timestamp, 1d, at: 12h)

Query result

timestamp	bin(timestamp, 1d, at:12h)
`2019-08-01T13:30:00.000Z`	`2019-08-01T12:00:00.000Z`

round

Rounds any numeric value to the specified number of decimal places. If you don't specify the number of decimal places, it rounds to the nearest integer. The return type is of the same type as the input parameter.

Syntax

round(expression [, decimals])
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
Numeric expression to be rounded.
decimals
long
no
Number of places after the decimal point.

Name	Type	Mandatory	Default	Constraints	Description
expression	double, long	yes			Numeric expression to be rounded.
decimals	long	no			Number of places after the decimal point.

Example

1data record(x = -0.5),
2     record(x = 0),
3     record(x = 0.5),
4     record(x = 0.55)
5| fieldsAdd round(x),
6            round(x, decimals: 1)

Query result

x	round(x)	round(x, decimals:1)
`-0.5`	`0`	`-0.5`
`0`	`0`	`0`
`0.5`	`1`	`0.5`
`0.55`	`1`	`0.6`

signum

Returns the signum (sign) result of an argument. It returns one of four possible values: -1 (if numeric_expression evaluates to a value less than 0), 0 (if numeric_expression evaluates to 0), 1 (if numeric_expression evaluates to a value greater than 0), or null (if numeric_expression evaluates to NULL). The return type is of the same type as the input parameter.

Syntax

signum(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression for which to calculate the signum.

Name	Type	Mandatory	Default	Constraints	Description
expression	double, long	yes			The numeric expression for which to calculate the signum.

Example

1data record(x = -42.13),
2     record(x = 0),
3     record(x = 6.8545)
4| fieldsAdd signum(x)

Query result

x	signum(x)
`-42.13`	`-1`
`0`	`0`
`6.8545`	`1`

sin

Computes the trigonometric sine of angle <expression> (in radians). Returns null if <expression> evaluates to NULL.

Syntax

sin(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression, angle in radians for which to calculate the sin.

Example

1data record(x = -pi() / 2),
2     record(x = 0),
3     record(x = pi() / 2)
4| fieldsAdd sin(x)

Query result

x	sin(x)
`-1.5708`	`-1`
`0`	`0`
`1.5708`	`1`

sinh

Computes the hyperbolic sine of <expression>. Returns null if <expression> evaluates to NULL.

Syntax

sinh(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression, angle in radians for which to calculate the sinh.

Example

1data record(x = -1),
2     record(x = 0),
3     record(x = 1)
4| fieldsAdd sinh(x)

Query result

x	sinh(x)
`-1`	`-1.1752`
`0`	`0`
`1`	`1.1752`

sqrt

Computes the positive square root of a numeric expression.

Syntax

sqrt(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression for which to calculate the square root.

Example

1data record(x = 4),
2     record(x = 81),
3     record(x = -14)
4| fieldsAdd sqrt(x)

Query result

x	sqrt(x)
`4`	`2`
`81`	`9`
`-14`	null

tan

Computes the trigonometric tangent of angle expression (in radians). Returns null if expression evaluates to NULL.

Syntax

tan(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression, angle in radians for which to calculate the tan.

Example

1data record(x = -pi() / 4),
2     record(x = 0),
3     record(x = pi() / 4)
4| fieldsAdd tan(x)

Query result

x	tan(x)
`-0.7854`	`-1`
`0`	`0`
`0.7854`	`1`

tanh

Computes the hyperbolic tangent of expression. Returns null if expression evaluates to NULL.

Syntax

tanh(expression)
Parameters

Name Type Mandatory Default Constraints Description
expression
double, long
yes
The numeric expression, angle in radians for which to calculate the tanh.

Example

1data record(x = -1),
2     record(x = 0),
3     record(x = 1)
4| fieldsAdd tanh(x)

Query result

x	tanh(x)
`-1`	`-0.7616`
`0`	`0`
`1`	`0.7616`

Mathematical functions

abs

acos

asin

atan

atan2

bin

ceil

cos

cosh

cbrt

degreeToRadian

e

exp

floor

hypotenuse

log

log1p

log10

pi

power

radianToDegree

random

range

round

signum

sin

sinh

sqrt

tan

tanh

Related topics