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.*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.
- Return type:
- Returns:
A Formula object representing the constructed 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()]
``ignore_null`` — accepted types
BOOLEAN
``field`` (variadic) — accepted types
BOOLEAN
BOOLEAN_ARRAY
DATE
DATETIME
DATETIME_ARRAY
DATE_ARRAY
DECIMAL
DECIMAL_ARRAY
INTEGER
INTEGER_ARRAY
NULL
OBJECT
OBJECT_ARRAY
STRING
STRING_ARRAY
TIME
TIME_ARRAY
Return types
BOOLEAN_ARRAY
DATETIME_ARRAY
DATE_ARRAY
DECIMAL_ARRAY
INTEGER_ARRAY
OBJECT_ARRAY
STRING_ARRAY
TIME_ARRAY