Filter Permutations¶

A template's Filter Clause can use each() to turn one template into many checks, one for each value in a list. This applies the same rule across a dimension, such as countries, regions, or product categories, without creating a separate check for every value by hand.

Syntax¶

<field_name> = each('<VALUE_1>', '<VALUE_2>', '<VALUE_3>')

each() combines with the other filter operators, such as =, >, <, AND, and IN. Only rule types that accept a filter clause can use it. Volumetric and Freshness, for example, take no filter.

One Check per Value¶

A team wants order totals to be checked separately for every country it operates in. Its Positive template uses this filter:

country_code = each('BRA', 'USA', 'ESP', 'CHN')

Applying the template to the TOTAL_AMOUNT field of the ORDERS table creates four checks, one per country. Each check gets the filter for its own value, such as country_code = 'BRA', and runs on its own, so a problem in one country fails only that country's check.

Several `each()` Clauses¶

A filter can hold more than one each(). Every combination of values becomes its own check.

region = each('EU', 'US') AND category = each('Retail', 'Wholesale')

This creates four checks:

region = 'EU' AND category = 'Retail'
region = 'EU' AND category = 'Wholesale'
region = 'US' AND category = 'Retail'
region = 'US' AND category = 'Wholesale'

Where `each()` Works¶

each() expands only when checks are created from a template:

Creating checks. Adding a check from a template, or several at once, expands the filter into its permutations.
Editing a check. A check's own filter cannot use each(). Saving one fails with The each() function cannot be used when updating a check's filter. To manage check permutations, update the template filter instead.
Applying the same permutations twice. When a table or file already has the permutation checks of a template, creating them again fails with a message naming the template to edit instead.

Changing the Values¶

Once the permutation checks exist, change their values by editing the template's filter. What happens to the checks depends on whether the template is locked:

Change to the `each()` list	Locked template	Unlocked template
Add a value	Creates a check for the new value on each table or file that already has checks from the list.	The same.
Remove a value	Deletes the check of that value.	Keeps the check. It stays as it is.
Add `each()` to a filter that had none	Splits every linked check into one check per value.	Creates no checks.

A new check is copied from a check the list already has on the same table or file, so it takes that check's fields, tags, and impact metrics. On a locked template, the rest of its definition then follows the template.

Replacing every value of the list

On a locked template, removing every value and adding new ones in the same save deletes the old checks first, so no check is left to copy and no check is created for the new values. Add the new values and save, then remove the old ones and save again.

Example¶

A locked template starts with this filter, applied to one table:

country_code = each('ITA', 'MEX', 'ESP')

The table gets three checks: Italy, Mexico, and Spain.
Adding 'BRA' to the list creates a fourth check, for Brazil.
Removing 'ESP' deletes the Spain check.

On an unlocked template, the same edits add the Brazil check, but the Spain check stays.

Filter Permutations¶

Syntax¶

One Check per Value¶

Several each() Clauses¶

Where each() Works¶

Changing the Values¶

Example¶

See Also¶

Several `each()` Clauses¶

Where `each()` Works¶