Using the anyMatch Template
Author:
Esma Tuzovic
Changed on:
3 June 2024
Overview
The configures icons, cards, and templates. Templates can be structured in various ways; for further details, please consult the UX Configuration Common Concepts . This , however, will specifically concentrate on the any Match template.
This template functions as a filter for a stream (such as a list of items), capable of matching none, some, or all records where a specific condition is met by a field path. This feature is particularly valuable for filtering purposes.
Key points
- The anyMatch template is used for performing conditional checks on structured data streams (i.e lists, arrays), typically JSON. The template requires three inputs parameters:
`STRING_PATH_TO_VARIABLE`
,`VALUE`
and`OPTIONAL_FUNCTION .`
- This template checks if a specific path within your data structure matches a given value.
- The anyMatch template also supports optional functions to perform different kinds of comparisons. The optional functions will compare the specified path to the value and return results if there is a match.
Syntax
All `anyMatch`
templates must adhere to the syntax outlined below when being utilized.
1{{anyMatch 'STRING_PATH_TO_VARIABLE' 'VALUE' 'OPTIONAL_FUNCTION'}}
Parameters
`STRING_PATH_TO_VARIABLE`
A dot-separated string that outlines the path to a variable within your data structure, navigating through both objects and arrays at intermediary levels. The path `"node.entity.field.subfield1"`
aims to reach `subfield1`
inside the structure `{node: {entity: {field: {subfield1: ...}}}}`
. Here, `node`
, `entity`
, and `field`
can represent objects or arrays, enabling traversal through each element of any arrays found along the way. The endpoint of the path, `subfield1`
in this case, is typically expected to be a singular value or a simple array of primitive values, especially when using functions like `includes`
that operate on collections.
1{
2 "node": [
3 {
4 "entity": {
5 "field": [
6 {
7 "subfield1": ["alpha", "beta"],
8 "subfield2": "delta"
9 },
10 {
11 "subfield1": ["gamma"],
12 "subfield2": "theta"
13 }
14 ]
15 }
16 }
17 ]
18}
Applying `anyMatch`
:
- To check if any
`subfield2`
within the structure equals`"delta"`
, you'd use:`{{anyMatch "node.entity.field.subfield2" "delta" "eq"}}`
This would return`'true'`
because`subfield2`
directly equals`"delta"`
in the second key of the field object - To check if any array
`subfield1`
includes`"beta"`
, you'd use:`{{anyMatch "node.entity.field.subfield1" "beta" "includes"}}`
This would return`'true'`
because`subfield1`
in the first object of the`field`
array includes`"beta"`
.
Operation Explanation:
`anyMatch`
starts at the`node`
, recognizes it as an array, and iterates through its objects.- In each object under the
`node`
, it accesses the`entity`
and then moves to the`field`
, which is also recognized as an array. - It then iterates through each object in the
`field`
array, inspecting`subfield1`
in each one.- If
`subfield1`
is a singular value, it checks if it matches the specified value (for`eq`
operation). - If
`subfield1`
is an array of primitive values, it checks if the array includes the specified value (for`includes`
operation).
- If
`VALUE`
The `VALUE`
parameter in the `anyMatch`
template represents the benchmark or criterion against which the data found at the specified path (`STRING_PATH_TO_VARIABLE`
) is compared. It's a versatile component that can accommodate various data types, including strings, numbers, and booleans, depending on the context of your data and the specific operation you're performing. Here's a breakdown:
- String: When
`VALUE`
is a string,`anyMatch`
compares the specified path's data to this string. This is particularly useful for operations like`eq`
(equality),`ne`
(inequality),`includes`
(for checking if a substring is part of a larger string or if an array includes a specific string), and pattern-based functions similar to`like`
.- Example:
`{{anyMatch "node.entity.field.subfield1" "expectedString" "eq"}}`
checks if`subfield1`
equals`'expectedString'`
.
- Example:
- Number: When
`VALUE`
is a number,`anyMatch`
performs numerical comparisons. This is essential for conditional checks like`lt`
,`gt`
,`lte`
,`gte`
.- Example:
`{{anyMatch "node.entity.field.quantity" 100 "lte"}}`
checks if`quantity`
is less than or equal to`100`
.
- Example:
- Boolean: When
`VALUE`
is a boolean (`true`
or`false`
),`anyMatch`
can be used to verify boolean conditions, ensuring that the data at the specified path aligns with the expected boolean value.- Example:
`{{anyMatch "node.entity.field.isActive" true "eq"}}`
checks if`isActive`
is`true`
.
- Example:
- Variable: Sometimes, you might want to compare the data at the specified path with the value of another variable rather than a hard-coded value. In such cases,
`VALUE`
can be a reference to another variable in your data structure, allowing for dynamic comparisons based on your data's state.- Example: If you have a variable reference like
`otherValue`
,`{{anyMatch "node.entity.field.subfield1" otherValue "eq"}}`
compares`subfield1`
with the value of`otherValue`
.Applying`anyMatch`
:
- Example: If you have a variable reference like
`OPTIONAL_FUNCTION`
(optional):
A string representing the comparison or operation you want to perform. Supported functions include:
`"eq"`
: Checks for equality.`"ne"`
: Checks for inequality.`"lt"`
: Checks if the variable is less than the value.`"lte"`
: Checks if the variable is less than or equal to the value.`"gt"`
: Checks if the variable is greater than the value.`"gte"`
: Checks if the variable is greater than or equal to the value.`"includes"`
: Checks if the variable (an array ) includes the value.`"like"`
: Checks if the variable is 'like' the value, based on case insensitive search`"likeIncludes"`
: Combination of the above two where the value can be an array
Returns:
`true`
or `false`
as a string, indicating whether the condition was met.
Operator | Expectation | Behavior | Use Case Example with Array at Any Level | Use Case Example without Array |
"eq" | Any data type | Checks exact equality. Iterates through arrays at any level in the path and stops at the first match found in the specified field. | { node: { entity: [{ field: { subfield1: [{ itemId: ‘1234' }] } }] } } with {{anyMatch "node.entity.field.subfield1.itemId" "1234" "eq"}} → 'true' if any “itemId” under subfield1 array is equal to '1234'. | { node: { entity: { field: { subfield1: { itemId: '1234' } } } } } with {{anyMatch "node.entity.field.subfield1.itemId" "1234" "eq"}} → 'true' |
"ne" | Any data type | Checks inequality. Iterates through arrays at any level in the path and stops at the first non-matching field. | { node: { entity: [{ field: { subfield1: [{ itemId: '1234' }] } }] } } with {{anyMatch "node.entity.field.subfield1.itemId" "1234" "ne"}} → 'true' if any “itemId” under subfield1 array is not '1234'. | { node: { entity: { field: { subfield1: { itemId: '1234' } } } } } with {{anyMatch "node.entity.field.subfield1.itemId" "1234" "ne"}} → 'true' |
"lt" | Numeric data types | Checks if less than provided value. Iterates through arrays at any level in the path and stops at the first match found. | { node: { entity: [{ field: { subfield1: [{ itemQty: 3 }] } }] } } with {{anyMatch "node.entity.field.subfield1.itemQty" 5 "lt"}} → 'true' if any itemQty under subfield1 array is less than 5. | { node: { entity: { field: { subfield1: { itemQty : 3 } } } } } with {{anyMatch "node.entity.field.subfield1.itemQty" 5 "lt"}} → 'true' |
"lte" | Numeric data types | Checks if less than or equal to provided value. Iterates through arrays at any level in the path and stops at the first match found. | { node: { entity: [{ field: { subfield1: [{ itemQty: 5 }] } }] } } with {{anyMatch "node.entity.field.subfield1.itemQty" 5 "lte"}} → 'true' if any itemQty under subfield1 array is less than or equal to 5. | { node: { entity: { field: { subfield1: { itemQty: 5 } } } } } with {{anyMatch "node.entity.field.subfield1.itemQty" 5 "lte"}} → 'true' |
"gt" | Numeric data types | Checks if greater than provided value. Iterates through arrays at any level in the path and stops at the first match found. | { node: { entity: [{ field: { subfield1: [{ itemQty: 6 }] } }] } } with {{anyMatch "node.entity.field.subfield1.itemQty" 5 "gt"}} → 'true' if any itemQty under subfield1 array is greater than 5. | { node: { entity: { field: { subfield1: { itemQty: 6 } } } } } with {{anyMatch "node.entity.field.subfield1.itemQty" 5 "gt"}} → 'true' |
"gte" | Numeric data types | Checks if greater than or equal to provided value. Iterates through arrays at any level in the path and stops at the first match found. | { node: { entity: [{ field: { subfield1: [{ itemQty: 5 }] } }] } } with {{anyMatch "node.entity.field.subfield1.itemQty" 5 "gte"}} → 'true' if any itemQty under subfield1 array is greater than or equal to 5. | { node: { entity: { field: { subfield1: { itemQty: 5 } } } } } with {{anyMatch "node.entity.field.subfield1.itemQty" 5 "gte"}} → 'true' |
"includes" | Iterable collection (array/string) | Checks if collection includes provided value. Iterates through arrays at any level in the path and stops at the first match found. | { node: { entity: [{ field: { subfield1: [{ sellableQty: [1, 2, 3] }] } }] } } with {{anyMatch "node.entity.field.subfield1.sellableQty" 2 "includes"}} → 'true' if any sellableQty array under subfield1 array includes 2. | { node: { entity: { field: { subfield1: { sellableQty: '123' } } } } } with {{anyMatch "node.entity.field.subfield1.sellableQty" "2" "includes"}} → 'true' |
"like" | String data types | More flexible match which is case insensitive . Iterates through arrays at any level in the path and stops at the first match found. | { node: { entity: [{ field: { subfield1: [{ key: 'hello world' }] } }] } } with {{anyMatch "node.entity.field.subfield1.key" "world" "like"}} → 'true' if any key under subfield1 array is like world. | { node: { entity: { field: { subfield1: { key: 'hello' } } } } } with {{anyMatch "node.entity.field.subfield1.key" "llo" "like"}} → 'true' |
"likeIncludes" | Iterable collection (array/string) | Combination of the above two functions that will perform a case insensitive partial string match on arrays. | { node: { entity: [{ field: { subfield1: [{ customers: ['John Smith', 'Albert Fumbledoor', 'Bilbo Haggins'] }] } }] } } with {{anyMatch "node.entity.field.subfield1.customers" "door" "likeIncludes"}} → 'true' if any customers array under subfield1 array includes 'door'. | { node: { entity: { field: { subfield1: { customer: 'Samwise Crabtree' } } } } } with {{anyMatch "node.entity.field.subfield1.sellableQty" "tree" "includes"}} → 'true' |