ARRAY_UNION()

All functions > ARRAY > ARRAY_UNION()

Returns the union of two arrays, eliminating duplicate elements.

Signatures

Returns: An array containing all unique elements from both input arrays

ARRAY_UNION(array1: ARRAY<T>, array2: ARRAY<T>) → ARRAY<T>

sql

Parameter	Type	Required	Description
`array1`	`ARRAY<T>`	Yes	The first input array
`array2`	`ARRAY<T>`	Yes	The second input array

Notes

Combines all unique elements from both arrays
Eliminates duplicate elements using set semantics
Result is sorted lexicographically
Works with arrays of any comparable type
Empty arrays are handled gracefully
Supports ARRAY<ROW> and ARRAY<ARRAY<T>>: both arrays must have the same element type; mismatched schemas raise a user error

Examples

Typical unions

FeatureQL

SELECT
    -- Basic union with numeric arrays
    f1 := ARRAY_UNION(ARRAY(1, 2, 3), ARRAY(2, 3, 4)),
    -- String arrays with duplicates
    f2 := ARRAY_UNION(ARRAY('apple', 'banana'), ARRAY('banana', 'cherry')),
    -- Multiple overlapping elements
    f3 := ARRAY_UNION(ARRAY('A', 'B', 'C'), ARRAY('B', 'C', 'D')),
    -- Duplicates within arrays eliminated
    f4 := ARRAY_UNION(ARRAY(1, 1, 2), ARRAY(2, 2, 3)),
    -- No overlapping elements
    f5 := ARRAY_UNION(ARRAY(1, 2), ARRAY(3, 4)),
    -- Result is sorted lexicographically
    f6 := ARRAY_UNION(ARRAY('Z', 'A'), ARRAY('B', 'Y'))
;

Result

f1 ARRAY	f2 ARRAY	f3 ARRAY	f4 ARRAY	f5 ARRAY	f6 ARRAY
[1, 2, 3, 4]	[apple, banana, cherry]	[A, B, C, D]	[1, 2, 3]	[1, 2, 3, 4]	[A, B, Y, Z]

Edge cases

FeatureQL

SELECT
    -- Empty array union
    f1 := ARRAY_UNION(ARRAY()::BIGINT[], ARRAY(1, 2))
;

Result

f1 ARRAY
[1, 2]

Suggest changes to this page

Last update at: 2026/06/20 10:08:10

On this page

Signatures Notes See also Examples Typical unions Edge cases