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
Parameter
Type
Description
Required
expression
double, long
The numeric expression for which to calculate the absolute value.
required
Returns
The data type of the returned value is double, long, or duration.
Examples
Example 1
data record(x = -42.13),record(x = 0),record(x = 6.8545)| 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
Parameter
Type
Description
Required
expression
double, long
The numeric expression, angle in radians for which to calculate the acos.
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(x = -1),record(x = 0),record(x = 1)| 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
Parameter
Type
Description
Required
expression
double, long
The numeric expression, angle in radians for which to calculate the asin.
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(x = -1),record(x = 0),record(x = 1)| 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
Parameter
Type
Description
Required
expression
double, long
The numeric expression, angle in radians for which to calculate the atan.
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(x = -1),record(x = 0),record(x = 1)| 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
Parameter
Type
Description
Required
ordinate
double, long
The ordinate coordinate.
required
abscissa
double, long
The abscissa coordinate.
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(x = 1, y = 1),record(x = 2, y = 3),record(x = 4, y = 5)| 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
Parameter
Type
Description
Required
expression
timestamp, long, double, duration
The expression that should be aligned.
required
interval
duration, double, long
The interval by which to align the expression. Constraints: statically evaluated.
required
at
timestamp, number, duration
The offset to which each interval should be shifted. Default: 0. Constraints: The offset to which each interval should be shifted.
optional
Returns
The data type of the returned value is double, long, duration, or timestamp.
Examples
Example 1
data record(x = -42.13),record(x = 0),record(x = 6.8545),record(x = 27)| 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
data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400")),record(timestamp = toTimestamp("2022-12-24T18:13:23.672-0400")),record(timestamp = toTimestamp("2023-01-27T23:21:11.459-0400"))| 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.
data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400"))| 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
Parameter
Type
Description
Required
expression
double, long
The numeric expression to be rounded up.
required
Returns
The data type of the returned value is double or long.
Examples
Example 1
data record(x = -0.5),record(x = 0),record(x = 0.5)| 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
Parameter
Type
Description
Required
expression
double, long
The numeric expression, angle in radians for which to calculate the sin.
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(x = -pi()),record(x = 0),record(x = pi())| 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
Parameter
Type
Description
Required
expression
double, long
The numeric expression, angle in radians for which to calculate the cosh.
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(x = -1),record(x = 0),record(x = 1)| 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
Parameter
Type
Description
Required
expression
double, long
The numeric expression for which to calculate the real cubic root.
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(x = -8),record(x = -42.13),record(x = 0),record(x = 6.8545)| 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
Parameter
Type
Description
Required
expression
double, long
The angle to be converted from radians to degrees.
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(degree = 90),record(degree = 180)| fieldsAdd degreeToRadian(degree)
Query result:
degree
degreeToRadian(degree)
90
1.5708
180
3.1416
e
Returns Euler’s number.
Syntax
e()
Returns
The data type of the returned value is double.
Examples
Example 1
data record()| fieldsAdd e()
Query result:
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
Parameter
Type
Description
Required
expression
double, duration, long
The numeric expression for which to calculate the exponential function.
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(x = 1),record(x = 4)| fieldsAdd exp(x)
Query result:
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
Parameter
Type
Description
Required
expression
double, long
The numeric expression to be rounded down.
required
Returns
The data type of the returned value is double orlong.
Examples
Example 1
data record(x = -0.5),record(x = 0),record(x = 0.5)| 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
Parameter
Type
Description
Required
x
double, long
Length of the first of the catheti.
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(x = 1, y = 2),record(x = 3, y = 4),record(x = 5, y = 6)| 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
Parameter
Type
Description
Required
expression
double, long
The numeric expression for which to calculate the natural logarithm (base e).
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(x = e()),record(x = 0),record(x = 1),record(x = 6.8545)| 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
Parameter
Type
Description
Required
expression
double, long
The numeric expression for which to add one and calculate the natural logarithm (base e).
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(x = 0),record(x = 6.8545)| 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
Parameter
Type
Description
Required
expression
double, long
The numeric expression for which to calculate the decadic logarithm (base 10).
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(x = 6.8545),record(x = 100)| 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()
Returns
The data type of the returned value is double.
Examples
Example 1
data record()| fieldsAdd pi()
Query result:
pi()
3.1416
power
Raises a numeric expression to a given power.
Syntax
power(base, exponent)
Parameters
Parameter
Type
Description
Required
base
double, long
The numeric expression acting as the base of the power calculation.
required
exponent
double, long
The numeric expression acting as the exponent of the power calculation.
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(base = 2, exponent = 4),record(base = 3, exponent = 5)| 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
Parameter
Type
Description
Required
expression
double, long
The angle to be converted from radians to degrees.
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(radian = pi() / 2),record(radian = pi())| 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()
Returns
The data type of the returned value is double.
Examples
Example 1
data record()| fieldsAdd random()
Query result:
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
Parameter
Type
Description
Required
expressions
expressions
The numeric, timestamp or duration expression that should be aligned into bins.
required
interval
expression
The size of bins produced and the values that are aligned to it. Constraints: numeric_expression, duration_expression.
required
at
expression
The starting value for the first bin that is produced. Default: 0, EPOCH.
optional
Returns
The data type of the returned value is record.
Examples
Example 1
data record(x = -42.13),record(x = 0),record(x = 6.8545),record(x = 27)| fieldsAdd range(x, 10),range(x, 10, at: 5)
Query result:
x
range(x, 10)
range(x, 10, at:5)
-42.13
start: -50end: -40
start: -45end: -35
0
start: 0end: 10
start: -5end: 5
6.8545
start: 0end: 10
start: 5end: 15
27
start: 20end: 30
start: 25end: 35
Example 2
data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400")),record(timestamp = toTimestamp("2022-12-24T18:13:23.672-0400")),record(timestamp = toTimestamp("2023-01-27T23:21:11.459-0400"))| fieldsAdd range(timestamp, 1m),range(timestamp, 1d)
Query result:
timestamp
range(timestamp, 1m)
range(timestamp, 1d)
2019-08-01T13:30:00.000Z
start: 2019-08-01T13:30:00.000Zend: 2019-08-01T13:31:00.000Z
start: 2019-08-01T00:00:00.000Zend: 2019-08-02T00:00:00.000Z
2022-12-24T22:13:23.672Z
start: 2022-12-24T22:13:00.000Zend: 2022-12-24T22:14:00.000Z
start: 2022-12-24T00:00:00.000Zend: 2022-12-25T00:00:00.000Z
2023-01-28T03:21:11.459Z
start: 2023-01-28T03:21:00.000Zend: 2023-01-28T03:22:00.000Z
start: 2023-01-28T00:00:00.000Zend: 2023-01-29T00:00:00.000Z
Example 3
data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400"))| 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
Parameter
Type
Description
Required
expression
double, long
Numeric expression to be rounded.
required
decimals
long
Number of places after the decimal point.
optional
Returns
The data type of the returned value is double or long.
Examples
Example 1
data record(x = -0.5),record(x = 0),record(x = 0.5),record(x = 0.55)| fieldsAdd round(x),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
Parameter
Type
Description
Required
expression
double, long
The numeric expression for which to calculate the signum.
required
Returns
The data type of the returned value is double or long.
Examples
Example 1
data record(x = -42.13),record(x = 0),record(x = 6.8545)| 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
Parameter
Type
Description
Required
expression
double, long
The numeric expression, angle in radians for which to calculate the sin.
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(x = -pi() / 2),record(x = 0),record(x = pi() / 2)| 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
Parameter
Type
Description
Required
expression
double, long
The numeric expression, angle in radians for which to calculate the sinh.
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(x = -1),record(x = 0),record(x = 1)| 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
Parameter
Type
Description
Required
expression
double, long
The numeric expression for which to calculate the square root.
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(x = 4),record(x = 81),record(x = -14)| 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
Parameter
Type
Description
Required
expression
double, long
The numeric expression, angle in radians for which to calculate the tan.
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(x = -pi() / 4),record(x = 0),record(x = pi() / 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
Parameter
Type
Description
Required
expression
double, long
The numeric expression, angle in radians for which to calculate the tanh.
required
Returns
The data type of the returned value is double.
Examples
Example 1
data record(x = -1),record(x = 0),record(x = 1)| fieldsAdd tanh(x)
Query result:
x
tanh(x)
-1
-0.7616
0
0
1
0.7616