List.Difference
ListReturns items from the first list that do not appear in the second list.
Syntax
List.Difference(list1 as list, list2 as list, optional equationCriteria as any) as listParameters
| Name | Type | Required | Description |
|---|---|---|---|
list1 | list | Yes | The source list to filter. |
list2 | list | Yes | The list of values to exclude from list1. |
equationCriteria | any | No | An optional equation criteria value to control comparison. Use a comparer function for custom equality logic. |
Return Value
list — A list of items present in list1 but not in list2.
Remarks
List.Difference performs a set-difference operation: it returns all items from list1 that do not appear in list2. The result preserves the order of items from list1. Duplicate values in list1 that are not in list2 are kept; duplicates that match something in list2 are all removed.
This is the right tool for finding what was added or removed between two snapshots — for example, which product codes appear in last month's inventory but not this month's, or which users were revoked access between two permission exports.
Comparison is case-sensitive for text by default. Pass Comparer.OrdinalIgnoreCase as the equationCriteria argument for case-insensitive matching. Note that List.Difference is a set-semantic operation — it deduplicates the exclusion set in list2 but not in list1. If you need to remove individual matched occurrences one-for-one, use List.RemoveItems instead.
Examples
Example 1: Find items in list1 not in list2
List.Difference({1, 2, 3, 4, 5}, {2, 4})Result | |
|---|---|
| 1 | {1, 3, 5} |
Example 2: Find discontinued products
let
LastMonth = {"Widget A", "Widget B", "Widget C", "Widget D"},
ThisMonth = {"Widget A", "Widget C"},
Discontinued = List.Difference(LastMonth, ThisMonth)
in
DiscontinuedResult | |
|---|---|
| 1 | {Widget B, Widget D} |
Example 3: Case-insensitive difference
List.Difference({"Apple", "Banana", "Cherry"}, {"apple", "cherry"}, Comparer.OrdinalIgnoreCase)Result | |
|---|---|
| 1 | {Banana} |