numerics
Table of Contents
Functions
- abs() : string
- Return the absolute value of a number.
- acos() : string
- Return the arccosine of a value.
- approxNearCosine() : string
- Return the approximate cosine similarity between two vectors, accelerated by a vector index.
- approxNearL2() : string
- Return the approximate L2 (Euclidean) distance between two vectors, accelerated by a vector index.
- asin() : string
- Return the arcsine of a value.
- atan() : string
- Return the arctangent of a value.
- atan2() : string
- Return the arctangent of the quotient of y and x.
- average() : string
- Return the average (arithmetic mean) of the values in an array.
- ceil() : string
- Return the integer closest but not less than the given value.
- cos() : string
- Return the cosine of a value.
- cosSimilarity() : string
- Return the cosine similarity between two vectors.
- degrees() : string
- Convert an angle from radians to degrees.
- exp() : string
- Return Euler's constant (e) raised to the power of a value.
- exp2() : string
- Return 2 raised to the power of a value.
- floor() : string
- Return the integer closest but not greater than the given value.
- l1Distance() : string
- Return the L1 (Manhattan / taxicab) distance between two vectors.
- l2Distance() : string
- Return the L2 (Euclidean) distance between two vectors.
- log() : string
- Return the natural logarithm of a value.
- log10() : string
- Return the base-10 logarithm of a value.
- log2() : string
- Return the base-2 logarithm of a value.
- max() : string
- Return the greatest element of an array.
- median() : string
- Return the median value of the values in an array.
- min() : string
- Return the smallest element of an array.
- percentile() : string
- Return the nth percentile of the values in an array.
- pi() : string
- Return the mathematical constant π (pi).
- pow() : string
- Return the base raised to the power of the exponent.
- product() : string
- Return the product of the values in an array.
- radians() : string
- Convert an angle from degrees to radians.
- rand() : string
- Return a pseudo-random number between 0 and 1.
- range() : string
- Return an array of numbers in the specified range.
- round() : string
- Return the integer closest to the given value.
- sin() : string
- Return the sine of a value.
- sqrt() : string
- Return the square root of a value.
- sum() : string
- Return the sum of the values in an array.
- tan() : string
- Return the tangent of a value.
Functions
abs()
Return the absolute value of a number.
abs(string|int|float $value) : string
This helper wraps the ArangoDB AQL function ABS(value) which returns the
absolute value (unsigned value) of a number, removing any negative sign.
Example AQL usage:
ABS(-5) // returns 5
ABS(5) // returns 5
ABS(doc.temperature) // returns absolute temperature value
Parameters
- $value : string|int|float
-
Any number, positive or negative.
Tags
Return values
string —The formatted AQL expression.
acos()
Return the arccosine of a value.
acos(string|int|float $value) : string
This helper wraps the ArangoDB AQL function ACOS(value) which returns
the arccosine (inverse cosine) of a value in radians. The value must be
between -1 and 1 (inclusive), otherwise it returns null.
Example AQL usage:
ACOS(1) // returns 0
ACOS(0) // returns 1.5707963267948966 (π/2)
ACOS(-1) // returns 3.141592653589793 (π)
ACOS(2) // returns null (out of range)
Parameters
- $value : string|int|float
-
The input value (must be between -1 and 1).
Tags
Return values
string —The formatted AQL expression.
approxNearCosine()
Return the approximate cosine similarity between two vectors, accelerated by a vector index.
approxNearCosine(string|int $x, string|int $y[, int|null $nProbe = null ]) : string
This helper wraps the ArangoDB AQL function APPROX_NEAR_COSINE(x, y).
One of the two operands must reference a document attribute covered by a
VectorIndex created with the
"cosine" metric; the other is the query vector. The closer the returned
value is to 1, the more similar the vectors are.
Because higher is more similar, you sort in descending order to get the
nearest neighbours first — which is exactly what aqlVectorSearch()
does for the cosine metric.
Requires ArangoDB started with the experimental vector index feature.
Example AQL usage:
FOR doc IN items
SORT APPROX_NEAR_COSINE(doc.embedding, @query) DESC
LIMIT 10
RETURN doc
Parameters
- $x : string|int
-
First operand — the stored attribute or the query vector.
- $y : string|int
-
Second operand — the query vector or the stored attribute.
- $nProbe : int|null = null
-
Optional number of neighbouring centroids to probe (higher = more accurate, slower).
Tags
Return values
string —The formatted AQL expression.
approxNearL2()
Return the approximate L2 (Euclidean) distance between two vectors, accelerated by a vector index.
approxNearL2(string|int $x, string|int $y[, int|null $nProbe = null ]) : string
This helper wraps the ArangoDB AQL function APPROX_NEAR_L2(x, y).
One of the two operands must reference a document attribute covered by a
VectorIndex created with the
"l2" metric; the other is the query vector. The closer the returned value
is to 0, the more similar the vectors are.
Because smaller is more similar, you sort in ascending order to get the
nearest neighbours first — which is exactly what aqlVectorSearch()
does for the l2 metric.
Requires ArangoDB started with the experimental vector index feature.
Example AQL usage:
FOR doc IN items
SORT APPROX_NEAR_L2(doc.embedding, @query) ASC
LIMIT 10
RETURN doc
Parameters
- $x : string|int
-
First operand — the stored attribute or the query vector.
- $y : string|int
-
Second operand — the query vector or the stored attribute.
- $nProbe : int|null = null
-
Optional number of neighbouring centroids to probe (higher = more accurate, slower).
Tags
Return values
string —The formatted AQL expression.
asin()
Return the arcsine of a value.
asin(string|int|float $value) : string
This helper wraps the ArangoDB AQL function ASIN(value) which returns
the arcsine (inverse sine) of a value in radians. The value must be
between -1 and 1 (inclusive), otherwise it returns null.
Example AQL usage:
ASIN(0) // returns 0
ASIN(1) // returns 1.5707963267948966 (π/2)
ASIN(-1) // returns -1.5707963267948966 (-π/2)
ASIN(2) // returns null (out of range)
Parameters
- $value : string|int|float
-
The input value (must be between -1 and 1).
Tags
Return values
string —The formatted AQL expression.
atan()
Return the arctangent of a value.
atan(string|int|float $value) : string
This helper wraps the ArangoDB AQL function ATAN(value) which returns
the arctangent (inverse tangent) of a value in radians. The value can be
any real number.
Example AQL usage:
ATAN(0) // returns 0
ATAN(1) // returns 0.7853981633974483 (π/4)
ATAN(-1) // returns -0.7853981633974483 (-π/4)
ATAN(INF) // returns 1.5707963267948966 (π/2)
Parameters
- $value : string|int|float
-
The input value (any real number).
Tags
Return values
string —The formatted AQL expression.
atan2()
Return the arctangent of the quotient of y and x.
atan2(string|int $y, string|int $x) : string
This helper wraps the ArangoDB AQL function ATAN2(y, x) which returns
the arctangent of y/x in radians, using the signs of both arguments to
determine the quadrant of the result. This is more accurate than ATAN(y/x)
for determining the angle from the origin to a point.
Example AQL usage:
ATAN2(0, 1) // returns 0
ATAN2(1, 1) // returns 0.7853981633974483 (π/4)
ATAN2(1, 0) // returns 1.5707963267948966 (π/2)
ATAN2(-1, -1) // returns -2.356194490192345 (-3π/4)
Parameters
- $y : string|int
-
The y coordinate.
- $x : string|int
-
The x coordinate.
Tags
Return values
string —The formatted AQL expression.
average()
Return the average (arithmetic mean) of the values in an array.
average(mixed $anyArray) : string
This helper wraps the ArangoDB AQL function AVERAGE(numArray) which calculates
the arithmetic mean of all numeric values in the given array.
Example AQL usage:
AVERAGE([5, 2, 9, 2]) // returns 4.5
AVERAGE(doc.scores) // returns average of scores array
AVERAGE([1, 2, 3, 4, 5]) // returns 3.0
Parameters
- $anyArray : mixed
-
Array expression containing numeric values.
Tags
Return values
string —The formatted AQL expression.
ceil()
Return the integer closest but not less than the given value.
ceil(string|int|float $value) : string
This helper wraps the ArangoDB AQL function CEIL(value) which rounds up
a number to the nearest integer that is greater than or equal to the value.
Example AQL usage:
CEIL(4.1) // returns 5
CEIL(4.9) // returns 5
CEIL(-4.1) // returns -4
CEIL(doc.price) // rounds up the price
Parameters
- $value : string|int|float
-
Any number to round up.
Tags
Return values
string —The formatted AQL expression.
cos()
Return the cosine of a value.
cos(string|int|float $value) : string
This helper wraps the ArangoDB AQL function COS(value) which returns
the cosine of a value in radians.
Example AQL usage:
COS(0) // returns 1
COS(1.5707963267948966) // returns 0 (cos(π/2))
COS(3.141592653589793) // returns -1 (cos(π))
COS(doc.angle) // returns cosine of the angle
Parameters
- $value : string|int|float
-
The input value in radians.
Tags
Return values
string —The formatted AQL expression.
cosSimilarity()
Return the cosine similarity between two vectors.
cosSimilarity(string|int $x, string|int $y) : string
This helper wraps the ArangoDB AQL function COSINE_SIMILARITY(x, y) which
calculates the cosine similarity between two vectors. Cosine similarity
measures the cosine of the angle between two vectors, ranging from -1 to 1.
Example AQL usage:
COSINE_SIMILARITY([1, 0], [1, 0]) // returns 1 (identical vectors)
COSINE_SIMILARITY([1, 0], [0, 1]) // returns 0 (orthogonal vectors)
COSINE_SIMILARITY([1, 0], [-1, 0]) // returns -1 (opposite vectors)
Parameters
- $x : string|int
-
First input array (vector).
- $y : string|int
-
Second input array (vector).
Tags
Return values
string —The formatted AQL expression.
degrees()
Convert an angle from radians to degrees.
degrees(string|int|float $rad) : string
This helper wraps the ArangoDB AQL function DEGREES(rad) which converts
an angle from radians to degrees using the conversion factor π radians = 180 degrees.
Example AQL usage:
DEGREES(0) // returns 0
DEGREES(1.5707963267948966) // returns 90 (π/2 radians = 90 degrees)
DEGREES(3.141592653589793) // returns 180 (π radians = 180 degrees)
DEGREES(6.283185307179586) // returns 360 (2π radians = 360 degrees)
Parameters
- $rad : string|int|float
-
The input value in radians.
Tags
Return values
string —The formatted AQL expression.
exp()
Return Euler's constant (e) raised to the power of a value.
exp(string|int|float $value) : string
This helper wraps the ArangoDB AQL function EXP(value) which returns
Euler's constant (approximately 2.71828) raised to the power of the given value.
This is the inverse of the natural logarithm function.
Example AQL usage:
EXP(0) // returns 1
EXP(1) // returns 2.718281828459045 (e)
EXP(2) // returns 7.38905609893065 (e²)
EXP(-1) // returns 0.36787944117144233 (1/e)
Parameters
- $value : string|int|float
-
The exponent value.
Tags
Return values
string —The formatted AQL expression.
exp2()
Return 2 raised to the power of a value.
exp2(string|int|float $value) : string
This helper wraps the ArangoDB AQL function EXP2(value) which returns
2 raised to the power of the given value. This is useful for binary
operations and exponential growth calculations.
Example AQL usage:
EXP2(0) // returns 1
EXP2(1) // returns 2
EXP2(2) // returns 4
EXP2(3) // returns 8
EXP2(-1) // returns 0.5
Parameters
- $value : string|int|float
-
The exponent value.
Tags
Return values
string —The formatted AQL expression.
floor()
Return the integer closest but not greater than the given value.
floor(string|int|float $value) : string
This helper wraps the ArangoDB AQL function FLOOR(value) which rounds down
a number to the nearest integer that is less than or equal to the value.
Example AQL usage:
FLOOR(4.1) // returns 4
FLOOR(4.9) // returns 4
FLOOR(-4.1) // returns -5
FLOOR(doc.price) // rounds down the price
Parameters
- $value : string|int|float
-
Any number to round down.
Tags
Return values
string —The formatted AQL expression.
l1Distance()
Return the L1 (Manhattan / taxicab) distance between two vectors.
l1Distance(string|int $x, string|int $y) : string
This helper wraps the ArangoDB AQL function L1_DISTANCE(x, y) which
calculates the sum of the absolute differences between the components of
two equally-sized numeric vectors. The smaller the value, the closer the
vectors are.
Unlike approxNearL2(), this computes the exact distance and does not require (nor benefit from) a vector index.
Example AQL usage:
L1_DISTANCE([1, 2], [4, 6]) // returns 7 (|1-4| + |2-6|)
L1_DISTANCE([0, 0], [0, 0]) // returns 0 (identical vectors)
Parameters
- $x : string|int
-
First input array (vector).
- $y : string|int
-
Second input array (vector).
Tags
Return values
string —The formatted AQL expression.
l2Distance()
Return the L2 (Euclidean) distance between two vectors.
l2Distance(string|int $x, string|int $y) : string
This helper wraps the ArangoDB AQL function L2_DISTANCE(x, y) which
calculates the straight-line distance between two equally-sized numeric
vectors (the square root of the sum of the squared component differences).
The smaller the value, the closer the vectors are.
Unlike approxNearL2(), this computes the exact distance and does not require (nor benefit from) a vector index.
Example AQL usage:
L2_DISTANCE([1, 2], [4, 6]) // returns 5 (sqrt(3² + 4²))
L2_DISTANCE([0, 0], [0, 0]) // returns 0 (identical vectors)
Parameters
- $x : string|int
-
First input array (vector).
- $y : string|int
-
Second input array (vector).
Tags
Return values
string —The formatted AQL expression.
log()
Return the natural logarithm of a value.
log(string|int|float $value) : string
This helper wraps the ArangoDB AQL function LOG(value) which returns
the natural logarithm (base e) of a value. The value must be greater than 0,
otherwise it returns null.
Example AQL usage:
LOG(1) // returns 0
LOG(2.718281828459045) // returns 1 (ln(e) = 1)
LOG(10) // returns 2.302585092994046
LOG(0) // returns null (invalid input)
LOG(-1) // returns null (invalid input)
Parameters
- $value : string|int|float
-
The input value (must be greater than 0).
Tags
Return values
string —The formatted AQL expression.
log10()
Return the base-10 logarithm of a value.
log10(string|int|float $value) : string
This helper wraps the ArangoDB AQL function LOG10(value) which returns
the base-10 logarithm (common logarithm) of a value. The value must be
greater than 0, otherwise it returns null.
Example AQL usage:
LOG10(1) // returns 0
LOG10(10) // returns 1
LOG10(100) // returns 2
LOG10(1000) // returns 3
LOG10(0) // returns null (invalid input)
Parameters
- $value : string|int|float
-
The input value (must be greater than 0).
Tags
Return values
string —The formatted AQL expression.
log2()
Return the base-2 logarithm of a value.
log2(string|int|float $value) : string
This helper wraps the ArangoDB AQL function LOG2(value) which returns
the base-2 logarithm of a value. The value must be greater than 0,
otherwise it returns null.
Example AQL usage:
LOG2(1) // returns 0
LOG2(2) // returns 1
LOG2(4) // returns 2
LOG2(8) // returns 3
LOG2(0) // returns null (invalid input)
Parameters
- $value : string|int|float
-
The input value (must be greater than 0).
Tags
Return values
string —The formatted AQL expression.
max()
Return the greatest element of an array.
max(mixed $anyArray) : string
This helper wraps the ArangoDB AQL function MAX(anyArray) which returns
the maximum value from an array. The array is not limited to numbers and
can contain any comparable values.
Example AQL usage:
MAX([5, 2, 9, 2]) // returns 9
MAX(doc.scores) // returns highest score
MAX(["a", "b", "c"]) // returns "c"
Parameters
- $anyArray : mixed
-
Array expression to find maximum value from.
Tags
Return values
string —The formatted AQL expression.
median()
Return the median value of the values in an array.
median(mixed $anyArray) : string
This helper wraps the ArangoDB AQL function MEDIAN(anyArray) which returns
the median (middle value) of all values in the given array. The median is
the value separating the higher half from the lower half of the data set.
Example AQL usage:
MEDIAN([5, 2, 9, 2]) // returns 3.5 (average of 2 and 5)
MEDIAN([1, 2, 3, 4, 5]) // returns 3 (middle value)
MEDIAN([1, 2, 3, 4]) // returns 2.5 (average of 2 and 3)
MEDIAN(doc.scores) // returns median of scores array
Parameters
- $anyArray : mixed
-
Array expression containing numeric values.
Tags
Return values
string —The formatted AQL expression.
min()
Return the smallest element of an array.
min(mixed $anyArray) : string
This helper wraps the ArangoDB AQL function MIN(anyArray) which returns
the minimum value from an array. The array is not limited to numbers and
can contain any comparable values.
Example AQL usage:
MIN([5, 2, 9, 2]) // returns 2
MIN(doc.scores) // returns lowest score
MIN(["a", "b", "c"]) // returns "a"
Parameters
- $anyArray : mixed
-
Array expression to find minimum value from.
Tags
Return values
string —The formatted AQL expression.
percentile()
Return the nth percentile of the values in an array.
percentile(mixed $numArray, int $position, string|null $method) : string
This helper wraps the ArangoDB AQL function PERCENTILE(numArray, n, method)
which returns the nth percentile of all values in the given array. The position
must be between 0 (excluded) and 100 (included).
Example AQL usage:
PERCENTILE([1, 2, 3, 4, 5], 50) // returns 3 (50th percentile)
PERCENTILE([1, 2, 3, 4, 5], 25) // returns 2 (25th percentile)
PERCENTILE([1, 2, 3, 4, 5], 75) // returns 4 (75th percentile)
PERCENTILE([1, 2, 3, 4, 5], 50, "interpolation") // returns 3 (with interpolation)
Parameters
- $numArray : mixed
-
Array expression containing numeric values (null values are ignored).
- $position : int
-
The percentile position (must be between 0 and 100).
- $method : string|null
-
Optional method: "rank" (default) or "interpolation".
Tags
Return values
string —The formatted AQL expression.
pi()
Return the mathematical constant π (pi).
pi() : string
This helper wraps the ArangoDB AQL function PI() which returns
the mathematical constant π (pi), approximately 3.141592653589793.
Example AQL usage:
PI() // returns 3.141592653589793
PI() * 2 // returns 6.283185307179586 (2π)
PI() / 2 // returns 1.5707963267948966 (π/2)
Tags
Return values
string —The formatted AQL expression.
pow()
Return the base raised to the power of the exponent.
pow(mixed $base, int $exp) : string
This helper wraps the ArangoDB AQL function POW(base, exp) which returns
the base raised to the power of the exponent. This is equivalent to base^exp.
Example AQL usage:
POW(2, 3) // returns 8 (2³)
POW(10, 2) // returns 100 (10²)
POW(5, 0) // returns 1 (any number to power 0)
POW(2, -1) // returns 0.5 (2⁻¹)
Parameters
- $base : mixed
-
The base value.
- $exp : int
-
The exponent value.
Tags
Return values
string —The formatted AQL expression.
product()
Return the product of the values in an array.
product(mixed $numArray) : string
This helper wraps the ArangoDB AQL function PRODUCT(numArray) which calculates
the product (multiplication) of all numeric values in the given array.
Example AQL usage:
PRODUCT([1, 2, 3, 4]) // returns 24 (1×2×3×4)
PRODUCT([5, 2]) // returns 10 (5×2)
PRODUCT([10]) // returns 10 (single value)
PRODUCT(doc.factors) // returns product of factors array
Parameters
- $numArray : mixed
-
Array expression containing numeric values to multiply.
Tags
Return values
string —The formatted AQL expression.
radians()
Convert an angle from degrees to radians.
radians(string|int|float $deg) : string
This helper wraps the ArangoDB AQL function RADIANS(deg) which converts
an angle from degrees to radians using the conversion factor 180 degrees = π radians.
Example AQL usage:
RADIANS(0) // returns 0
RADIANS(90) // returns 1.5707963267948966 (π/2)
RADIANS(180) // returns 3.141592653589793 (π)
RADIANS(360) // returns 6.283185307179586 (2π)
Parameters
- $deg : string|int|float
-
The input value in degrees.
Tags
Return values
string —The formatted AQL expression.
rand()
Return a pseudo-random number between 0 and 1.
rand() : string
This helper wraps the ArangoDB AQL function RAND() which returns
a pseudo-random number between 0 (inclusive) and 1 (exclusive).
The algorithm for random number generation should be treated as opaque.
Example AQL usage:
RAND() // returns a random number like 0.123456789
RAND() * 100 // returns a random number between 0 and 100
FLOOR(RAND() * 6) + 1 // returns a random integer between 1 and 6
Tags
Return values
string —The formatted AQL expression.
range()
Return an array of numbers in the specified range.
range(int $start, int $stop[, float $step = 1.0 ]) : string
This helper wraps the ArangoDB AQL function RANGE(start, stop, step) which
generates an array of numbers from start to stop (exclusive) with the specified
step increment. The start and stop arguments are truncated to integers unless
a step argument is provided.
Example AQL usage:
RANGE(1, 5) // returns [1, 2, 3, 4]
RANGE(0, 10, 2) // returns [0, 2, 4, 6, 8]
RANGE(5, 1, -1) // returns [5, 4, 3, 2]
RANGE(1, 1) // returns [] (empty array)
Parameters
- $start : int
-
The starting value (inclusive).
- $stop : int
-
The ending value (exclusive).
- $step : float = 1.0
-
The step increment (default: 1.0).
Tags
Return values
string —The formatted AQL expression.
round()
Return the integer closest to the given value.
round(string|int|float $value) : string
This helper wraps the ArangoDB AQL function ROUND(value) which rounds
a number to the nearest integer using standard rounding rules.
Example AQL usage:
ROUND(4.1) // returns 4
ROUND(4.5) // returns 5
ROUND(4.9) // returns 5
ROUND(doc.price) // rounds the price to nearest integer
Parameters
- $value : string|int|float
-
Any number to round to nearest integer.
Tags
Return values
string —The formatted AQL expression.
sin()
Return the sine of a value.
sin(string|int|float $value) : string
This helper wraps the ArangoDB AQL function SIN(value) which returns
the sine of a value in radians.
Example AQL usage:
SIN(0) // returns 0
SIN(1.5707963267948966) // returns 1 (sin(π/2))
SIN(3.141592653589793) // returns 0 (sin(π))
SIN(doc.angle) // returns sine of the angle
Parameters
- $value : string|int|float
-
The input value in radians.
Tags
Return values
string —The formatted AQL expression.
sqrt()
Return the square root of a value.
sqrt(string|int|float $value) : string
This helper wraps the ArangoDB AQL function SQRT(value) which returns
the square root of a value. The value must be non-negative, otherwise
it returns null.
Example AQL usage:
SQRT(0) // returns 0
SQRT(1) // returns 1
SQRT(4) // returns 2
SQRT(9) // returns 3
SQRT(-1) // returns null (invalid input)
Parameters
- $value : string|int|float
-
The input value (must be non-negative).
Tags
Return values
string —The formatted AQL expression.
sum()
Return the sum of the values in an array.
sum(mixed $numArray) : string
This helper wraps the ArangoDB AQL function SUM(numArray) which calculates
the sum of all numeric values in the given array.
Example AQL usage:
SUM([1, 2, 3, 4]) // returns 10
SUM(doc.scores) // returns sum of all scores
SUM([5, 10, 15]) // returns 30
Parameters
- $numArray : mixed
-
Array expression containing numeric values to sum.
Tags
Return values
string —The formatted AQL expression.
tan()
Return the tangent of a value.
tan(string|int|float $value) : string
This helper wraps the ArangoDB AQL function TAN(value) which returns
the tangent of a value in radians.
Example AQL usage:
TAN(0) // returns 0
TAN(0.7853981633974483) // returns 1 (tan(π/4))
TAN(1.5707963267948966) // returns a very large number (tan(π/2))
TAN(doc.angle) // returns tangent of the angle
Parameters
- $value : string|int|float
-
The input value in radians.
Tags
Return values
string —The formatted AQL expression.