This helper wraps the ArangoDB AQL function APPEND(anyArray, values, unique) to concatenate arrays. All values from the second argument are appended to the end of the first array. If unique is set to true, only values that are not already present in the target array are appended.

Example AQL usage:

APPEND(doc.tags, ["new", "tags"])      // appends values to doc.tags
APPEND(doc.tags, other.tags, true)       // appends only values not present yet

Unlike arrayFilter() ([* FILTER cond], which returns the matching sub-array), the question-mark operator returns a boolean: whether the array contains elements satisfying $condition under the given quantifier. It is the direct, idiomatic way to write the existential LENGTH(array[* FILTER cond]) > 0 and, with a quantifier, the ALL / NONE / AT LEAST (n) variants.

Supported quantifiers (omitted = "at least one"):

• '' → at least one element matches (default);
• ANY / ALL / NONE;
• AT LEAST (n) → at least n elements match.

$condition is interpolated verbatim — callers build it from trusted/whitelisted pieces (bound values, validated fields, …).

This is AQL's array expansion in its filtering form: it keeps the elements of $array for which $condition (which typically references the loop variable Clause::CURRENT) holds, yielding a sub-array. It is the filtering sibling of arrayMap() ([* RETURN expr]).

Combined with length() it expresses an existential test — LENGTH(doc.items[* FILTER CURRENT.active]) > 0 — though the boolean array "question mark" operator ([? FILTER …], see arrayContains()) is a more direct way to write the same intent.

$condition is interpolated verbatim — callers are responsible for building it from trusted/whitelisted pieces (bound values, validated fields, …).

This is AQL's array expansion in its projecting form: it maps each element of $array to $expression (which typically references the loop variable Clause::CURRENT), yielding a new array. It is the read-only sibling of arrayFilter() ([* FILTER cond]).

$expression is interpolated verbatim — callers are responsible for building it from trusted/whitelisted pieces (e.g. CURRENT, an alterExpression() chain, or a validated sub-field). pluck() is the safe specialization for a single sub-field (it validates the field name first).

This helper wraps the ArangoDB AQL function COUNT(expression) which is an alias for LENGTH(expression). It returns the number of elements in the given array expression.

Example AQL usage:

COUNT(doc.tags)              // returns number of elements in doc.tags
COUNT([1, 2, 3, 4])         // returns 4

This helper wraps the ArangoDB AQL function COUNT_DISTINCT(anyArray) which returns the number of unique elements in the given array, removing duplicates before counting.

Example AQL usage:

COUNT_DISTINCT([1, 2, 3, 2, 1])     // returns 3 (unique elements: 1, 2, 3)
COUNT_DISTINCT(doc.tags)            // returns number of unique tags

This helper wraps the ArangoDB AQL function FIRST(anyArray) which returns the first element of the given array. If the array is empty, it returns null.

Example AQL usage:

FIRST([1, 2, 3])            // returns 1
FIRST(doc.items)            // returns first item from doc.items
FIRST([])                   // returns null

This helper wraps the ArangoDB AQL function LAST(anyArray) which returns the last element of the given array. If the array is empty, it returns null.

Example AQL usage:

LAST([1, 2, 3])             // returns 3
LAST(doc.items)             // returns last item from doc.items
LAST([])                    // returns null

This helper wraps the ArangoDB AQL function LENGTH(expression) which returns the number of elements in arrays, the number of attributes in objects, or the number of documents in collections.

Example AQL usage:

LENGTH([1, 2, 3, 4])        // returns 4
LENGTH(doc.items)           // returns number of items
LENGTH({a: 1, b: 2})       // returns 2 (object attributes)
LENGTH(collection)          // returns number of documents

This helper wraps the ArangoDB AQL function NTH(anyArray, position) which returns the element at the specified zero-based position in the array. If the position is out of bounds, it returns null.

Note: Negative positions are not supported in ArangoDB AQL.

Example AQL usage:

NTH([2, 4, 6, 8], 0)        // returns 2 (first element)
NTH([2, 4, 6, 8], 2)        // returns 6 (third element)
NTH([2, 4, 6, 8], 10)       // returns null (out of bounds)

Builds the AQL inline projection array[* RETURN CURRENT.<field>], which maps an array of objects to an array holding only the requested sub-field of each element. Combined with an aggregate (AVERAGE, SUM, MAX, …) it lets a filter reduce over a property of embedded objects:

AVERAGE(doc.items[* RETURN CURRENT.price])   // average price across doc.items

The [* RETURN expr] form is AQL's array inline projection (the read-only sibling of the array filter [* FILTER cond]). Because $field is typically user-supplied (it comes from the alt chain), it is validated with assertAttributeName() before being interpolated, guarding against AQL injection.

This helper wraps the ArangoDB AQL function POP(anyArray) which removes and returns the last element of an array, modifying the original array.

If it’s already empty or has only a single element left, an empty array is returned.

Example AQL usage:

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

This helper wraps the ArangoDB AQL function POSITION(anyArray, search, returnIndex) which searches for a value in an array and returns either its position or a boolean indicating whether the value was found.

Example AQL usage:

POSITION([2, 4, 6, 8], 4)           // returns 1 (position of 4)
POSITION([2, 4, 6, 8], 4, true)     // returns 1 (same as above)
POSITION([2, 4, 6, 8], 5, false)    // returns false (not found)
POSITION([2, 4, 6, 8], 5)           // returns false (default behavior)

This helper wraps the ArangoDB AQL function PUSH(anyArray, value, unique) which adds a value to the end of an array. If unique is true, the value is only added if it's not already present in the array.

Example AQL usage:

PUSH([2, 4, 6], 8)          // returns [2, 4, 6, 8]
PUSH([2, 4, 6], 4)          // returns [2, 4, 6, 4]
PUSH([2, 4, 6], 4, true)    // returns [2, 4, 6] (4 already exists)
PUSH([2, 4, 6], 8, true)    // returns [2, 4, 6, 8] (8 is new)

This helper wraps the ArangoDB AQL function REMOVE_VALUE(anyArray, value, limit) which removes all occurrences of a specified value from an array. An optional limit can be specified to limit the number of removals.

Example AQL usage:

REMOVE_VALUE([1, 2, 3, 2, 4], 2)        // returns [1, 3, 4]
REMOVE_VALUE([1, 2, 3, 2, 4], 2, 1)     // returns [1, 3, 2, 4] (only first occurrence)
REMOVE_VALUE([1, 2, 3], 5)               // returns [1, 2, 3] (value not found)

This helper wraps the ArangoDB AQL function REMOVE_VALUES(anyArray, values) which removes all occurrences of multiple specified values from an array. The values parameter should be an array expression containing the values to remove.

Example AQL usage:

REMOVE_VALUES([1, 2, 3, 2, 4, 3], [2, 3])    // returns [1, 4]
REMOVE_VALUES(doc.tags, ["old", "deprecated"]) // removes multiple tags

This helper wraps the ArangoDB AQL function REVERSE(expression) which can reverse both arrays and strings. For arrays, it reverses the order of elements. For strings, it reverses the order of characters.

Example AQL usage:

REVERSE([1, 2, 3])          // returns [3, 2, 1]
REVERSE("hello")            // returns "olleh"
REVERSE(doc.items)          // reverses the order of items

This helper wraps the ArangoDB AQL function SHIFT(anyArray) which removes and returns the first element of an array, modifying the original array. If the array is empty, it returns null.

Example AQL usage:

SHIFT([1, 2, 3])            // returns 1, array becomes [2, 3]
SHIFT(doc.items)            // removes first item from doc.items
SHIFT([])                   // returns null

This helper wraps the ArangoDB AQL function SLICE(anyArray, start, length) which extracts a portion of an array starting from the specified index. The length parameter is optional - if not provided, all elements from the start position to the end are included.

Example AQL usage:

SLICE([1, 2, 3, 4, 5], 1, 2)       // returns [2, 3]
SLICE([1, 2, 3, 4, 5], 2)          // returns [3, 4, 5]
SLICE([1, 2, 3, 4, 5], 0, 3)       // returns [1, 2, 3]

This helper wraps the ArangoDB AQL function SORTED(anyArray) which returns a new array with all elements sorted in ascending order. The original array is not modified. Elements are sorted using ArangoDB's default comparison rules.

Example AQL usage:

SORTED([4, 1, 8, 2, 3])            // returns [1, 2, 3, 4, 8]
SORTED(["c", "a", "b"])            // returns ["a", "b", "c"]
SORTED(doc.numbers)                // sorts the numbers array

This helper wraps the ArangoDB AQL function SORTED_UNIQUE(anyArray) which returns a new array with all elements sorted in ascending order and duplicates removed. The original array is not modified.

Example AQL usage:

SORTED_UNIQUE([8, 4, 2, 10, 6, 2, 8, 6, 4])    // returns [2, 4, 6, 8, 10]
SORTED_UNIQUE(["c", "a", "b", "a", "c"])        // returns ["a", "b", "c"]
SORTED_UNIQUE(doc.tags)                         // sorts and deduplicates tags

Example AQL usage:

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

This helper wraps the ArangoDB AQL function UNSHIFT(anyArray, value, unique) which adds a value to the beginning of an array. If unique is true, the value is only added if it's not already present in the array.

Example AQL usage:

UNSHIFT([2, 4, 6], 1)           // returns [1, 2, 4, 6]
UNSHIFT([2, 4, 6], 4)           // returns [4, 2, 4, 6]
UNSHIFT([2, 4, 6], 4, true)     // returns [2, 4, 6] (4 already exists)
UNSHIFT([2, 4, 6], 1, true)     // returns [1, 2, 4, 6] (1 is new)