Arrays

An array is a collection of values contained inside [] (square brackets), each of which is stored at a certain index. Individual indexes and slices of indexes can be accessed using the same square bracket syntax.

-- Return a full array
RETURN [1,2,3,4,5];
-- Return the first ("zeroeth") item
RETURN [1,2,3,4,5][0];
-- Return indexes 0 up to and including 2 of an array
RETURN [1,2,3,4,5][0..=2];

-------- Query 1 --------

[
	1,
	2,
	3,
	4,
	5
]

-------- Query 2 --------

1

-------- Query 3 --------

[
	1,
	2,
	3
]

Arrays are frequently encountered in SurrealDB, as SELECT statements return an array of values by default unless the ONLY keyword is used on an array that contains a single item.

-- Use the `ONLY` clause to return a single item
SELECT * FROM ONLY 9;
-- Error: array has more than one item
SELECT * FROM ONLY [1,9];

-------- Query 1  --------

[
	9
]

-------- Query 2 --------

9

-------- Query 3 --------

'Expected a single result output when using the ONLY keyword'

Records in SurrealDB can store arrays of values, including arrays within arrays. Arrays can store any value stored within them, and can store different value types within the same array.

CREATE person SET results = [
	{ score: 76, date: "2017-06-18T08:00:00Z", name: "Algorithmics" },
	{ score: 83, date: "2018-03-21T08:00:00Z", name: "Concurrent Programming" },
	{ score: 69, date: "2018-09-17T08:00:00Z", name: "Advanced Computer Science 101" },
	{ score: 73, date: "2019-04-20T08:00:00Z", name: "Distributed Databases" },
];

A required number of items can be specified for an array.

DEFINE FIELD employees ON TABLE team TYPE array<record<employee>, 5>;
CREATE team:one SET employees = [
	employee:one, 
	employee:two, 
	employee:three, 
	employee:four, 
	employee:five, 
	employee:doesnt_belong
];

"Couldn't coerce value for field `employees` of `team:one`:
Expected `array<record<employee>,5>` but found a collection of length `6`"

Mapping and filtering on arrays

The [] operator after an array can also be used to filter the items inside an array. The parameter $this is used to refer to each individual item, while WHERE (or its alias ?, a question mark) is used to set the condition for the item to pass the filter.

[true, false, true][WHERE $this = true];

[true, true]

If a WHERE or ? clause finds an item that by itself is not equal to true or false, it will check the item's truthiness to determine whether to pass it on or not.

[1,2,NONE][? $this];

-- [1, 2]

Filtering can be repeated if desired.

[
    {
        name: "Boston",
        population: NONE,
        first_mayor: "John Phillips"
    },
    {
        name: "Smurfville",
        population: 55,
        first_mayor: "Papa Smurf"
    },
    {
        name: "Harrisburg",
        population: 50183,
        first_mayor: NONE
    }
][WHERE $this.population]
 [WHERE $this.first_mayor];

[
	{
		first_mayor: 'Papa Smurf',
		name: 'Smurfville',
		population: 55
	}
]

Filtering and mapping with array functions

SurrealDB also includes a number of methods for arrays that make it easier to filter and map. These methods take a closure (an anonymous function) that works in a similar way to the $this parameter above.

Here is an example of the array::filter() method being used in contrast to the classic WHERE syntax. Note that the parameter name inside the closure is named by the user, so $val in the example below could be $v or $some_val or anything else.

[1,3,5].filter(|$val| $val > 2);
[1,3,5][WHERE $this > 2];

-- [3,5]

While the array functions section of the documentation contains the full details of each function, the following examples provide a glimpse into how they are commonly used.

The array::map() function provides access to each item in an array, allowing an opearation to be performed on it before being passed on.

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

-- [2,3,4]

If desired, a second parameter can be passed in that holds the index of the item.

[1,2,3]
    .map(|$v, $i| 
    "At index " + <string>$i + " we got a " + <string>$v + "!");

[
	'At index 0 we got a 1!',
	'At index 1 we got a 2!',
	'At index 2 we got a 3!'
]

Adding arrays

An array can be added to another array, resulting in a single array consisting of the items of the first followed by those of the second. This is identical to the array::concat() function.

[1,2] + [3,4];
[1,2].concat([3,4]);

[1,2,3,4]