Math functions

These functions can be used when analysing numeric data and numeric collections.

math::abs

The math::abs function returns the absolute value of a number.

API DEFINITION
math::abs(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::abs(-13.746189);

13.746189

math::acos

Available since: v2.0.0

The math::acos function returns the arccosine (inverse cosine) of a number, which must be in the range -1 to 1. The result is expressed in radians.

API DEFINITION
math::acos(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::acos(0.5);

1.0471975511965979

math::acot

Available since: v2.0.0

The math::acot function returns the arccotangent (inverse cotangent) of a number. The result is expressed in radians.

API DEFINITION
math::acot(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::acot(1);

0.7853981633974483

math::asin

Available since: v2.0.0

The math::asin function returns the arcsine (inverse sine) of a number, which must be in the range -1 to 1. The result is expressed in radians.

API DEFINITION
math::asin(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::asin(0.5);

0.5235987755982989

math::atan

Available since: v2.0.0

The math::atan function returns the arctangent (inverse tangent) of a number. The result is expressed in radians.

API DEFINITION
math::atan(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::atan(1);

0.7853981633974483

math::bottom

The math::bottom function returns the bottom X set of numbers in a set of numbers.

API DEFINITION
math::bottom(array<number>, number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::bottom([1, 2, 3], 2);

[ 2, 1 ]

math::ceil

The math::ceil function rounds a number up to the next largest integer.

API DEFINITION
math::ceil(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::ceil(13.146572);

14

math::clamp

Available since: v2.0.0

The math::clamp function constrains a number within the specified range, defined by a minimum and a maximum value. If the number is less than the minimum, it returns the minimum. If it is greater than the maximum, it returns the maximum.

API DEFINITION
math::clamp(number, min, max) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::clamp(1, 5, 10);

5

math::cos

Available since: v2.0.0

The math::cos function returns the cosine of a number, which is assumed to be in radians. The result is a value between -1 and 1.

API DEFINITION
math::cos(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::cos(1);

0.5403023058681398

math::cot

Available since: v2.0.0

The math::cot function returns the cotangent of a number, which is assumed to be in radians. The cotangent is the reciprocal of the tangent function.

API DEFINITION
math::cot(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::cot(1);

0.6420926159343306

math::deg2rad

Available since: v2.0.0

The math::deg2rad function converts an angle from degrees to radians.

API DEFINITION
math::deg2rad(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::deg2rad(180);

3.141592653589793

math::e

The math::e constant represents the base of the natural logarithm (Euler’s number).

API DEFINITION
math::e -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::e;

2.718281828459045f

math::fixed

The math::fixed function returns a number with the specified number of decimal places.

API DEFINITION
math::fixed(number, number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::fixed(13.146572, 2);

13.15

math::floor

The math::floor function rounds a number down to the nearest integer.

API DEFINITION
math::floor(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::floor(13.746189);

13

math::frac_1_pi

The math::frac_1_pi constant represents the fraction 1/π.

API DEFINITION
math::frac_1_pi -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::frac_1_pi;

0.3183098861837907f

math::frac_1_sqrt_2

The math::frac_1_sqrt_2 constant represents the fraction 1/sqrt(2).

API DEFINITION
math::frac_1_sqrt_2 -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::frac_1_sqrt_2;

0.7071067811865476f

math::frac_2_pi

The math::frac_2_pi constant represents the fraction 2/π.

API DEFINITION
math::frac_2_pi -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::frac_2_pi;

0.6366197723675814f

math::frac_2_sqrt_pi

The math::frac_2_sqrt_pi constant represents the fraction 2/sqrt(π).

API DEFINITION
math::frac_2_sqrt_pi -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::frac_2_sqrt_pi;

1.1283791670955126f

math::frac_pi_2

The math::frac_pi_2 constant represents the fraction π/2.

API DEFINITION
math::frac_pi_2 -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::frac_pi_2;

1.5707963267948966f

math::frac_pi_3

The math::frac_pi_3 constant represents the fraction π/3.

API DEFINITION
math::frac_pi_3 -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::frac_pi_3;

1.0471975511965979f

math::frac_pi_4

The math::frac_pi_4 constant represents the fraction π/4.

API DEFINITION
math::frac_pi_4 -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::frac_pi_4;

0.7853981633974483f

math::frac_pi_6

The math::frac_pi_6 constant represents the fraction π/6.

API DEFINITION
math::frac_pi_6 -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::frac_pi_6;

0.5235987755982989f

math::frac_pi_8

The math::frac_pi_8 constant represents the fraction π/8.

API DEFINITION
math::frac_pi_8 -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::frac_pi_8;

0.39269908169872414f

math::inf

The math::inf constant represents positive infinity.

API DEFINITION
math::inf -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::inf;

inf

math::interquartile

The math::interquartile function returns the interquartile of an array of numbers.

API DEFINITION
math::interquartile(array<number>) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::interquartile([ 1, 40, 60, 10, 2, 901 ]);

51

math::lerp

Available since: v2.0.0

The math::lerp function performs a linear interpolation between two numbers (a and b) based on a given fraction (t). The fraction t should be between 0 and 1, where 0 returns a and 1 returns b.

API DEFINITION
math::lerp(a, b, t) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::lerp(0, 10, 0.5);

5

math::lerpangle

Available since: v2.0.0

The math::lerpangle function interpolates between two angles (a and b) by the given fraction (t). This is useful for smoothly transitioning between angles.

API DEFINITION
math::lerpangle(a, b, t) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::lerpangle(0, 180, 0.5);

90

math::ln

Available since: v2.0.0

The math::ln function returns the natural logarithm (base e) of a number.

API DEFINITION
math::ln(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::ln(10);

2.302585092994046

math::ln_10

The math::ln_10 constant represents the natural logarithm (base e) of 10.

API DEFINITION
math::ln_10 -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::ln_10;

2.302585092994046f

math::ln_2

The math::ln_2 constant represents the natural logarithm (base e) of 2.

API DEFINITION
math::ln_2 -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::ln_2;

0.6931471805599453f

math::log

Available since: v2.0.0

The math::log function returns the logarithm of a number with a specified base.

API DEFINITION
math::log(number, base) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::log(100, 10);

2

math::log10

Available since: v2.0.0

The math::log10 function returns the base-10 logarithm of a number.

API DEFINITION
math::log10(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::log10(1000);

3

math::log10_2

The math::log10_2 constant represents the base-10 logarithm of 2.

API DEFINITION
math::log10_2 -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::log10_2;

0.3010299956639812f

math::log10_e

The math::log10_e constant represents the base-10 logarithm of e, the base of the natural logarithm (Euler’s number).

API DEFINITION
math::log10_e -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::log10_e;

0.4342944819032518f

math::log2

Available since: v2.0.0

The math::log2 function returns the base-2 logarithm of a number.

API DEFINITION
math::log2(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::log2(8);

3

math::log2_10

The math::log2_10 constant represents the base-2 logarithm of 10.

API DEFINITION
math::log2_10 -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::log2_10;

3.321928094887362f

math::log2_e

The math::log2_e constant represents the base-2 logarithm of e, the base of the natural logarithm (Euler’s number).

API DEFINITION
math::log2_e -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::log2_e;

1.4426950408889634f

math::max

The math::max function returns the greatest number from an array of numbers.

API DEFINITION
math::max(array<number>) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::max([ 26.164, 13.746189, 23, 16.4, 41.42 ]);

41.42

See also:

• array::max, which extracts the greatest value from an array of values
• time::max, which extracts the greatest datetime from an array of datetimes

math::mean

The math::mean function returns the mean of a set of numbers.

API DEFINITION
math::mean(array<number>) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::mean([ 26.164, 13.746189, 23, 16.4, 41.42 ]);

24.1460378

math::median

The math::median function returns the median of a set of numbers.

API DEFINITION
math::median(array<number>) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::median([ 26.164, 13.746189, 23, 16.4, 41.42 ]);

23

math::midhinge

The math::midhinge function returns the midhinge of an array of numbers.

API DEFINITION
math::midhinge(array<number>) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::midhinge([ 1, 40, 60, 10, 2, 901 ]);

29.5

math::min

The math::min function returns the least number from an array of numbers.

API DEFINITION
math::min(array<number>) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::min([ 26.164, 13.746189, 23, 16.4, 41.42 ]);

13.746189

See also:

• array::min, which extracts the least value from an array of values
• time::min, which extracts the least datetime from an array of datetimes

math::mode

The math::mode function returns the value that occurs most often in a set of numbers. In case of a tie, the highest one is returned.

API DEFINITION
math::mode(array<number>) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::mode([ 1, 40, 60, 10, 2, 901 ]);

901

math::nearestrank

The math::nearestrank function returns the nearestrank of an array of numbers.

API DEFINITION
math::nearestrank(array<number>, number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::nearestrank([1, 40, 60, 10, 2, 901], 50);

40

math::neg_inf

The math::neg_inf constant represents negative infinity.

API DEFINITION
math::neg_inf -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::neg_inf;

-inf

math::percentile

The math::percentile function returns the value below which a percentage of data falls.

API DEFINITION
math::percentile(array<number>, number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::percentile([1, 40, 60, 10, 2, 901], 50);

25

math::pi

The math::pi constant represents the mathematical constant π.

API DEFINITION
math::pi -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::pi;

3.141592653589793f

math::pow

The math::pow function returns a number raised to the power of a second number.

API DEFINITION
math::pow(number, number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::pow(1.07, 10);

1.9671513572895665f

math::product

The math::product function returns the product of a set of numbers.

API DEFINITION
math::product(array<number>) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::product([ 26.164, 13.746189, 23, 16.4, 41.42 ]);

5619119.004884841504

math::rad2deg

Available since: v2.0.0

The math::rad2deg function converts an angle from radians to degrees.

API DEFINITION
math::rad2deg(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::rad2deg(3.141592653589793);

180

math::round

The math::round function rounds a number up or down to the nearest integer.

API DEFINITION
math::round(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::round(13.53124);

14

math::sign

Available since: v2.0.0

The math::sign function returns the sign of a number, indicating whether the number is positive, negative, or zero. It returns 1 for positive numbers, -1 for negative numbers, and 0 for zero.

API DEFINITION
math::sign(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::sign(-42);

-1

math::sin

Available since: v2.0.0

The math::sin function returns the sine of a number, which is assumed to be in radians.

API DEFINITION
math::sin(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::sin(1);

0.8414709848078965

math::spread

The math::spread function returns the spread of an array of numbers.

API DEFINITION
math::spread(array<number>) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::spread([ 1, 40, 60, 10, 2, 901 ]);

900

math::sqrt

The math::sqrt function returns the square root of a number.

API DEFINITION
math::sqrt(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::sqrt(15);

3.872983346207417

math::sqrt_2

The math::sqrt_2 constant represents the square root of 2.

API DEFINITION
math::sqrt_2 -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::sqrt_2;

1.4142135623730951f

math::stddev

The math::stddev function calculates how far a set of numbers are away from the mean.

API DEFINITION
math::stddev(array<number>) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::stddev([ 1, 40, 60, 10, 2, 901 ]);

359.37167389765153

As of SurrealDB 3.0.0-alpha.11, this function can be used inside a table view.

DEFINE TABLE person SCHEMALESS;
DEFINE TABLE person_stats AS
	SELECT
		count(),
		age,
		math::stddev(score) AS score_stddev
	FROM person
	GROUP BY age;

math::sum

The math::sum function returns the total sum of a set of numbers.

API DEFINITION
math::sum(array<number>) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::sum([ 26.164, 13.746189, 23, 16.4, 41.42 ]);

-- 120.730189

This function on its own expects a numeric value at each point in an array, meaning that on its own it will not be able to be used on an array that contains NONE or NULL values.

math::sum([0, NONE, 10dec, 10.7, NULL]);

-- Error: Incorrect arguments for function math::sum().
-- Argument 1 was the wrong type.
-- Expected `number` but found `NONE` when coercing an element of `array<number>`

However, NONE and NULL can be coalesced into a default value by using the ?? operator (the “null coalescing operator”).

NONE ?? 0; -- Finds NONE so returns latter value: 0
1000 ?? 0; -- Finds 1000 so returns 1000 instead of 0

Inside an array the array::map() function can be used to ensure that each value is the number 0 if a NONE or NULL is encountered.

Classic array filtering can also be used to simply remove any NONE or NULL values before math::sum() is called.

// Classic array filtering, removes NONE / NULL
math::sum([0,NONE,10dec,10.7,NULL][? $this]);
// array::map() function, turns NONE / NULL to 0
[0, NONE, 10dec, 10.7, NULL].map(|$num| $num ?? 0);

With this mapping in place, math::sum() will be guaranteed to work.

// Classic array filtering
math::sum([0,NONE,10dec,10.7,NULL][? $this]);
// array::map() function
math::sum([0, NONE, 10dec, 10.7, NULL].map(|$num| $num ?? 0));

-- 20.7dec

math::tan

Available since: v2.0.0

The math::tan function returns the tangent of a number, which is assumed to be in radians.

API DEFINITION
math::tan(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::tan(1);

1.5574077246549023

math::tau

The math::tau constant represents the mathematical constant τ, which is equal to 2π.

API DEFINITION
math::tau -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::tau;

6.283185307179586f

math::top

The math::top function returns the top of an array of numbers.

API DEFINITION
math::top(array<number>, number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::top([1, 40, 60, 10, 2, 901], 3);

[ 40, 901, 60 ]

math::trimean

The math::trimean function returns the trimean of an array of numbers.

API DEFINITION
math::trimean(array<number>) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::trimean([ 1, 40, 60, 10, 2, 901 ]);

27.25

math::variance

The math::variance function returns the variance of an array of numbers.

API DEFINITION
math::variance(array<number>) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN math::variance([ 1, 40, 60, 10, 2, 901 ]);

129148

As of SurrealDB 3.0.0-alpha.11, this function can be used inside a table view.

DEFINE TABLE person SCHEMALESS;
DEFINE TABLE person_stats AS
	SELECT
		count(),
		age,
		math::variance(score) AS score_variance
	FROM person
	GROUP BY age;