Array Functions and Operators

Arrays store expressions of the same type in an ordered list.

Constructing arrays

An array constructor is an expression that consists of a sequence of comma-separated expressions of the same type enclosed in square brackets. It produces an array value:

"[" expr [, ...] "]"

For example:

db>

select [1, 2, 3];

{[1, 2, 3]}

db>

select [('a', 1), ('b', 2), ('c', 3)];

{[('a', 1), ('b', 2), ('c', 3)]}

Empty arrays

An empty array can also be created, but it must be used together with a type cast, since EdgeDB cannot infer the type of an array that contains no elements.

db>

select [];

QueryError: expression returns value of indeterminate type
Hint: Consider using an explicit type cast.
### select [];
###        ^

db>

select <array<int64>>[];

{[]}

Functions and operators

Reference

type

array

Arrays represent a one-dimensional homogeneous ordered list.

Array indexing starts at zero.

With the exception of other array types, any type can be used as an array element type.

An array type is created implicitly when an array constructor is used:

db>

select [1, 2];

{[1, 2]}

The syntax of an array type declaration can be found in this section.

See also the list of standard array functions and generic functions such as len().

operator

array[i]

array<anytype> [ int64 ] -> anytype

Array indexing.

Example:

db>

select [1, 2, 3][0];

{1}

db>

select [(x := 1, y := 1), (x := 2, y := 3.3)][1];

{(x := 2, y := 3.3)}

Negative indexing is supported:

db>

select [1, 2, 3][-1];

{3}

Referencing a non-existent array element will result in an error:

db>

select [1, 2, 3][4];

InvalidValueError: array index 4 is out of bounds

operator

array[from:to]

array<anytype> [ int64 : int64 ] -> anytype

Array slicing.

An omitted lower bound defaults to zero, and an omitted upper bound defaults to the size of the array.

The upper bound is non-inclusive.

Examples:

db>

select [1, 2, 3][0:2];

{[1, 2]}

db>

select [1, 2, 3][2:];

{[3]}

db>

select [1, 2, 3][:1];

{[1]}

db>

select [1, 2, 3][:-2];

{[1]}

Referencing an array slice beyond the array boundaries will result in an empty array (unlike a direct reference to a specific index):

db>

select [1, 2, 3][1:20];

{[2, 3]}

db>

select [1, 2, 3][10:20];

{[]}

operator

array ++ array

array<anytype> ++ array<anytype> -> array<anytype>

Array concatenation.

db>

select [1, 2, 3] ++ [99, 98];

{[1, 2, 3, 99, 98]}

function

array_agg()

std::array_agg(s: set of anytype) -> array<anytype>

Return an array made from all of the input set elements.

The ordering of the input set will be preserved if specified.

db>

select array_agg({2, 3, 5});

{[2, 3, 5]}

db>

select array_agg(User.name order by User.name);

{['Alice', 'Bob', 'Joe', 'Sam']}

function

array_get()

std::array_get(array: array<anytype>, index: int64, named only default: anytype = {} ) -> optional anytype

Return the element of array at the specified index.

If index is out of array bounds, the default or {} (empty set) is returned.

This works the same as array indexing operator except that if the index is outside array boundaries an empty set of the array element type is returned instead of raising an exception.

db>

select array_get([2, 3, 5], 1);

{3}

db>

select array_get([2, 3, 5], 100);

{}

db>

select array_get([2, 3, 5], 100, default := 42);

{42}

function

array_unpack()

std::array_unpack(array: array<anytype>) -> set of anytype

Return array elements as a set.

The ordering of the returned set is not guaranteed.

db>

select array_unpack([2, 3, 5]);

{3, 2, 5}

function

array_join()

std::array_join(array: array<str>, delimiter: str) -> str

Render an array to a string.

Join a string array into a single string using a specified delimiter:

db>

select to_str(['one', 'two', 'three'], ', ');

{'one, two, three'}

function

array_fill()

std::array_fill(val: anytype, n: int64) -> array<anytype>

Make a new array of specified size and filled with specified value.

Create anarray of size n where every element has the value val.

db>

select array_fill(0, 5);

{[0, 0, 0, 0, 0]}

db>

select array_fill('n/a', 3);

{['n/a', 'n/a', 'n/a']}

function

array_replace()

std::array_replace(array: array<anytype>, old: anytype, new: anytype) -> array<anytype>

Return an array where all occurrences of a particualr value are replaced.

Return an array where every old value is replaced with new.

db>

select array_replace([1, 1, 2, 3, 5], 1, 99);

{[99, 99, 2, 3, 5]}

db>

select array_replace(['h', 'e', 'l', 'l', 'o'], 'l', 'L');

{['h', 'e', 'L', 'L', 'o']}