Array functions
Array functions
These functions can be used when working with, and manipulating arrays of data.
| Function | Description |
|---|---|
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.
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.
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.
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.
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.
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.
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", 0, 1 ]
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.
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.
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.
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.
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.
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
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. Similar to slice::chunks
array::clump(array, value) -> array
The following example shows this function, and its output, when used in a RETURN statement:
RETURN array::clump([0, 1, 2, 3], 2);
[ [0, 1], [2, 3] ]
array::difference
The array::difference determines the difference between two arrays, returning a single array containing items which are not in both arrays.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 ]