Skip to main content
Version: 2.x(alpha)

Array functions

These functions can be used when working with, and manipulating arrays of data.

FunctionDescription
array::add()Adds an item to an array if it doesn't exist
array::all()Checks whether all array values are truthy
array::any()Checks whether any array value is truthy
array::at()Returns value for X index, or in reverse for a negative index
array::append()Appends an item to the end of an array
array::boolean_and()Perform the AND bitwise operations on two arrays
array::boolean_or()Perform the OR bitwise operations on two arrays
array::boolean_xor()Perform the XOR bitwise operations on two arrays
array::boolean_not()Perform the NOT bitwise operations on an array
array::combine()Combines all values from two arrays together
array::complement()Returns the complement of two arrays
array::clump()Returns the original array split into multiple arrays of X size
array::concat()Returns the merged values from two arrays
array::difference()Returns the difference between two arrays
array::distinct()Returns the unique items in an array
array::find_index()Returns the index of the first occurrence of X value
array::filter_index()Find the indexes of all occurrences of all matching X value
array::first()Returns the first item in an array
array::flatten()Flattens multiple arrays into a single array
array::group()Flattens and returns the unique items in an array
array::insert()Inserts an item at the end of an array, or in a specific position, supports negative index
array::intersect()Returns the values which intersect two arrays
array::join()Returns concatenated value of an array with a string in between.
array::last()Returns the last item in an array
array::len()Returns the length of an array
array::logical_and()Performs the AND logical operations on two arrays
array::logical_or()Performs the OR logical operations on two arrays
array::logical_xor()Performs the XOR logical operations on two arrays
array::max()Returns the maximum item in an array
array::matches()Returns an array of booleans
array::min()Returns the minimum item in an array
array::pop()Returns the last item from an array
array::prepend()Prepends an item to the beginning of an array
array::push()Appends an item to the end of an array
array::remove()Removes an item at a specific position from an array, supports negative index
array::reverse()Reverses the sorting order of an array
array::sort()Sorts the values in an array in ascending or descending order
array::slice()Returns a slice of an array
array::sort::asc()Sorts the values in an array in ascending order
array::sort::desc()Sorts the values in an array in descending order
array::transpose()Performs 2d array transposition on two arrays
array::union()Returns the unique merged values from two arrays

array::add​

The array::add function adds an item to an array only if it doesn't exist.

API DEFINITION
array::add(array, value) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::add(["one", "two"], "three");

["one", "two", "three"]

array::all​

The array::all function checks whether all array values are truthy.

API DEFINITION
array::all(array) -> bool

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::all([ 1, 2, 3, NONE, 'SurrealDB', 5 ]);

false

array::any​

The array::any function checks whether any array values are truthy.

API DEFINITION
array::any(array) -> bool

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::any([ 1, 2, 3, NONE, 'SurrealDB', 5 ]);

true

array::at​

The array::at function returns value for X index, or in reverse for a negative index.

API DEFINITION
array::at(array, index) -> any

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::at(['s', 'u', 'r', 'r', 'e', 'a', 'l'], 2);

"r"

You can also pass a negative index. This will perform the lookup in reverse:

RETURN array::at(['s', 'u', 'r', 'r', 'e', 'a', 'l'], -3);

"e"

array::append​

The array::append function appends a value to the end of an array.

API DEFINITION
array::append(array, value) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::append([1, 2, 3, 4], 5);

[ 1, 2, 3, 4, 5 ]

array::boolean_and​

The array::boolean_and Perform the AND bitwise operations on the input arrays per-element based on the element's truthiness. If one array is shorter than the other it is considered null and thus false.

API DEFINITION
array::boolean_and(lh: Array, rh: Array)

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::boolean_and(["true", "false", 1, 1], ["true", "true", 0, "true"]);

[true, false, false, true]

For those that take two arrays, missing elements (if one array is shorter than the other) are considered null and thus false.

RETURN array::boolean_and([true, true], [false])

[ false, false ]

array::boolean_or​

The array::boolean_or Perform the OR bitwise operations on the input arrays per-element based on the element's truthiness. It takes two arrays and if one array is shorter than the other or missing, the output is considered null and thus false.

API DEFINITION
array::boolean_or(lh: Array, rh: Array)

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::boolean_or([false, true, false, true], [false, false, true, true])

[ false, true, true, true ]

array::boolean_xor​

The array::boolean_xor Performs the XOR bitwise operations.

API DEFINITION
array::boolean_xor(lh: Array, rh: Array)

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::boolean_xor([false, true, false, true], [false, false, true, true]);

[ false, true, true, false ]

array::boolean_not​

The array::boolean_not Perform the NOT bitwise operations on the input array(s) per-element based on the element's truthiness. It takes in one array and it returns false if its single operand can be converted to true.

API DEFINITION
array::boolean_not(Array)

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::boolean_not([ false, true, 0, 1 ]);

[ true, false, true, false ]

array::combine​

The array::combine function combines all values from two arrays together, returning an array of arrays.

API DEFINITION
array::combine(array, array) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::combine([1,2], [2,3]);

[ [1,2], [1,3], [2,2], [2,3] ]

array::complement​

The array::complement function returns the complement of two arrays, returning a single array containing items which are not in the second array.

API DEFINITION
array::complement(array, array) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::complement([1,2,3,4], [3,4,5,6]);

[ 1, 2 ]

array::concat​

The array::concat function merges two arrays together, returning an array which may contain duplicate values. If you want to remove duplicate values from the resulting array, then use the array::union() function

API DEFINITION
array::concat(array, array) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::concat([1,2,3,4], [3,4,5,6]);

[ 1, 2, 3, 4, 3, 4, 5, 6 ]

array::clump​

The array::clump function returns the original array split into sub-arrays of size.

API DEFINITION
array::clump(array, value) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::clump([1, 2, 3, 4, 5], 2);

[ [1, 2], [3, 4], [5] ]

array::difference​

The array::difference determines the difference between two arrays, returning a single array containing items which are not in both arrays.

API DEFINITION
array::difference(array, array) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::difference([1,2,3,4], [3,4,5,6]);

[ 1, 2, 5, 6 ]

array::distinct​

The array::distinct function calculates the unique values in an array, returning a single array.

API DEFINITION
array::distinct(array) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::distinct([ 1, 2, 1, 3, 3, 4 ]);

[ 1, 2, 3, 4 ]

array::flatten​

The array::flatten flattens an array of arrays, returning a new array with all sub-array elements concatenated into it.

API DEFINITION
array::flatten(array, index) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::flatten([ [1,2], [3, 4], 'SurrealDB', [5, 6, [7, 8]] ]);

[ 1, 2, 3, 4, 'SurrealDB', 5, 6, [7, 8] ]

array::find_index​

The array::find_index Returns the index of the first occurrence of value in the array or null if array does not contain value.

API DEFINITION
array::find_index(array, index) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::find_index(['a', 'b', 'c', 'b', 'a'], 'b');

1

array::filter_index​

The array::filter_index finds the indexes of all occurrences of all matching values.

API DEFINITION
array::filter_index(array, index) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::filter_index(['a', 'b', 'c', 'b', 'a'], 'b');

[ 1, 3 ]

array::first​

The array::first function returns the first value from an array.

API DEFINITION
array::first(array) -> any

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::first([ 's', 'u', 'r', 'r', 'e', 'a', 'l' ]);

"s"

array::group​

The array::group function flattens and returns the unique items in an array.

API DEFINITION
array::group(array) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::group([1, 2, 3, 4, [3,5,6], [2,4,5,6], 7, 8, 8, 9]);

[ 1, 2, 3, 4, 5, 6, 7, 8, 9 ]

array::insert​

The array::insert function inserts a value into an array at a specific position, supports negative index.

API DEFINITION
array::insert(array, value, number) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::insert([1,2,3,4], 5, 2);

[ 1, 2, 5, 3, 4 ]

array::intersect​

The array::intersect function calculates the values which intersect two arrays, returning a single array containing the values which are in both arrays.

API DEFINITION
array::intersect(array, array) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::intersect([1,2,3,4], [3,4,5,6]);

[ 3, 4 ]

array::join​

The array::join function takes an array and a string as parameters and returns a concatenated string.

API DEFINITION
array::join(array, string) -> string

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::join(["again", "again", "again"], " and ");

"again and again and again"

array::last​

The array::lastfunction returns the last value from an array.

API DEFINITION
array::last(array) -> any

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::last([ 's', 'u', 'r', 'r', 'e', 'a', 'l' ]);

"l"

array::len​

The array::len function calculates the length of an array, returning a number. This function includes all items when counting the number of items in the array. If you want to only count truthy values, then use the count() function.

API DEFINITION
array::len(array) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::len([ 1, 2, 1, null, "something", 3, 3, 4, 0 ]);

9

array::logical_and​

The array::logical_and performs the AND logical operations local but they return the element that represents the resulting truthiness similar to the above. Note that the functions prioritize the elements on the left hand. Also, in the event that neither element can represent the truthiness of the output, the resulting element is a boolean value of the truthiness.

API DEFINITION
array::logical_and(lh: Array, rh: Array)

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::logical_and([true, false, true, false], [true, true, false, false]);

[ true, false, false, false ]

For those that take two arrays, missing elements (if one array is shorter than the other) are considered null and thus false

RETURN array::logical_and([0, 1], [])

[ 0, null ]

array::logical_or​

The array::logical_or Performs the OR logical operations. Note that the functions prioritize the elements on the left hand.

API DEFINITION
array::logical_or(lh: Array, rh: Array)

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::logical_or([true, false, true, false], [true, true, false, false]);

[ true, true, true, false ]

If one of the array is empty, the first array is returned.

RETURN array::logical_or([0, 1], []);

[ 0, 1 ]

array::logical_xor​

The array::logical_or performs the XOR logical operations.

API DEFINITION
array::logical_xor(lh: Array, rh: Array)

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::logical_xor([true, false, true, false], [true, true, false, false]);

[ false, true, true, false ]

If one of the array is empty, the first array is returned.

RETURN array::logical_xor([0, 1], [])

[ 0, 1 ]

array::max​

The array::max returns the maximum item in an array

API DEFINITION
array::max(Array) -> any

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::max([0, 1, 2]);

2

array::matches​

The array::matches returns an array of booleans

API DEFINITION
array::matches(Array,value) -> Array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::matches([0, 1, 2], 1);

[false, true, false]

The following example shows this function when the array contains objects.

RETURN array::matches([{id: "ohno:0"}, {id: "ohno:1"}], {id: "ohno:1"})

[ false, true ]

array::min​

The array::min returns the minimum item in an array

API DEFINITION
array::min(Array) -> any

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::min([0, 1, 2]);

0

array::pop​

The array::pop function removes a value from the end of an array and returns it.

API DEFINITION
array::pop(array) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::pop([ 1, 2, 3, 4 ]);

4

array::prepend​

The array::prepend function prepends a value to the beginning of an array.

API DEFINITION
array::prepend(array, value) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::prepend([1,2,3,4], 5);

[ 5, 1, 2, 3, 4 ]

array::push​

The array::push function prepends a value to the end of an array.

API DEFINITION
array::push(array, value) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::push([1,2,3,4], 5);

[ 1, 2, 3, 4, 5 ]

array::remove​

The array::remove function removes an item from a specific position in an array, supports negative index.

API DEFINITION
array::remove(array, number) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::remove([1,2,3,4,5], 2);

[ 1, 2, 4, 5 ]

The following examples shows this function using a negative index.

RETURN array::remove([1,2,3,4,5], -2);

[ 1, 2, 3, 5 ]

array::reverse​

The array::reverse function reverses the sorting order of an array.

API DEFINITION
array::reverse(array) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::reverse([ 1, 2, 3, 4, 5 ]);

[ 5, 4, 3, 2, 1 ]

array::sort​

The array::sort function sorts the values in an array in ascending or descending order.

API DEFINITION
array::sort(array) -> array

The function also accepts a second boolean parameter which determines the sorting direction. The second parameter can be true for ascending order, or false for descending order.

API DEFINITION
array::sort(array, bool) -> array

The function also accepts a second string parameter which determines the sorting direction. The second parameter can be 'asc' for ascending order, or 'desc' for descending order.

API DEFINITION
array::sort(array, string) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::sort([ 1, 2, 1, null, "something", 3, 3, 4, 0 ]);

[ null, 0, 1, 1, 2, 3, 3, 4, "something" ]
RETURN array::sort([1,2,1,null,"something",3,3,4,0], false);

[ "something", 4, 3, 3, 2, 1, 1, 9, null ]
RETURN array::sort([1,2,1,null,"something",3,3,4,0], "asc");

[ null, 0, 1, 1, 2, 3, 3, 4, "something" ]
RETURN array::sort([1,2,1,null,"something",3,3,4,0], "desc");

[ "something", 4, 3, 3, 2, 1, 1, 9, null ]

array::slice​

The array::slice returns a slice of an array, based on a starting position, and a length or negative position.

API DEFINITION
array::slice(array, start, len) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::slice([ 1, 2, 3, 4, 5 ], 1, 2);

[2,3]

The following example shows how you can use this function with a starting position, and a negative position, which will slice off the first and last element from the array:

RETURN array::slice([ 1, 2, 3, 4, 5 ], 1, -1);

[ 2, 3, 4 ]

The following example shows how you can use this function with just a starting position, which will only slice from the beginning of the array:

RETURN array::slice([ 1, 2, 3, 4, 5 ], 2);

[ 3, 4, 5 ]

The following example shows how you can use this function with just a negative position, which will only slice from the end of the array:

RETURN array::slice([ 1, 2, 3, 4, 5 ], -2);

[ 4, 5 ]

The following example shows how you can use this function with a negative position, and a length of the slice:

RETURN array::slice([ 1, 2, 3, 4, 5 ], -3, 2);

[ 3, 4 ]

array::sort::asc​

The array::sort::asc function is a shorthand convenience function for the array::sort function, to sort values in an array in ascending order.

API DEFINITION
array::sort::asc(array) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::sort::asc([ 1, 2, 1, null, "something", 3, 3, 4, 0 ]);

[ null, 0, 1, 1, 2, 3, 3, 4, "something" ]

array::sort::desc​

The array::sort::desc function is a shorthand convenience function for the array::sort function, to sort values in an array in descending order.

API DEFINITION
array::sort::desc(array) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::sort::desc([ 1, 2, 1, null, "something", 3, 3, 4, 0 ]);

[ "something", 4, 3, 3, 2, 1, 1, 9, null ]

array::transpose​

The array::transpose is used to perform 2d array transposition but it's behavior in cases of arrays of differing sizes can be best described as taking in multiple arrays and 'layering' them on top of each other.

API DEFINITION
array::transpose(array, array) -> array array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::transpose([[0, 1], [2, 3]]);

[ [0, 2], [1, 3] ]

array::union​

The array::union function combines two arrays together, removing duplicate values, and returning a single array.

API DEFINITION
array::union(array, array) -> array

The following example shows this function, and its output, when used in a RETURN statement:

RETURN array::union([1,2,1,6], [1,3,4,5,6]);

[ 1, 2, 6, 3, 4, 5 ]


What's on your mind?

Create GitHub Issue

Quickest way to alert
our team of a problem.