List.RemoveMatchingItems

List

Removes all occurrences of items found in the second list from the first list.

Examples on this page use shared sample tables. View them to understand the input data before reading the examples below.

Syntax

List.RemoveMatchingItems(list1 as list, list2 as list, optional equationCriteria as any) as list

Parameters

NameTypeRequiredDescription
list1listYesThe source list to remove items from.
list2listYesThe list of values to remove from list1.
equationCriteriaanyNoAn optional equation criteria to control how equality is determined.

Return Value

list — A new list with all occurrences of list2 items removed from list1.

Remarks

List.RemoveMatchingItems removes all occurrences of any value in list2 from list1. It scans through list1 and filters out any item that appears anywhere in list2. Duplicates in list1 are both removed if the value appears in list2; duplicates in list1 that are not in list2 are preserved.

The key distinction from related functions: List.RemoveMatchingItems removes every occurrence of each matching value; List.RemoveItems removes only one occurrence per entry in list2 (one-for-one removal); List.Difference performs a set-difference and deduplicates the result. Choose based on whether you want value-based filtering (this function), occurrence counting (List.RemoveItems), or a set operation (List.Difference).

Comparison is case-sensitive for text by default. Pass Comparer.OrdinalIgnoreCase as the equationCriteria argument for case-insensitive removal. Returns a new list; the originals are not modified.

Examples

Example 1: Remove all matching values

List.RemoveMatchingItems({1, 2, 3, 2, 4, 2, 5}, {2, 4})
Result
Result
1{1, 3, 5}

Example 2: Remove stopwords from a word list

let
    Words = {"the", "quick", "the", "brown", "fox", "the"},
    Stopwords = {"the", "a", "an"},
    Filtered = List.RemoveMatchingItems(Words, Stopwords)
in
    Filtered
Result
Result
1{quick, brown, fox}

Example 3: Case-insensitive removal

List.RemoveMatchingItems({"Apple", "APPLE", "Banana", "apple"}, {"apple"}, Comparer.OrdinalIgnoreCase)
Result
Result
1{Banana}

Related Functions

Compatibility

✓ Power BI Desktop✓ Power BI Service✓ Excel Desktop✓ Excel Online✓ Dataflows✓ Fabric Notebooks