Array functions

AQL provides functions for higher-level array manipulation. Also see the numeric functions for functions that work on number arrays. If you want to concatenate the elements of an array equivalent to join() in JavaScript, see CONCAT() and CONCAT_SEPARATOR() in the string functions chapter.

Apart from that, AQL also offers several language constructs:

  • simple array access of individual elements,
  • array operators for array expansion and contraction, optionally with inline filter, limit and projection,
  • array comparison operators to compare each element in an array to a value or the elements of another array,
  • loop-based operations using FOR, SORT, LIMIT, as well as COLLECT for grouping, which also offers efficient aggregation.

APPEND()

APPEND(anyArray, values, unique) → newArray

Add all elements of an array to another array. All values are added at the end of the array (right side).

  • anyArray (array): array with elements of arbitrary type
  • values (array): array, whose elements shall be added to anyArray
  • unique (bool, optional): if set to true, only those values will be added that are not already contained in anyArray. The default is false.
  • returns newArray (array): the modified array

Examples

Query:
RETURN APPEND([ 1, 2, 3 ], [ 5, 6, 9 ])

Show query result
Query:
RETURN APPEND([ 1, 2, 3 ], [ 3, 4, 5, 2, 9 ], true)

Show query result

CONTAINS_ARRAY()

This is an alias for POSITION().

COUNT()

This is an alias for LENGTH().

COUNT_DISTINCT()

COUNT_DISTINCT(anyArray) → number

Get the number of distinct elements in an array.

  • anyArray (array): array with elements of arbitrary type
  • returns number: the number of distinct elements in anyArray.

Examples

Query:
RETURN COUNT_DISTINCT([ 1, 2, 3 ])

Query results:
[
  3
]
Query:
RETURN COUNT_DISTINCT([ "yes", "no", "yes", "sauron", "no", "yes" ])

Query results:
[
  3
]

COUNT_UNIQUE()

This is an alias for COUNT_DISTINCT().

FIRST()

FIRST(anyArray) → firstElement

Get the first element of an array. It is the same as anyArray[0].

  • anyArray (array): array with elements of arbitrary type
  • returns firstElement (any|null): the first element of anyArray, or null if the array is empty.

Examples

Query:
RETURN FIRST([ 1, 2, 3 ])

Query results:
[
  1
]
Query:
RETURN FIRST([])

Query results:
[
  null
]

FLATTEN()

FLATTEN(anyArray, depth) → flatArray

Turn an array of arrays into a flat array. All array elements in array will be expanded in the result array. Non-array elements are added as they are. The function will recurse into sub-arrays up to the specified depth. Duplicates will not be removed.

  • array (array): array with elements of arbitrary type, including nested arrays
  • depth (number, optional): flatten up to this many levels, the default is 1
  • returns flatArray (array): a flattened array

Examples

Query:
RETURN FLATTEN( [ 1, 2, [ 3, 4 ], 5, [ 6, 7 ], [ 8, [ 9, 10 ] ] ] )

Show query result

To fully flatten the example array, use a depth of 2:

Query:
RETURN FLATTEN( [ 1, 2, [ 3, 4 ], 5, [ 6, 7 ], [ 8, [ 9, 10 ] ] ], 2 )

Show query result

INTERSECTION()

INTERSECTION(array1, array2, ... arrayN) → newArray

Return the intersection of all arrays specified. The result is an array of values that occur in all arguments.

  • arrays (array, repeatable): an arbitrary number of arrays as multiple arguments (at least 2)
  • returns newArray (array): a single array with only the elements, which exist in all provided arrays. The element order is random. Duplicates are removed.

Examples

Query:
RETURN INTERSECTION( [1,2,3,4,5], [2,3,4,5,6], [3,4,5,6,7] )

Show query result
Query:
RETURN INTERSECTION( [2,4,6], [8,10,12], [14,16,18] )

Query results:
[
  []
]

LAST()

LAST(anyArray) → lastElement

Get the last element of an array. It is the same as anyArray[-1].

  • anyArray (array): array with elements of arbitrary type
  • returns lastElement (any|null): the last element of anyArray or null if the array is empty.

Example

Query:
RETURN LAST( [1,2,3,4,5] )

Query results:
[
  5
]

LENGTH()

LENGTH(anyArray) → length

Determine the number of elements in an array.

  • anyArray (array): array with elements of arbitrary type
  • returns length (number): the number of array elements in anyArray.

LENGTH() can also determine the number of attribute keys of an object / document, the amount of documents in a collection and the character length of a string.

input length
String number of unicode characters
Number number of unicode characters that represent the number
Array number of elements
Object number of first level elements
true 1
false 0
null 0

Examples

Query:
RETURN LENGTH( "🥑" )

Query results:
[
  1
]
Query:
RETURN LENGTH( 1234 )

Query results:
[
  4
]
Query:
RETURN LENGTH( [1,2,3,4,5,6,7] )

Query results:
[
  7
]
Query:
RETURN LENGTH( [1,2,3,4,5,6,7] )

Query results:
[
  7
]
Query:
RETURN LENGTH( {a:1, b:2, c:3, d:4, e:{f:5,g:6}} )

Query results:
[
  5
]

MINUS()

MINUS(array1, array2, ... arrayN) → newArray

Return the difference of all arrays specified.

  • arrays (array, repeatable): an arbitrary number of arrays as multiple arguments (at least 2)
  • returns newArray (array): an array of values that occur in the first array, but not in any of the subsequent arrays. The order of the result array is undefined and should not be relied on. Duplicates will be removed.

Example

Query:
RETURN MINUS( [1,2,3,4], [3,4,5,6], [5,6,7,8] )

Show query result

NTH()

NTH(anyArray, position) → nthElement

Get the element of an array at a given position. It is the same as anyArray[position] for positive positions, but does not support negative positions.

  • anyArray (array): array with elements of arbitrary type
  • position (number): position of desired element in array, positions start at 0
  • returns nthElement (any|null): the array element at the given position. If position is negative or beyond the upper bound of the array, then null will be returned.

Examples

Query:
RETURN NTH( [ "foo", "bar", "baz" ], 2 )

Query results:
[
  "baz"
]
Query:
RETURN NTH( [ "foo", "bar", "baz" ], 3 )

Query results:
[
  null
]
Query:
RETURN NTH( [ "foo", "bar", "baz" ], -1 )

Query results:
[
  null
]

OUTERSECTION()

OUTERSECTION(array1, array2, ... arrayN) → newArray

Return the values that occur only once across all arrays specified.

  • arrays (array, repeatable): an arbitrary number of arrays as multiple arguments (at least 2)
  • returns newArray (array): a single array with only the elements that exist only once across all provided arrays. The element order is random.

Example

Query:
RETURN OUTERSECTION( [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4, 5 ] )

Show query result

POP()

POP(anyArray) → newArray

Remove the element at the end (right side) of array.

  • anyArray (array): an array with elements of arbitrary type
  • returns newArray (array): anyArray without the last element. If it's already empty or has only a single element left, an empty array is returned.

Examples

Query:
RETURN POP( [ 1, 2, 3, 4 ] )

Show query result
Query:
RETURN POP( [ 1 ] )

Query results:
[
  []
]

POSITION()

POSITION(anyArray, search, returnIndex) → position

Return whether search is contained in array. Optionally return the position.

  • anyArray (array): the haystack, an array with elements of arbitrary type
  • search (any): the needle, an element of arbitrary type
  • returnIndex (bool, optional): if set to true, the position of the match is returned instead of a boolean. The default is false.
  • returns position (bool|number): true if search is contained in anyArray, false otherwise. If returnIndex is enabled, the position of the match is returned (positions start at 0), or -1 if it's not found.

To determine if or at which position a string occurs in another string, see the CONTAINS() string function.

Examples

Query:
RETURN POSITION( [2,4,6,8], 4 )

Query results:
[
  true
]
Query:
RETURN POSITION( [2,4,6,8], 4, true )

Query results:
[
  1
]

PUSH()

PUSH(anyArray, value, unique) → newArray

Append value to the array specified by anyArray.

  • anyArray (array): array with elements of arbitrary type
  • value (any): an element of arbitrary type
  • unique (bool): if set to true, then value is not added if already present in the array. The default is false.
  • returns newArray (array): anyArray with value added at the end (right side)

Note: The unique flag only controls if value is added if it's already present in anyArray. Duplicate elements that already exist in anyArray will not be removed. To make an array unique, use the UNIQUE() function.

Examples

Query:
RETURN PUSH([ 1, 2, 3 ], 4)

Show query result
Query:
RETURN PUSH([ 1, 2, 2, 3 ], 2, true)

Show query result

REMOVE_NTH()

REMOVE_NTH(anyArray, position) → newArray

Remove the element at position from the anyArray.

  • anyArray (array): array with elements of arbitrary type
  • position (number): the position of the element to remove. Positions start at 0. Negative positions are supported, with -1 being the last array element. If position is out of bounds, the array is returned unmodified.
  • returns newArray (array): anyArray without the element at position

Examples

Query:
RETURN REMOVE_NTH( [ "a", "b", "c", "d", "e" ], 1 )

Show query result
Query:
RETURN REMOVE_NTH( [ "a", "b", "c", "d", "e" ], -2 )

Show query result

REMOVE_VALUE()

REMOVE_VALUE(anyArray, value, limit) → newArray

Remove all occurrences of value in anyArray. Optionally with a limit to the number of removals.

  • anyArray (array): array with elements of arbitrary type
  • value (any): an element of arbitrary type
  • limit (number, optional): cap the number of removals to this value
  • returns newArray (array): anyArray with value removed

Examples

Query:
RETURN REMOVE_VALUE( [ "a", "b", "b", "a", "c" ], "a" )

Show query result
Query:
RETURN REMOVE_VALUE( [ "a", "b", "b", "a", "c" ], "a", 1 )

Show query result

REMOVE_VALUES()

REMOVE_VALUES(anyArray, values) → newArray

Remove all occurrences of any of the values from anyArray.

  • anyArray (array): array with elements of arbitrary type
  • values (array): an array with elements of arbitrary type, that shall be removed from anyArray
  • returns newArray (array): anyArray with all individual values removed

Example

Query:
RETURN REMOVE_VALUES( [ "a", "a", "b", "c", "d", "e", "f" ], [ "a", "f", "d" ] )

Show query result

REVERSE()

REVERSE(anyArray) → reversedArray

Return an array with its elements reversed.

  • anyArray (array): array with elements of arbitrary type
  • returns reversedArray (array): a new array with all elements of anyArray in reversed order

Example

Query:
RETURN REVERSE ( [2,4,6,8,10] )

Show query result

SHIFT()

SHIFT(anyArray) → newArray

Remove the element at the start (left side) of anyArray.

  • anyArray (array): array with elements with arbitrary type
  • returns newArray (array): anyArray without the left-most element. If anyArray is already empty or has only one element left, an empty array is returned.

Examples

Query:
RETURN SHIFT( [ 1, 2, 3, 4 ] )

Show query result
Query:
RETURN SHIFT( [ 1 ] )

Query results:
[
  []
]

SLICE()

SLICE(anyArray, start, length) → newArray

Extract a slice of anyArray.

  • anyArray (array): array with elements of arbitrary type
  • start (number): start extraction at this element. Positions start at 0. Negative values indicate positions from the end of the array.
  • length (number, optional): extract up to length elements, or all elements from start up to length if negative (exclusive)
  • returns newArray (array): the specified slice of anyArray. If length is not specified, all array elements starting at start will be returned.

Examples

Query:
RETURN SLICE( [ 1, 2, 3, 4, 5 ], 0, 1 )

Show query result
Query:
RETURN SLICE( [ 1, 2, 3, 4, 5 ], 1, 2 )

Show query result
Query:
RETURN SLICE( [ 1, 2, 3, 4, 5 ], 3 )

Show query result
Query:
RETURN SLICE( [ 1, 2, 3, 4, 5 ], 1, -1 )

Show query result
Query:
RETURN SLICE( [ 1, 2, 3, 4, 5 ], 0, -2 )

Show query result
Query:
RETURN SLICE( [ 1, 2, 3, 4, 5 ], -3, 2 )

Show query result

SORTED()

SORTED(anyArray) → newArray

Sort all elements in anyArray. The function will use the default comparison order for AQL value types.

  • anyArray (array): array with elements of arbitrary type
  • returns newArray (array): anyArray, with elements sorted

Example

Query:
RETURN SORTED( [ 8,4,2,10,6 ] )

Show query result

SORTED_UNIQUE()

SORTED_UNIQUE(anyArray) → newArray

Sort all elements in anyArray. The function will use the default comparison order for AQL value types. Additionally, the values in the result array will be made unique.

  • anyArray (array): array with elements of arbitrary type
  • returns newArray (array): anyArray, with elements sorted and duplicates removed

Example

Query:
RETURN SORTED_UNIQUE( [ 8,4,2,10,6,2,8,6,4 ] )

Show query result

UNION()

UNION(array1, array2, ... arrayN) → newArray

Return the union of all arrays specified.

  • arrays (array, repeatable): an arbitrary number of arrays as multiple arguments (at least 2)
  • returns newArray (array): all array elements combined in a single array, in any order

Examples

Query:
RETURN UNION(
  [ 1, 2, 3 ],
  [ 1, 2 ]
)

Show query result

Note: No duplicates will be removed. In order to remove duplicates, please use either UNION_DISTINCT() or apply UNIQUE() on the result of UNION():

Query:
RETURN UNIQUE(
  UNION(
      [ 1, 2, 3 ],
      [ 1, 2 ]
  )
)

Show query result

UNION_DISTINCT()

UNION_DISTINCT(array1, array2, ... arrayN) → newArray

Return the union of distinct values of all arrays specified.

  • arrays (array, repeatable): an arbitrary number of arrays as multiple arguments (at least 2)
  • returns newArray (array): the elements of all given arrays in a single array, without duplicates, in any order

Example

Query:
RETURN UNION_DISTINCT(
  [ 1, 2, 3 ],
  [ 1, 2 ]
)

Show query result

UNIQUE()

UNIQUE(anyArray) → newArray

Return all unique elements in anyArray. To determine uniqueness, the function will use the comparison order.

  • anyArray (array): array with elements of arbitrary type
  • returns newArray (array): anyArray without duplicates, in any order

Example

Query:
RETURN UNIQUE( [ 1,2,2,3,3,3,4,4,4,4,5,5,5,5,5 ] )

Show query result

UNSHIFT()

UNSHIFT(anyArray, value, unique) → newArray

Prepend value to anyArray.

  • anyArray (array): array with elements of arbitrary type
  • value (any): an element of arbitrary type
  • unique (bool): if set to true, then value is not added if already present in the array. The default is false.
  • returns newArray (array): anyArray with value added at the start (left side)

Note: The unique flag only controls if value is added if it's already present in anyArray. Duplicate elements that already exist in anyArray will not be removed. To make an array unique, use the UNIQUE() function.

Examples

Query:
RETURN UNSHIFT( [ 1, 2, 3 ], 4 )

Show query result
Query:
RETURN UNSHIFT( [ 1, 2, 3 ], 2, true )

Show query result