List.Union
ListReturns the union of a list of lists, containing all distinct items from all lists combined.
Syntax
List.Union(lists as list, optional equationCriteria as any) as listParameters
| Name | Type | Required | Description |
|---|---|---|---|
lists | list | Yes | A list of lists to compute the union of. |
equationCriteria | any | No | An optional equation criteria to control how equality is determined when deduplicating. |
Return Value
list — A list of all distinct items that appear in any of the provided lists.
Remarks
List.Union takes a list of lists as its argument and returns a single list containing all distinct values from all the input lists combined. It is equivalent to List.Distinct(List.Combine({list1, list2, list3})) but expresses the intent more cleanly.
Note the argument shape: you must wrap your input lists in an outer list — {listA, listB} — not pass them as separate arguments. This is the same convention used by List.Intersect.
The result contains only distinct values. Duplicates within a single input list and duplicates across input lists are all deduplicated. The order of items in the result follows their first appearance, scanning the input lists from left to right. Comparison is case-sensitive for text by default; pass Comparer.OrdinalIgnoreCase as the optional second argument for case-insensitive deduplication.
For combining lists without deduplication, use List.Combine. For finding items common to all lists, use List.Intersect.
Examples
Example 1: Union of two lists
List.Union({{1, 2, 3}, {2, 3, 4, 5}})Result | |
|---|---|
| 1 | {1, 2, 3, 4, 5} |
Example 2: Union of three lists
List.Union({{"A", "B"}, {"B", "C"}, {"C", "D", "E"}})Result | |
|---|---|
| 1 | {A, B, C, D, E} |
Example 3: Combine customer lists from multiple regions
let
RegionA = {"Cust-01", "Cust-02", "Cust-03"},
RegionB = {"Cust-02", "Cust-04"},
RegionC = {"Cust-03", "Cust-05"},
AllCustomers = List.Union({RegionA, RegionB, RegionC})
in
AllCustomersResult | |
|---|---|
| 1 | {Cust-01, Cust-02, Cust-03, Cust-04, Cust-05} |