ARRAY

ARRAY(ignore_null, *fields)[source]

Creates a Formula representing an array from the provided fields.

The ARRAY function constructs an array from the input values or model components. Optionally, fields with blank values can be excluded if ignore_null is True. All input fields must have the same data type and cannot themselves be arrays or maps.

Parameters:

ignore_null (Operand | bool) –
Boolean or model component indicating whether to exclude BLANK values from the resulting array.

Supported types:
- BOOLEAN
*fields (Operand | str | int | float | bool) –
An arbitrary number of scalar values, model components, or BLANK() values to include in the array. All non-BLANK fields must share the same data type and cannot be MapDataTypes. At least one non-BLANK field must be provided to determine the array data type.

Supported types:
- STRING
- INTEGER
- DECIMAL
- BOOLEAN
- DATE
- TIME
- DATETIME
- OBJECT
- STRING_ARRAY
- INTEGER_ARRAY
- DECIMAL_ARRAY
- BOOLEAN_ARRAY
- DATE_ARRAY
- TIME_ARRAY
- DATETIME_ARRAY
- OBJECT_ARRAY
- NULL (BLANK)

Return type:

Formula

Returns:

A Formula object representing the constructed array.

Supported types:

STRING_ARRAY
INTEGER_ARRAY
DECIMAL_ARRAY
BOOLEAN_ARRAY
DATE_ARRAY
TIME_ARRAY
DATETIME_ARRAY
OBJECT_ARRAY

Raises:

ValueError – If no fields are provided.
ValueError – If all fields are BLANK (cannot determine data type).
ValueError – If non-BLANK field types are inconsistent.
ValueError – If any non-BLANK field is a MapDataType.
ValueError – If ignore_null is not a BOOLEAN type.

Examples

Creating an array from primitive values:

ARRAY(False, 1, 2, 3)
# Returns [1, 2, 3]

Creating an array excluding blank values:

ARRAY(True, CONST(1), BLANK(), CONST(3))
# Returns [1, 3]

Creating an array that includes BLANK values:

ARRAY(False, CONST(1), BLANK(), CONST(3))
# Returns [1, BLANK(), 3]

Combining arrays where some elements are BLANK:

ARRAY(False, ARRAY(False, 1, 2), ARRAY(False, 3, BLANK()))
# Returns [1, 2, 3, BLANK()]