mirror of https://gitee.com/bigwinds/arangodb
258 lines
10 KiB
Plaintext
258 lines
10 KiB
Plaintext
!CHAPTER List functions
|
|
|
|
AQL supports the following functions to operate on list values:
|
|
|
|
- *LENGTH(list)*: Returns the length (number of list elements) of *list*. If
|
|
*list* is a document, returns the number of attribute keys of the document,
|
|
regardless of their values.
|
|
|
|
- *FLATTEN(list), depth)*: Turns a list of lists into a flat list. All
|
|
list elements in *list* will be expanded in the result list. Non-list elements
|
|
are added as they are. The function will recurse into sub-lists up to a depth of
|
|
*depth*. *depth* has a default value of 1.
|
|
|
|
*Examples*
|
|
|
|
FLATTEN([ 1, 2, [ 3, 4 ], 5, [ 6, 7 ], [ 8, [ 9, 10 ] ])
|
|
|
|
will produce:
|
|
|
|
[ 1, 2, 3, 4, 5, 6, 7, 8, [ 9, 10 ] ]
|
|
|
|
To fully flatten the list, use a *depth* of 2:
|
|
|
|
FLATTEN([ 1, 2, [ 3, 4 ], 5, [ 6, 7 ], [ 8, [ 9, 10 ] ], 2)
|
|
|
|
This will produce:
|
|
|
|
[ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]
|
|
|
|
- *MIN(list)*: Returns the smallest element of *list*. *null* values
|
|
are ignored. If the list is empty or only *null* values are contained in the list, the
|
|
function will return *null*.
|
|
|
|
- *MAX(list)*: Returns the greatest element of *list*. *null* values
|
|
are ignored. If the list is empty or only *null* values are contained in the list, the
|
|
function will return *null*.
|
|
|
|
- *AVERAGE(list)*: Returns the average (arithmetic mean) of the values in *list*.
|
|
This requires the elements in *list* to be numbers. *null* values are ignored.
|
|
If the list is empty or only *null* values are contained in the list, the function
|
|
will return *null*.
|
|
|
|
- *SUM(list)*: Returns the sum of the values in *list*. This
|
|
requires the elements in *list* to be numbers. *null* values are ignored.
|
|
|
|
- *MEDIAN(list)*: Returns the median value of the values in *list*. This
|
|
requires the elements in *list* to be numbers. *null* values are ignored. If the
|
|
list is empty or only *null* values are contained in the list, the function will return
|
|
*null*.
|
|
|
|
- *PERCENTILE(list, n, method)*: Returns the *n*th percentile of the values in *list*.
|
|
This requires the elements in *list* to be numbers. *null* values are ignored. *n* must
|
|
be between 0 (excluded) and 100 (included). *method* can be *rank* or *interpolation*.
|
|
The function will return null if the list is empty or only *null* values are contained
|
|
in it or the percentile cannot be calculated.
|
|
|
|
- *VARIANCE_POPULATION(list)*: Returns the population variance of the values in
|
|
*list*. This requires the elements in *list* to be numbers. *null* values
|
|
are ignored. If the list is empty or only *null* values are contained in the list,
|
|
the function will return *null*.
|
|
|
|
- *VARIANCE_SAMPLE(list)*: Returns the sample variance of the values in
|
|
*list*. This requires the elements in *list* to be numbers. *null* values
|
|
are ignored. If the list is empty or only *null* values are contained in the list,
|
|
the function will return *null*.
|
|
|
|
- *STDDEV_POPULATION(list)*: Returns the population standard deviation of the
|
|
values in *list*. This requires the elements in *list* to be numbers. *null*
|
|
values are ignored. If the list is empty or only *null* values are contained in the list,
|
|
the function will return *null*.
|
|
|
|
- *STDDEV_SAMPLE(list)*: Returns the sample standard deviation of the values in
|
|
*list*. This requires the elements in *list* to be numbers. *null* values
|
|
are ignored. If the list is empty or only *null* values are contained in the list,
|
|
the function will return *null*.
|
|
|
|
- *REVERSE(list)*: Returns the elements in *list* in reversed order.
|
|
|
|
- *FIRST(list)*: Returns the first element in *list* or *null* if the
|
|
list is empty.
|
|
|
|
- *LAST(list)*: Returns the last element in *list* or *null* if the
|
|
list is empty.
|
|
|
|
- *NTH(list, position)*: Returns the list element at position *position*.
|
|
Positions start at 0. If *position* is negative or beyond the upper bound of the list
|
|
specified by *list*, then *null* will be returned.
|
|
|
|
- *POSITION(list, search, return-index)*: Returns the position of the
|
|
element *search* in list *list*. Positions start at 0. If the element is not
|
|
found, then *-1* is returned. If *return-index* is *false*, then instead of the
|
|
position only *true* or *false* are returned, depending on whether the sought element
|
|
is contained in the list.
|
|
|
|
- *SLICE(list, start, length)*: Extracts a slice of the list specified
|
|
by *list*. The extraction will start at list element with position *start*.
|
|
Positions start at 0. Up to *length* elements will be extracted. If *length* is
|
|
not specified, all list elements starting at *start* will be returned.
|
|
If *start* is negative, it can be used to indicate positions from the end of the
|
|
list.
|
|
|
|
*Examples*
|
|
|
|
SLICE([ 1, 2, 3, 4, 5 ], 0, 1)
|
|
|
|
will return *[ 1 ]*
|
|
|
|
SLICE([ 1, 2, 3, 4, 5 ], 1, 2)
|
|
|
|
will return *[ 2, 3 ]*
|
|
|
|
SLICE([ 1, 2, 3, 4, 5 ], 3)
|
|
|
|
will return *[ 4, 5 ]*
|
|
|
|
SLICE([ 1, 2, 3, 4, 5 ], 1, -1)
|
|
|
|
will return *[ 2, 3, 4 ]*
|
|
|
|
SLICE([ 1, 2, 3, 4, 5 ], 0, -2)
|
|
|
|
will return *[ 1, 2, 3 ]*
|
|
|
|
- *UNIQUE(list)*: Returns all unique elements in *list*. To determine
|
|
uniqueness, the function will use the comparison order.
|
|
Calling this function may return the unique elements in any order.
|
|
|
|
- *UNION(list1, list2, ...)*: Returns the union of all lists specified.
|
|
The function expects at least two list values as its arguments. The result is a list
|
|
of values in an undefined order.
|
|
|
|
Note: No duplicates will be removed. In order to remove duplicates, please use either
|
|
*UNION_DISTINCT* function or apply the *UNIQUE* on the result of *union*.
|
|
|
|
*Examples*
|
|
|
|
RETURN UNION(
|
|
[ 1, 2, 3 ],
|
|
[ 1, 2 ]
|
|
)
|
|
|
|
will produce:
|
|
|
|
[ [ 1, 2, 3, 1, 2 ] ]
|
|
|
|
with duplicate removal:
|
|
|
|
RETURN UNIQUE(
|
|
UNION(
|
|
[ 1, 2, 3 ],
|
|
[ 1, 2 ]
|
|
)
|
|
)
|
|
|
|
will produce:
|
|
|
|
[ [ 1, 2, 3 ] ]
|
|
|
|
- *UNION_DISTINCT(list1, list2, ...)*: Returns the union of distinct values of
|
|
all lists specified. The function expects at least two list values as its arguments.
|
|
The result is a list of values in an undefined order.
|
|
|
|
- *MINUS(list1, list2, ...)*: Returns the difference of all lists specified.
|
|
The function expects at least two list values as its arguments.
|
|
The result is a list of values that occur in the first list but not in any of the
|
|
subsequent lists. The order of the result list is undefined and should not be relied on.
|
|
Note: duplicates will be removed.
|
|
|
|
- *INTERSECTION(list1, list2, ...)*: Returns the intersection of all lists specified.
|
|
The function expects at least two list values as its arguments.
|
|
The result is a list of values that occur in all arguments. The order of the result list
|
|
is undefined and should not be relied on.
|
|
|
|
Note: Duplicates will be removed.
|
|
|
|
- *APPEND(list, values, unique)*: Adds all elements from the list *values* to the list
|
|
specified by *list*. If *unique* is set to true, then only those *values* will be added
|
|
that are not already contained in *list*.
|
|
The modified list is returned. All values are added at the end of the list (right side).
|
|
|
|
/* [ 1, 2, 3, 5, 6, 9 ] */
|
|
APPEND([ 1, 2, 3 ], [ 5, 6, 9 ])
|
|
|
|
/* [ 1, 2, 3, 4, 5, 9 ] */
|
|
APPEND([ 1, 2, 3 ], [ 3, 4, 5, 2, 9 ], true)
|
|
|
|
- *PUSH(list, value, unique)*: Adds *value* to the list specified by *list*. If
|
|
*unique* is set to true, then *value* is not added if already present in the list.
|
|
The modified list is returned. The value is added at the end of the list (right side).
|
|
|
|
Note: non-unique elements will not be removed from the list if they were already present
|
|
before the call to `PUSH`. The *unique* flag will only control if the value will
|
|
be added again to the list if already present. To make a list unique, use the `UNIQUE`
|
|
function.
|
|
|
|
/* [ 1, 2, 3, 4 ] */
|
|
PUSH([ 1, 2, 3 ], 4)
|
|
|
|
/* [ 1, 2, 3 ] */
|
|
PUSH([ 1, 2, 3 ], 2, true)
|
|
|
|
- *UNSHIFT(list, value, unique)*: Adds *value* to the list specified by *list*. If
|
|
*unique* is set to true, then *value* is not added if already present in the list.
|
|
The modified list is returned. The value is added at the start of the list (left side).
|
|
|
|
Note: non-unique elements will not be removed from the list if they were already present
|
|
before the call to `UNSHIFT`. The *unique* flag will only control if the value will
|
|
be added again to the list if already present. To make a list unique, use the `UNIQUE`
|
|
function.
|
|
|
|
/* [ 4, 1, 2, 3 ] */
|
|
UNSHIFT([ 1, 2, 3 ], 4)
|
|
|
|
/* [ 1, 2, 3 ] */
|
|
UNSHIFT([ 1, 2, 3 ], 2, true)
|
|
|
|
- *POP(list)*: Removes the element at the end (right side) of *list*. The modified list
|
|
is returned. If the list is already empty or *null*, an empty list is returned.
|
|
|
|
/* [ 1, 2, 3 ] */
|
|
POP([ 1, 2, 3, 4 ])
|
|
|
|
- *SHIFT(list)*: Removes the element at the start (left side) of *list*. The modified list
|
|
is returned. If the list is already empty or *null*, an empty list is returned.
|
|
|
|
/* [ 2, 3, 4 ] */
|
|
SHIFT([ 1, 2, 3, 4 ])
|
|
|
|
- *REMOVE_VALUE(list, value, limit)*: Removes all occurrences of *value* in the list
|
|
specified by *list*. If the optional *limit* is specified, only *limit* occurrences
|
|
will be removed.
|
|
|
|
/* [ "b", "b", "c" ] */
|
|
REMOVE_VALUE([ "a", "b", "b", "a", "c" ], "a")
|
|
|
|
/* [ "b", "b", "a", "c" ] */
|
|
REMOVE_VALUE([ "a", "b", "b", "a", "c" ], "a", 1)
|
|
|
|
- *REMOVE_VALUES(list, values)*: Removes all occurrences of any of the values specified
|
|
in list *values* from the list specified by *list*.
|
|
|
|
/* [ "b", "c", "e", "g" ] */
|
|
REMOVE_VALUES([ "a", "b", "c", "d", "e", "f", "g" ], [ "a", "f", "d" ])
|
|
|
|
- *REMOVE_NTH(list, position)*: Removes the element at position *position* from the
|
|
list specified by *list*. Positions start at 0. Negative positions are supported,
|
|
with -1 being the last list element. If *position* is out of bounds, the list is
|
|
returned unmodified. Otherwise, the modified list is returned.
|
|
|
|
/* [ "a", "c", "d", "e" ] */
|
|
REMOVE_NTH([ "a", "b", "c", "d", "e" ], 1)
|
|
|
|
/* [ "a", "b", "c", "e" ] */
|
|
REMOVE_NTH([ "a", "b", "c", "d", "e" ], -2)
|
|
|
|
Apart from these functions, AQL also offers several language constructs (e.g.
|
|
*FOR*, *SORT*, *LIMIT*, *COLLECT*) to operate on lists.
|