Light
Dark
System

Array Functions and Operators

array[i]

Accesses the array element at a given index.

array[from:to]

Produces a sub-array from an existing array.

array ++ array

Concatenates two arrays of the same type into one.

= != ?= ?!= < > <= >=

Comparison operators

len()

Returns the number of elements in the array.

contains()

Checks if an element is in the array.

find()

Finds the index of an element in the array.

array_join()

Renders an array to a string.

array_fill()

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

array_replace()

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

array_agg()

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

array_get()

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

array_unpack()

Returns the elements of an array as a set.

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

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:

Copy
db> 
select [1, 2, 3];
{[1, 2, 3]}
Copy
db> 
select [('a', 1), ('b', 2), ('c', 3)];
{[('a', 1), ('b', 2), ('c', 3)]}

You can also create an empty array, but it must be done by providing the type information using type casting. EdgeDB cannot infer the type of an empty array created otherwise. For example:

Copy
db> 
select [];
QueryError: expression returns value of indeterminate type
Hint: Consider using an explicit type cast.
### select [];
###        ^
Copy
db> 
select <array<int64>>[];
{[]}
type
array

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:

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

Copy
db> 
select <array<str>>[1, 4, 7];
{['1', '4', '7']}
Copy
db> 
select <array<bigint>>[1, 4, 7];
{[1n, 4n, 7n]}

Array types may also appear in schema declarations:

Copy
type Person {
    property str_array -> array<str>;
    property json_array -> array<json>;
}

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

operator
array[i]
array<anytype> [ int64 ] -> anytype

Accesses the array element at a given index.

Example:

Copy
db> 
select [1, 2, 3][0];
{1}
Copy
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:

Copy
db> 
select [1, 2, 3][-1];
{3}

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

Copy
db> 
select [1, 2, 3][4];
InvalidValueError: array index 4 is out of bounds
operator
array[from:to]
array<anytype> [ int64 : int64 ] -> anytype

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:

Copy
db> 
select [1, 2, 3][0:2];
{[1, 2]}
Copy
db> 
select [1, 2, 3][2:];
{[3]}
Copy
db> 
select [1, 2, 3][:1];
{[1]}
Copy
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:

Copy
db> 
select [1, 2, 3][1:20];
{[2, 3]}
Copy
db> 
select [1, 2, 3][10:20];
{[]}
operator
array ++ array
array<anytype> ++ array<anytype> -> array<anytype>

Concatenates two arrays of the same type into one.

Copy
db> 
select [1, 2, 3] ++ [99, 98];
{[1, 2, 3, 99, 98]}
function
array_agg()
std::array_agg(s: set of anytype) -> array<anytype>

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

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

Copy
db> 
select array_agg({2, 3, 5});
{[2, 3, 5]}
Copy
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

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:

Copy
db> 
select array_get([2, 3, 5], 1);
{3}
Copy
db> 
select array_get([2, 3, 5], 100);
{}
Copy
db> 
select array_get([2, 3, 5], 100, default := 42);
{42}
function
array_unpack()
std::array_unpack(array: array<anytype>) -> set of anytype

Returns the elements of an array as a set.

The ordering of the returned set is not guaranteed.

Copy
db> 
select array_unpack([2, 3, 5]);
{3, 2, 5}
function
array_join()
std::array_join(array: array<str>, delimiter: str) -> str

Renders an array to a string.

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

Copy
db> 
select to_str(['one', 'two', 'three'], ', ');
{'one, two, three'}
function
array_fill()
std::array_fill(val: anytype, n: int64) -> array<anytype>

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

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

Copy
db> 
select array_fill(0, 5);
{[0, 0, 0, 0, 0]}
Copy
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>

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

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

Copy
db> 
select array_replace([1, 1, 2, 3, 5], 1, 99);
{[99, 99, 2, 3, 5]}
Copy
db> 
select array_replace(['h', 'e', 'l', 'l', 'o'], 'l', 'L');
{['h', 'e', 'L', 'L', 'o']}
Light
Dark
System