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

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
    f1 := ARRAY_UNION(ARRAY[]::BIGINT[], ARRAY[1, 2]) -- Empty array union
;

Result

f1 ARRAY
[1, 2]

Suggest changes to this page

Last update at: 2026/05/26 17:22:09

On this page

Signatures Notes See also Examples Typical unions Edge cases