Array Functions and Operators​

An ordered list of values of the same type.

Array indexing starts at zero.

An array can contain any type except another array. In EdgeDB, arrays are always one-dimensional.

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

db> 

select [1, 2];

{[1, 2]}

The array types themselves are denoted by array followed by their sub-type in angle brackets. These may appear in cast operations:

db> 

select <array<str>>[1, 4, 7];

{['1', '4', '7']}

db> 

select <array<bigint>>[1, 4, 7];

{[1n, 4n, 7n]}

Array types may also appear in schema declarations:

type Person {
    str_array: array<str>;
    json_array: array<json>;
}

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

Accesses the array element at a given index.

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)}

This operator also allows accessing elements from the end of the array using a negative index:

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

Produces a sub-array from an existing array.

Omitting the lower bound of an array slice will default to a lower bound of zero.

Omitting the upper bound will default the upper bound to the length of the array.

The lower bound of an array slice is inclusive while the upper bound is not.

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). Slicing with a lower bound less than the minimum index or a upper bound greater than the maximum index are functionally equivalent to not specifying those bounds for your slice:

db> 

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

{[2, 3]}

db> 

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

{[]}

Concatenates two arrays of the same type into one.

db> 

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

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

Returns 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']}

Returns the element of a given array at the specified index.

If the index is out of the array’s bounds, the default argument or {} (empty set) will be returned.

This works the same as the array indexing operator, except that if the index is out of bounds, an empty set of the array element’s 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}

Returns the elements of an array as a set.

db> 

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

{3, 2, 5}

db> 

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

{(1, 3), (0, 2), (2, 5)}

Renders an array to a string or byte-string.

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

db> 

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

{'one, two, three'}

Similarly, an array of bytes can be joined as a single value using a specified delimiter:

db> 

select array_join([b'\x01', b'\x02', b'\x03'], b'\xff');

{b'\x01\xff\x02\xff\x03'}

Returns an array of the specified size, filled with the provided value.

Create an array 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']}

Returns an array with all occurrences of one value replaced by another.

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']}