Array ​

Array(T) stores an ordered collection of values of type T. Arrays can be empty and can contain other arrays or typed collections.

Creating an Array ​

Construct an array with array(...), or pass standard JSON array text to a typed column or cast. An explicit type is useful for empty arrays and when the element range must be checked.

SELECT array(1, 2, 3), CAST('[]' AS Array(UInt8))
FORMAT csv;

"[1,2,3]","[]"

Nested declarations preserve their element contracts even when the arrays are empty:

SELECT CAST('[[1,2],[]]' AS Array(Array(UInt8)))
FORMAT csv;

"[[1,2],[]]"

Working with Data Types ​

Array(T)

• T — The element type. Every element is converted and validated against this type.

Use Array(Nullable(T)) to allow missing elements. A top-level array column can itself be NULL unless declared NOT NULL.

Array Size ​

Use array_length to count array elements. An empty array has length zero; NULL members still count as elements.

SELECT array_length(array(1, 2, 3)),
       array_length(CAST('[]' AS Array(Int32)))
FORMAT csv;

3,0

Accessing elements ​

array_element(array, index) uses positions starting at 1. Negative positions count from the end. Position 0 raises INVALID_ARGUMENT. A position outside the array returns the declared element type's default, such as zero or an empty string; nullable elements default to NULL.

SELECT array_element(array(10, 20), 1),
       array_element(array(10, 20), -1),
       array_element(CAST('[10,20]' AS Array(UInt8)), 3)
FORMAT csv;

10,20,0

Use the function syntax; bracket access such as tags[1] and lambda expressions are not implemented.

Example ​

Storing nullable measurements ​

CREATE TABLE samples(id UInt32, readings Array(Nullable(UInt8)));
INSERT INTO samples VALUES (1, '[10,null,20]');

SELECT id, readings, array_length(readings) AS positions
FROM samples
FORMAT csv;

1,"[10,null,20]",3

See array functions for membership, slicing and other operations, and array_agg for collecting rows into an array.