SurrealDB Docs Logo

Enter a search query

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, or equal to a condition
array::any()Checks whether any array value is truthy, or equal to a condition
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::fill()Fills an existing array of the same value
array::filter()Filters out values that do not match a pattern
array::filter_index()Returns the indexes of all occurrences of all matching X value
array::find()Returns the first matching value
array::find_index()Returns the index of the first occurrence of 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
array::intersect()Returns the values which intersect two arrays
array::is_empty()Checks if an array is empty
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::map()Applies an operation to every item in an array and passes it on
array::max()Returns the maximum item in an array
array::matches()Returns an array of booleans indicating which elements of the input array contain a specified value.
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::range()Creates a number array from a range (start to end)
array::remove()Removes an item at a specific position from an array
array::repeat()Creates an array a given size with a specified value used for each element.
array::reverse()Reverses the sorting order of an array
array::shuffle()Randomly shuffles the contents of an array
array::slice()Returns a slice of an array
array::sort()Sorts the values in an array in ascending or descending order
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::swap()Swaps two items in an array
array::transpose()Performs 2d array transposition on two arrays
array::union()Returns the unique merged values from two arrays
array::windows()Returns a number of arrays of length size created by moving one index at a time down the original array

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

When called on an array without any extra arguments, the array::all function checks whether all array values are truthy.

API DEFINITION
array::all(array) -> bool array::all(array, value) -> bool array::all(array, @closure) -> 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 RETURN ["all", "clear"].all(); -- true

The array::all function can also be followed with a value or a closure to check if all elements conform to a condition.

RETURN ["same", "same", "same"].all("same"); -- true [ "What's", "it", "got", "in", "its", "pocketses??" ].all(|$s| $s.len() > 1); -- true [1, 2, "SurrealDB"].all(|$var| $var.is_string()); -- false

The array::all function can also be called using its alias array::every.

[1, 2, 3].every(|$num| $num > 0);
-- true

array::any

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

API DEFINITION
array::any(array) -> bool array::any(array, value) -> bool array::any(array, @closure) -> bool

When called on an array without any extra arguments, the array::any function checks whether any array values are truthy.

RETURN array::any([ 1, 2, 3, NONE, 'SurrealDB', 5 ]); -- true ["", 0, NONE, NULL, [], {}].any(); -- false

The array::any function can also be followed with a value or a closure to check if any elements conform to a condition.

RETURN ["same", "same?", "Dude, same!"].any("same"); -- true [ "What's", "it", "got", "in", "its", "pocketses??" ].any(|$s| $s.len() > 15); -- false [1, 2, "SurrealDB"].any(|$var| $var.is_string()); -- true

The array::any function can also be called using the aliases array::some and array::includes.

[1, 2, 3].some(|$num| $num > 2); -- true [1999, 2001, 2002].includes(2000); -- false

array::at

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

API DEFINITION
array::at(array, index: int) -> 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 function performs 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, true, 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 function performs 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 function 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 function performs 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. The last sub-array may have a length less than the length of size if size does not divide equally into the original array.

API DEFINITION
array::clump(array, size: int) -> array

The following examples show this function, and its output, when used in a RETURN statement:

LET $array = [1, 2, 3, 4]; RETURN array::clump($array, 2); RETURN array::clump($array, 3);
Response
[ [ 1, 2], [3, 4] ] [ [1, 2, 3], [4] ]

array::difference

The array::difference function 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::fill

Available since: v2.0.0

The array::fill function replaces all values of an array with a new value.

API DEFINITION
array::fill(array, any) -> array

The function also accepts a third and a fourth parameter which allows you to replace only a portion of the source array.

API DEFINITION
array::fill(array, any, start: int, end: int) -> array

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

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

The following example shows how you can use this function with a starting position, and an ending position, which in this example will replace one item from the array:

RETURN array::fill([ 1, NONE, 3, 4, 5 ], 10, 1, 2); [ 1, 10, 3, 4, 5 ]

The following example shows how you can use this function with starting and ending negative positions, which in this example will replace one item from the array:

RETURN array::fill([ 1, 2, NONE, 4, 5 ], 10, -3, -2); [ 1, 2, 10, 4, 5 ]

array::filter

The array::filter function filters out values in an array that do not match a pattern, returning only the ones that do match.

API DEFINITION
array::filter(array, value) -> array array::filter(array, @closure) -> array

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

RETURN array::filter([ 1, 2, 1, 3, 3, 4 ], 1); -- [ 1, 1 ] RETURN [true, false, false, false, true, true].filter(true); -- [ true, true, true ]

The array::filter function can also take a closure for more customized filtering.

[ { importance: 10, message: "I need some help with this query..." }, { importance: 0, message: "TEST Is this thing on?" }, { importance: 5, message: "I have an idea. What if we..."}, { importance: 100, message: "Stuck on an island with two hours of battery life left. Can you..."} ].filter(|$v| $v.importance > 5);
Response
[ { importance: 10, message: 'I need some help with this query...' }, { importance: 100, message: 'Stuck on an island with two hours of battery life left. Can you...' } ]

array::filter_index

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

API DEFINITION
array::filter_index(array, value) -> array array::filter_index(array, @closure) -> array

The following examples show this function, and its output, when used in a RETURN statement:

RETURN array::filter_index(['a', 'b', 'c', 'b', 'a'], 'b'); -- [ 1, 3 ] RETURN [0, 0, 1, 0, 0, 5, 1].filter_index(0); -- [ 0, 1, 3, 4 ]

The array::filter_index function can also take a closure for more customized filtering.

[ { importance: 10, message: "I need some help with this query..." }, { importance: 0, message: "TEST Is this thing on?" }, { importance: 5, message: "I have an idea. What if we..."}, { importance: 100, message: "Stuck on an island with two hours of battery life left. Can you..."} ].filter_index(|$v| $v.importance > 5);
Response
[0, 3 ]

array::find

The array::find function returns the first occurrence of value in the array or NONE if array does not contain value.

API DEFINITION
array::find(array, value) -> value | NONE array::find(array, @closure) -> value | NONE

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

RETURN array::find(['a', 'b', 'c', 'b', 'a'], 'b'); -- b RETURN [1, 2, 3].find(4); -- [NONE]

The array::find function is most useful when a closure is passed in which allows for customized searching.

-- Find a number 3 or greater RETURN [1, 2, 3].find(|$num| $num > 3); -- Find the first adventurer good enough for the task [ { strength: 15, intelligence: 6, name: "Dom the Magnificent" }, { strength: 10, intelligence: 15, name: "Mardine" }, { strength: 20, intelligence: 3, name: "Gub gub" }, { strength: 10, intelligence: 18, name: "Lumin695" } ].find(|$c| $c.strength > 9 AND $c.intelligence > 9);
Response
-------- Query -------- NONE -------- Query -------- { intelligence: 15, name: 'Mardine', strength: 10 }

array::find_index

The array::find_index function returns the index of the first occurrence of value in the array or NONE if array does not contain value.

API DEFINITION
array::find_index(array, value) -> number | NONE array::find_index(array, @closure) -> number | NONE

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 RETURN [1, 2, 3].find_index(4); -- NONE

The array::find_index function can also take a closure for more customized searching.

RETURN [1, 2, 3].find_index(|$num| $num > 3);
-- NONE

The array::find_index function also be called using the alias array::index_of.

["cat", "badger", "dog", "octopus"].index_of("octopus");
-- 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::flatten

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

API DEFINITION
array::flatten(array) -> 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]] ]);
Response
[ 1, 2, 3, 4, 'SurrealDB', 5, 6, [7, 8] ]

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. A negative index can be provided to specify a position relative to the end of the array.

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::is_empty

Available since: v2.0.0

The array::is_empty function checks whether the array contains values.

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

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

An array that contain values
RETURN array::is_empty([1, 2, 3, 4]); false
An empty array
RETURN array::is_empty([]); true

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::last function 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 function performs the AND logical operation element-wise between two arrays. The resulting array will have a length of the longer of the two input arrays, where each element is the result of the logical AND operation performed between an element from the left hand side array and an element from the right hand side array.

When both of the compared elements are truthy, the resulting element will have the type and value of one of the two truthy values, prioritizing the value and type of the element from the left hand side (the first array).

When one or both of the compared elements are not truthy, the resulting element will have the type and value of one of the non-truthy value(s), prioritizing the value and type of the element from the left hand side (the first array).

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 function performs the OR logical operations element-wise between two arrays.

The resulting array will have a length of the longer of the two input arrays, where each element is the result of the logical OR operation performed between an element from the left hand side array and an element from the right hand side array.

When one or both of the compared elements are truthy, the resulting element will have the type and value of one of the two truthy value(s), prioritizing the value and type of the element from the left hand side (the first array).

When both of the compared elements are not truthy, the resulting element will have the type and value of one of the non-truthy values, prioritizing the value and type of the element from the left hand side (the first array).

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_xor function performs the XOR logical operations element-wise between two arrays.

The resulting array will have a length of the longer of the two input arrays, where each element is the result of the logical XOR operation performed between an element from the left hand side array and an element from the right hand side array.

When exactly one of the compared elements is truthy, the resulting element will have the type and value of the truthy value.

When both of the compared elements are truthy, the resulting element will be the bool value false.

When neither of the compared elements are truthy, the resulting element will have the type and value of one of the non-truthy values, prioritizing the value and type of the element from the left hand side (the first array).

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::map

The array::map function allows the user to call an anonymous function (closure) that is performed on every item in the array before passing it on.

API DEFINITION
array::map(array, @closure) -> array;

The most basic use of array::map involves choosing a parameter name for each item in the array and a desired output. The following example gives each item the parameter name $v, which can then be used to double the value.

[1, 2, 3].map(|$v| $v * 2);
Response
[ 2, 4, 6 ]

An example of a longer operation that uses {} to allow the closure to take multiple lines of code:

["1", "2", "3"].map(|$val| { LET $num = <number>$val; LET $is_even = IF $num % 2 = 0 { true } ELSE { false }; { value: $num, is_even: $is_even } });
Response
[ { is_even: false, value: 1 }, { is_even: true, value: 2 }, { is_even: false, value: 3 } ]

The types for the closure arguments and output can be annotated for extra type safety. Take the following simple closure:

[1, 2, 3].map(|$num| $num + 1.1);

The output is [2.1f, 3.1f, 4.1f].

However, if the 1.1 inside the function was actually a typo and should have been the integer 11, the following would have prevented it from running.

[1, 2, 3].map(|$num: int| -> int { $num + 1.1 });
Response
'There was a problem running the ANONYMOUS function. Expected this function to return a value of type int, but found 2.1f'

The array::map function also allows access to the index of each item if a second parameter is added.

[ ": first used in the year 876", ": the number of moons in the sky", ": also called a pair" ] .map(|$item, $index| <string>$index + $item);
Response
[ '0: first used in the year 876', '1: the number of moons in the sky', '2: also called a pair' ]

For a similar function that allows using a closure on entire values instead of each item in an array, see the chain method.

array::max

The array::max function 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 function returns an array of booleans indicating which elements of the input array contain a specified value.

API DEFINITION
array::matches(array, value) -> array<bool>

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: r"ohno:0"}, {id: r"ohno:1"}], {id: r"ohno:1"}); [ false, true ]

array::min

The array::min function 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. If the array is empty, NONE is returned.

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

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::range

Available since: v2.0.0

The array::range function creates an array of numbers from a given range.

API DEFINITION
array::range(start: int, count: int) -> array

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

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

array::remove

The array::remove function removes an item from a specific position in an array. A negative index can be provided to specify a position relative to the end of the array.

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::repeat

Available since: v2.0.0

The array::repeat function creates an array of a given size contain the specified value for each element.

API DEFINITION
array::repeat(any, count: int) -> array

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

RETURN array::repeat(1, 10); [ 10, 10, 10, 10, 10, 10, 10, 10, 10, 10 ]
RETURN array::repeat("hello", 2); [ "hello", "hello" ]

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::shuffle

Available since: v2.0.0

The array::shuffle function randomly shuffles the items of an array.

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

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

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

array::slice

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

API DEFINITION
array::slice(array, start: int, len: int) -> 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

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::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::swap

Available since: v2.0.0

The array::swap function swaps two values of an array based on indexes.

API DEFINITION
array::swap(array, from: int, to: int) -> array

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

RETURN array::swap(["What's", "its", "got", "in", "it", "pocketses?"], 1, 4);
Output
[ "What's", 'it', 'got', 'in', 'its', 'pocketses?' ]

The following example shows how you can use this function with a positive index, and a negative index, which will swap the first and last element from the array:

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

An error will be returned if any of the indexes are invalid that informs of range of possible indexes that can be used.

RETURN array::swap([0, 1], 100, 1000000);
Output
'Incorrect arguments for function array::swap(). Argument 1 is out of range. Expected a number between -2 and 2'

array::transpose

The array::transpose function is used to perform 2d array transposition but its 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 ]


array::windows

Available since: v2.0.0

API DEFINITION
array::windows(array, size: int) -> array

The array::windows function returns a number of arrays of length size created by moving one index at a time down the original array. The arrays returned are guaranteed to be of length size. As a result, the function will return an empty array if the length of the original array is not large enough to create a single output array.

The following examples show this function, and its output, when used in a RETURN statement:

LET $array = [1, 2, 3, 4]; RETURN array::windows($array, 2); RETURN array::windows($array, 5);
Response
[ [1, 2], [2, 3], [3, 4] ]; [];

An example of the same function used in a RELATE statement:

CREATE person:grandfather, person:father, person:son; FOR $pair IN array::windows(["grandfather", "father", "son"], 2) { LET $first = type::thing("person", $pair[0]); LET $second = type::thing("person", $pair[1]); RELATE $first->father_of->$second; }; SELECT id, ->father_of->person, ->father_of->father_of->person FROM person;

Method chaining

Available since: v2.0.0

Method chaining allows functions to be called using the . dot operator on a value of a certain type instead of the full path of the function followed by the value.

-- Traditional syntax array::push(["Again", "again"], "again"); -- Method chaining syntax ["Again", "again"].push("again");
Response
["Again", "again", "again"]

This is particularly useful for readability when a function is called multiple times.

-- Traditional syntax array::join(array::push(["Again", "again"], "again")); -- Method chaining syntax ["Again", "again"].push("again").join(" and ");
Response
"Again and again and again"
© SurrealDB GitHub Discord Community Cloud Features Releases Install