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.746189f
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);
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);
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);
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);
math::bottom
The math::bottom function returns the bottom X set of numbers in an array of numbers.
API DEFINITION
math::bottom(array<number>, $quantity: number) -> number
The following example shows this function, and its output, when used in a RETURN statement:
RETURN math::bottom([1, 2, 3], 2);
math::ceil
The math::ceil function rounds a number up to the next largest whole number.
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);
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: number, $max: number) -> number
The following example shows this function, and its output, when used in a RETURN statement:
RETURN math::clamp(1, 5, 10);
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);
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);
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);
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;
math::fixed
The math::fixed function returns a number with the specified number of decimal places.
API DEFINITION
math::fixed(number, $places: number) -> number
The following example shows this function, and its output, when used in a RETURN statement:
RETURN math::fixed(13.146572, 2);
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);
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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 ]);
math::lerp
Available since: v2.0.0
The math::lerp function performs a linear interpolation between two numbers based on a given fraction. The fraction will usually be between 0 and 1, where 0 returns $num_1 and 1 returns $num_2.
API DEFINITION
math::lerp($num_1: number, $num_2: number, $fraction: number) -> number
The following example shows this function, and its output, when used in a RETURN statement:
RETURN math::lerp(0, 10, 0.5);
The function will not return an error if the third argument is not in the range of 0 to 1. Instead, it will extrapolate linearly beyond the first two numbers.
RETURN math::lerp(0, 10, 2);
math::lerpangle
Available since: v2.0.0
The math::lerpangle function interpolates between two angles ($num_1 and $num_2) by the given fraction. This is useful for smoothly transitioning between angles.
API DEFINITION
math::lerpangle($num_1: number, $num_2: number, $fraction: number) -> number
The following example shows this function, and its output, when used in a RETURN statement:
RETURN math::lerpangle(0, 180, 0.5);
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);
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;
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;
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) -> number
The following example shows this function, and its output, when used in a RETURN statement:
RETURN math::log(100, 10);
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);
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;
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;
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);
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;
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;
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 ]);
See also:
array::max, which extracts the greatest value from an array of valuestime::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 ]);
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 ]);
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 ]);
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 ]);
See also:
array::min, which extracts the least value from an array of valuestime::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 ]);
RETURN math::mode([ 1, 40, 60, 10, 2, 901, 2 ]);
math::nearestrank
The math::nearestrank function returns the nearest rank of an array of numbers by pullinng the closest extant record from the dataset at the %-th percentile.
API DEFINITION
math::nearestrank(array<number>, $percentile: 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);
A number for the percentile outside of the range 0 to 100 will return the output NaN.
math::nearestrank([1, 40, 60, 10, 2, 901], 101);
math::nearestrank([1, 40, 60, 10, 2, 901], -1);
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;
-Infinity
math::percentile
The math::percentile function returns the value below which a percentage of data falls by getting the N percentile, averaging neighboring records if non-exact.
API DEFINITION
math::percentile(array<number>, $percentile: 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);
A number for the percentile outside of the range 0 to 100 will return the output NaN.
math::percentile([1, 40, 60, 10, 2, 901], 101);
math::percentile([1, 40, 60, 10, 2, 901], -1);
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;
math::pow
The math::pow function returns a number raised to the power of a second number.
API DEFINITION
math::pow(number, $raise_to: number) -> number
The following example shows this function, and its output, when used in a RETURN statement:
RETURN math::pow(1.07, 10);
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 ]);
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);
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);
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);
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);
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 ]);
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);
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;
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 ]);
As of SurrealDB 3.0.0-beta, 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 ]);
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]);
However, NONE and NULL can be coalesced into a default value by using the ?? operator (the “null coalescing operator”).
NONE ?? 0;
1000 ?? 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.
[0,NONE,10dec,10.7,NULL][? $this];
[0, NONE, 10dec, 10.7, NULL].map(|$num| $num ?? 0);
With this mapping in place, math::sum() will be guaranteed to work.
math::sum([0,NONE,10dec,10.7,NULL][? $this]);
math::sum([0, NONE, 10dec, 10.7, NULL].map(|$num| $num ?? 0));
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);
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;
math::top
The math::top function returns the top of an array of numbers.
API DEFINITION
math::top(array<number>, $quantity: 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);
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 ]);
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 ]);
As of SurrealDB 3.0.0-beta, 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;
