mirror of https://gitee.com/bigwinds/arangodb
575 lines
12 KiB
Plaintext
575 lines
12 KiB
Plaintext
!CHAPTER Numeric functions
|
|
|
|
AQL offers some numeric functions for calculations. The following functions are
|
|
supported:
|
|
|
|
!SUBSECTION ABS()
|
|
|
|
`ABS(value) → unsignedValue`
|
|
|
|
Return the absolute part of *value*.
|
|
|
|
- **value** (number): any number, positive or negative
|
|
- returns **unsignedValue** (number): the number without + or - sign
|
|
|
|
```js
|
|
ABS(-5) // 5
|
|
ABS(+5) // 5
|
|
ABS(3.5) // 3.5
|
|
```
|
|
|
|
!SUBSECTION ACOS()
|
|
|
|
`ACOS(value) → num`
|
|
|
|
Return the arccosine of *value*.
|
|
|
|
- **value** (number): the input value
|
|
- returns **num** (number|null): the arccosine of *value*, or *null* if *value* is
|
|
outside the valid range -1 and 1 (inclusive)
|
|
|
|
```js
|
|
ACOS(-1) // 3.141592653589793
|
|
ACOS(0) // 1.5707963267948966
|
|
ACOS(1) // 0
|
|
ACOS(2) // null
|
|
```
|
|
|
|
!SUBSECTION ASIN()
|
|
|
|
`ASIN(value) → num`
|
|
|
|
Return the arcsine of *value*.
|
|
|
|
- **value** (number): the input value
|
|
- returns **num** (number|null): the arcsine of *value*, or *null* if *value* is
|
|
outside the valid range -1 and 1 (inclusive)
|
|
|
|
```js
|
|
ASIN(1) // 1.5707963267948966
|
|
ASIN(0) // 0
|
|
ASIN(-1) // -1.5707963267948966
|
|
ASIN(2) // null
|
|
```
|
|
|
|
!SUBSECTION ATAN()
|
|
|
|
`ATAN(value) → num`
|
|
|
|
Return the arctangent of *value*.
|
|
|
|
- **value** (number): the input value
|
|
- returns **num** (number): the arctangent of *value*
|
|
|
|
```js
|
|
ATAN(-1) // -0.7853981633974483
|
|
ATAN(0) // 0
|
|
ATAN(10) // 1.4711276743037347
|
|
```
|
|
|
|
!SUBSECTION ATAN2()
|
|
|
|
`ATAN2(y, x) → num`
|
|
|
|
Return the arctangent of the quotient of *y* and *x*.
|
|
|
|
```js
|
|
ATAN2(0, 0) // 0
|
|
ATAN2(1, 0) // 1.5707963267948966
|
|
ATAN2(1, 1) // 0.7853981633974483
|
|
ATAN2(-10, 20) // -0.4636476090008061
|
|
```
|
|
|
|
!SUBSECTION AVERAGE()
|
|
|
|
`AVERAGE(numArray) → mean`
|
|
|
|
Return the average (arithmetic mean) of the values in *array*.
|
|
|
|
- **numArray** (array): an array of numbers, *null* values are ignored
|
|
- returns **mean** (number|null): the average value of *numArray*. If the array is
|
|
empty or contains *null* values only, *null* will be returned.
|
|
|
|
```js
|
|
AVERAGE( [5, 2, 9, 2] ) // 4.5
|
|
AVERAGE( [ -3, -5, 2 ] ) // -2
|
|
AVERAGE( [ 999, 80, 4, 4, 4, 3, 3, 3 ] ) // 137.5
|
|
```
|
|
|
|
!SUBSECTION CEIL()
|
|
|
|
`CEIL(value) → roundedValue`
|
|
|
|
Return the integer closest but not less than *value*.
|
|
|
|
- **value** (number): any number
|
|
- returns **roundedValue** (number): the value rounded to the ceiling
|
|
|
|
```js
|
|
CEIL(2.49) // 3
|
|
CEIL(2.50) // 3
|
|
CEIL(-2.50) // -2
|
|
CEIL(-2.51) // -2
|
|
```
|
|
|
|
!SUBSECTION COS()
|
|
|
|
`COS(value) → num`
|
|
|
|
Return the cosine of *value*.
|
|
|
|
- **value** (number): the input value
|
|
- returns **num** (number): the cosine of *value*
|
|
|
|
```js
|
|
COS(1) // 0.5403023058681398
|
|
COS(0) // 1
|
|
COS(-3.141592653589783) // -1
|
|
COS(RADIANS(45)) // 0.7071067811865476
|
|
```
|
|
|
|
!SUBSECTION DEGREES()
|
|
|
|
`DEGREES(rad) → num`
|
|
|
|
Return the angle converted from radians to degrees.
|
|
|
|
- **rad** (number): the input value
|
|
- returns **num** (number): the angle in degrees
|
|
|
|
```js
|
|
DEGREES(0.7853981633974483) // 45
|
|
DEGREES(0) // 0
|
|
DEGREES(3.141592653589793) // 180
|
|
```
|
|
|
|
!SUBSECTION EXP()
|
|
|
|
`EXP(value) → num`
|
|
|
|
Return Euler's constant (2.71828...) raised to the power of *value*.
|
|
|
|
- **value** (number): the input value
|
|
- returns **num** (number): Euler's constant raised to the power of *value*
|
|
|
|
```js
|
|
EXP(1) // 2.718281828459045
|
|
EXP(10) // 22026.46579480671
|
|
EXP(0) // 1
|
|
```
|
|
|
|
!SUBSECTION EXP2()
|
|
|
|
`EXP2(value) → num`
|
|
|
|
Return 2 raised to the power of *value*.
|
|
|
|
- **value** (number): the input value
|
|
- returns **num** (number): 2 raised to the power of *value*
|
|
|
|
```js
|
|
EXP2(16) // 65536
|
|
EXP2(1) // 2
|
|
EXP2(0) // 1
|
|
```
|
|
|
|
!SUBSECTION FLOOR()
|
|
|
|
`FLOOR(value) → roundedValue`
|
|
|
|
Return the integer closest but not greater than *value*.
|
|
|
|
- **value** (number): any number
|
|
- returns **roundedValue** (number): the value rounded to the floor
|
|
|
|
```js
|
|
FLOOR(2.49) // 2
|
|
FLOOR(2.50) // 2
|
|
FLOOR(-2.50) // -3
|
|
FLOOR(-2.51) // -3
|
|
```
|
|
|
|
!SUBSECTION LOG()
|
|
|
|
`LOG(value) → num`
|
|
|
|
Return the natural logarithm of *value*. The base is Euler's
|
|
constant (2.71828...).
|
|
|
|
- **value** (number): the input value
|
|
- returns **num** (number|null): the natural logarithm of *value*, or *null* if *value* is
|
|
equal or less than 0
|
|
|
|
```js
|
|
LOG(2.718281828459045) // 1
|
|
LOG(10) // 2.302585092994046
|
|
LOG(0) // null
|
|
```
|
|
|
|
!SUBSECTION LOG2()
|
|
|
|
`LOG2(value) → num`
|
|
|
|
Return the base 2 logarithm of *value*.
|
|
|
|
- **value** (number): the input value
|
|
- returns **num** (number|null): the base 2 logarithm of *value*, or *null* if *value* is
|
|
equal or less than 0
|
|
|
|
```js
|
|
LOG2(1024) // 10
|
|
LOG2(8) // 3
|
|
LOG2(0) // null
|
|
```
|
|
|
|
!SUBSECTION LOG10()
|
|
|
|
`LOG10(value) → num`
|
|
|
|
Return the base 10 logarithm of *value*.
|
|
|
|
- **value** (number): the input value
|
|
- returns **num** (number): the base 10 logarithm of *value*, or *null* if *value* is
|
|
equal or less than 0
|
|
|
|
```js
|
|
LOG10(10000) // 10
|
|
LOG10(10) // 1
|
|
LOG10(0) // null
|
|
```
|
|
!SUBSECTION MAX()
|
|
|
|
`MAX(anyArray) → max`
|
|
|
|
Return the greatest element of *anyArray*. The array is not limited to numbers.
|
|
Also see [type and value order](../Fundamentals/TypeValueOrder.md).
|
|
|
|
- **anyArray** (array): an array of numbers, *null* values are ignored
|
|
- returns **max** (any|null): the element with the greatest value. If the array is
|
|
empty or contains *null* values only, the function will return *null*.
|
|
|
|
```js
|
|
MAX( [5, 9, -2, null, 1] ) // 9
|
|
MAX( [ null, null ] ) // null
|
|
```
|
|
|
|
!SUBSECTION MEDIAN()
|
|
|
|
`MEDIAN(numArray) → median`
|
|
|
|
Return the median value of the values in *array*.
|
|
|
|
The array is sorted and the element in the middle is returned. If the array has an
|
|
even length of elements, the two center-most elements are interpolated by calculating
|
|
the average value (arithmetic mean).
|
|
|
|
- **numArray** (array): an array of numbers, *null* values are ignored
|
|
- returns **median** (number|null): the median of *numArray*. If the array is
|
|
empty or contains *null* values only, the function will return *null*.
|
|
|
|
```js
|
|
MEDIAN( [ 1, 2, 3] ) // 2
|
|
MEDIAN( [ 1, 2, 3, 4 ] ) // 2.5
|
|
MEDIAN( [ 4, 2, 3, 1 ] ) // 2.5
|
|
MEDIAN( [ 999, 80, 4, 4, 4, 3, 3, 3 ] ) // 4
|
|
```
|
|
|
|
!SUBSECTION MIN()
|
|
|
|
`MIN(anyArray) → min`
|
|
|
|
Return the smallest element of *anyArray*. The array is not limited to numbers.
|
|
Also see [type and value order](../Fundamentals/TypeValueOrder.md).
|
|
|
|
- **anyArray** (array): an array of numbers, *null* values are ignored
|
|
- returns **min** (any|null): the element with the smallest value. If the array is
|
|
empty or contains *null* values only, the function will return *null*.
|
|
|
|
```js
|
|
MIN( [5, 9, -2, null, 1] ) // -2
|
|
MIN( [ null, null ] ) // null
|
|
```
|
|
|
|
!SUBSECTION PERCENTILE()
|
|
|
|
`PERCENTILE(numArray, n, method) → percentile`
|
|
|
|
Return the *n*th percentile of the values in *numArray*.
|
|
|
|
- **numArray** (array): an array of numbers, *null* values are ignored
|
|
- **n** (number): must be between 0 (excluded) and 100 (included)
|
|
- **method** (string, *optional*): "rank" (default) or "interpolation"
|
|
- returns **percentile** (number|null): the *n*th percentile, or *null* if the
|
|
array is empty or only *null* values are contained in it or the percentile
|
|
cannot be calculated
|
|
|
|
```js
|
|
PERCENTILE( [1, 2, 3, 4], 50 ) // 2
|
|
PERCENTILE( [1, 2, 3, 4], 50, "rank" ) // 2
|
|
PERCENTILE( [1, 2, 3, 4], 50, "interpolation" ) // 2.5
|
|
```
|
|
|
|
!SUBSECTION PI()
|
|
|
|
`PI() → pi`
|
|
|
|
Return pi.
|
|
|
|
- returns **pi** (number): the first few significant digits of pi (3.141592653589793)
|
|
|
|
```js
|
|
PI() // 3.141592653589793
|
|
```
|
|
|
|
!SUBSECTION POW()
|
|
|
|
`POW(base, exp) → num`
|
|
|
|
Return the *base* to the exponent *exp*.
|
|
|
|
- **base** (number): the base value
|
|
- **exp** (number): the exponent value
|
|
- returns **num** (number): the exponentiated value
|
|
|
|
```js
|
|
POW( 2, 4 ) // 16
|
|
POW( 5, -1 ) // 0.2
|
|
POW( 5, 0 ) // 1
|
|
```
|
|
|
|
!SUBSECTION RADIANS()
|
|
|
|
`RADIANS(deg) → num`
|
|
|
|
Return the angle converted from degrees to radians.
|
|
|
|
- **deg** (number): the input value
|
|
- returns **num** (number): the angle in radians
|
|
|
|
```js
|
|
RADIANS(180) // 3.141592653589793
|
|
RADIANS(90) // 1.5707963267948966
|
|
RADIANS(0) // 0
|
|
```
|
|
|
|
!SUBSECTION RAND()
|
|
|
|
`RAND() → randomNumber`
|
|
|
|
Return a pseudo-random number between 0 and 1.
|
|
|
|
- returns **randomNumber** (number): a number greater than 0 and less than 1
|
|
|
|
```js
|
|
RAND() // 0.3503170117504508
|
|
RAND() // 0.6138226173882478
|
|
```
|
|
|
|
Complex example:
|
|
|
|
```js
|
|
LET coinFlips = (
|
|
FOR i IN 1..100000
|
|
RETURN RAND() > 0.5 ? "heads" : "tails"
|
|
)
|
|
RETURN MERGE(
|
|
FOR flip IN coinFlips
|
|
COLLECT f = flip WITH COUNT INTO count
|
|
RETURN { [f]: count }
|
|
)
|
|
```
|
|
|
|
Result:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"heads": 49902,
|
|
"tails": 50098
|
|
}
|
|
]
|
|
```
|
|
|
|
!SUBSECTION RANGE()
|
|
|
|
`RANGE(start, stop, step) → numArray`
|
|
|
|
Return an array of numbers in the specified range, optionally with increments
|
|
other than 1.
|
|
|
|
For integer ranges, use the [range operator](../Operators.md#range-operator)
|
|
instead for better performance.
|
|
|
|
- **start** (number): the value to start the range at (inclusive)
|
|
- **stop** (number): the value to end the range with (inclusive)
|
|
- **step** (number, *optional*): how much to increment in every step,
|
|
the default is *1.0*
|
|
- returns **numArray** (array): all numbers in the range as array
|
|
|
|
```js
|
|
RANGE(1, 4) // [ 1, 2, 3, 4 ]
|
|
RANGE(1, 4, 2) // [ 1, 3 ]
|
|
RANGE(1, 4, 3) // [ 1, 4 ]
|
|
RANGE(1.5, 2.5) // [ 1.5, 2.5 ]
|
|
RANGE(1.5, 2.5, 0.5) // [ 1.5, 2, 2.5 ]
|
|
RANGE(-0.75, 1.1, 0.5) // [ -0.75, -0.25, 0.25, 0.75 ]
|
|
```
|
|
|
|
!SUBSECTION ROUND()
|
|
|
|
`ROUND(value) → roundedValue`
|
|
|
|
Return the integer closest to *value*.
|
|
|
|
- **value** (number): any number
|
|
- returns **roundedValue** (number): the value rounded to the closest integer
|
|
|
|
```js
|
|
ROUND(2.49) // 2
|
|
ROUND(2.50) // 3
|
|
ROUND(-2.50) // -2
|
|
ROUND(-2.51) // -3
|
|
```
|
|
|
|
Rounding towards zero, also known as *trunc()* in C/C++, can be achieved with
|
|
a combination of the [ternary operator](../Operators.md#ternary-operator),
|
|
[CEIL()](#ceil) and [FLOOR()](#floor):
|
|
|
|
```js
|
|
LET rounded = value >= 0 ? FLOOR(value) : CEIL(value)
|
|
```
|
|
|
|
!SUBSECTION SIN()
|
|
|
|
`SIN(value) → num`
|
|
|
|
Return the sine of *value*.
|
|
|
|
- **value** (number): the input value
|
|
- returns **num** (number): the sine of *value*
|
|
|
|
```js
|
|
SIN(3.141592653589783 / 2) // 1
|
|
SIN(0) // 0
|
|
SIN(-3.141592653589783 / 2) // -1
|
|
SIN(RADIANS(270)) // -1
|
|
```
|
|
|
|
!SUBSECTION SQRT()
|
|
|
|
`SQRT(value) → squareRoot`
|
|
|
|
Return the square root of *value*.
|
|
|
|
- **value** (number): a number
|
|
- returns **squareRoot** (number): the square root of *value*
|
|
|
|
```js
|
|
SQRT(9) // 3
|
|
SQRT(2) // 1.4142135623730951
|
|
```
|
|
|
|
Other roots can be calculated with [POW()](#pow) like `POW(value, 1/n)`:
|
|
|
|
```js
|
|
// 4th root of 8*8*8*8 = 4096
|
|
POW(4096, 1/4) // 8
|
|
|
|
// cube root of 3*3*3 = 27
|
|
POW(27, 1/3) // 3
|
|
|
|
// square root of 3*3 = 9
|
|
POW(9, 1/2) // 3
|
|
```
|
|
|
|
!SUBSECTION STDDEV_POPULATION()
|
|
|
|
`STDDEV_POPULATION(numArray) → num`
|
|
|
|
Return the population standard deviation of the values in *array*.
|
|
|
|
- **numArray** (array): an array of numbers, *null* values are ignored
|
|
- returns **num** (number|null): the population standard deviation of *numArray*.
|
|
If the array is empty or only *null* values are contained in the array,
|
|
*null* will be returned.
|
|
|
|
```js
|
|
STDDEV_POPULATION( [ 1, 3, 6, 5, 2 ] ) // 1.854723699099141
|
|
```
|
|
|
|
!SUBSECTION STDDEV_SAMPLE()
|
|
|
|
`STDDEV_SAMPLE(numArray) → num`
|
|
|
|
Return the sample standard deviation of the values in *array*.
|
|
|
|
- **numArray** (array): an array of numbers, *null* values are ignored
|
|
- returns **num** (number|null): the sample standard deviation of *numArray*.
|
|
If the array is empty or only *null* values are contained in the array,
|
|
*null* will be returned.
|
|
|
|
```js
|
|
STDDEV_SAMPLE( [ 1, 3, 6, 5, 2 ] ) // 2.0736441353327724
|
|
```
|
|
|
|
!SUBSECTION SUM()
|
|
|
|
`SUM(numArray) → sum`
|
|
|
|
Return the sum of the values in *array*.
|
|
|
|
- **numArray** (array): an array of numbers, *null* values are ignored
|
|
- returns **sum** (number): the total of all values in *numArray*. If the array
|
|
is empty or only *null* values are contained in the array, *0* will be returned.
|
|
|
|
```js
|
|
SUM( [1, 2, 3, 4] ) // 10
|
|
SUM( [null, -5, 6] ) // 1
|
|
SUM( [ ] ) // 0
|
|
```
|
|
|
|
!SUBSECTION TAN()
|
|
|
|
`TAN(value) → num`
|
|
|
|
Return the tangent of *value*.
|
|
|
|
- **value** (number): the input value
|
|
- returns **num** (number): the tangent of *value*
|
|
|
|
```js
|
|
TAN(10) // 0.6483608274590866
|
|
TAN(5) // -3.380515006246586
|
|
TAN(0) // 0
|
|
```
|
|
|
|
!SUBSECTION VARIANCE_POPULATION()
|
|
|
|
`VARIANCE_POPULATION(numArray) → num`
|
|
|
|
Return the population variance of the values in *array*.
|
|
|
|
- **numArray** (array): an array of numbers, *null* values are ignored
|
|
- returns **num** (number|null): the population variance of *numArray*.
|
|
If the array is empty or only *null* values are contained in the array,
|
|
*null* will be returned.
|
|
|
|
```js
|
|
VARIANCE_POPULATION( [ 1, 3, 6, 5, 2 ] ) // 3.4400000000000004
|
|
```
|
|
|
|
!SUBSECTION VARIANCE_SAMPLE()
|
|
|
|
`VARIANCE_SAMPLE(array) → num`
|
|
|
|
Return the sample variance of the values in *array*.
|
|
|
|
- **numArray** (array): an array of numbers, *null* values are ignored
|
|
- returns **num** (number|null): the sample variance of *numArray*.
|
|
If the array is empty or only *null* values are contained in the array,
|
|
*null* will be returned.
|
|
|
|
```js
|
|
VARIANCE_SAMPLE( [ 1, 3, 6, 5, 2 ] ) // 4.300000000000001
|
|
```
|