Using the anyMatch Template

Home
Essential Knowledge
By Type
Building Blocks
APIs
Releases

Essential knowledge

Author:

Esma Tuzovic

Changed on:

3 June 2024

Overview

The Mystique manifest configures icons, cards, and templates. Templates can be structured in various ways; for further details, please consult the UX Configuration Common Concepts article. This article, 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).

`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'`.
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`.
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`.
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`:

`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

Logic functions for regular templates Vs anyMatch templates

The logic functions vary slightly between both templates. While most functions remain consistent (such as `eq`, `ne`, `lt`, `lte`, `gt`, `gte`), regular templates include additional functions like `and`, `or`, and `firstDefinedValue`, whereas anyMatch includes `includes,` `like` and `likeIncludes`.

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'