# Filtering Arrays
### findMatching Function
To filter array attributes according to specific criteria, you should use the `#findMatching` function. The syntax of the output of the values matching your criteria is dependent on the type of array it is used upon.
This function may be used to filter array attributes containing:
* **Simple values**, also referred to as primitives, which are values that have no properties: `string`("This is a string"), `integer`(2), `float`(5.6), `datetime`(1994-11-05T13:15:30Z), `boolean`(true).
* **Objects**, which are values with properties e.g. subscriptions
The syntax of this helper function is:
```jsx
{{#findMatching '{
"data": "[attribute]",
"criteria": [
{
"operator": "[operator]",
"value": "[value]"
}
],
"limit": [limit]
}'}}
[output]
{{/findMatching}}
```
{% hint style="info" %}
You may also use a combination of conditions in the criteria array. For example:
```jsx
...
"criteria": [
{
"operator": "[operator]",
"value": "[value]"
},
{
"operator": "[operator]",
"value": "[value]"
}
]
...
```
{% endhint %}
| Property | Type | Description | |
| ----------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| `attribute` | `string` | The user or event attribute that is used for the verification. e.g. `user.[traits.birthday]`, `[properties.price]` | |
| `operator` | `string` | The operator that will be used to asses whether the criteria is met or not. e.g. `==`. `<=`. [See the list of all available operators and their compatibility below](https://documentation.crossengage.io/personalisation/untitled/filtering-arrays#operators). | |
| `value` | `string` | The value the `attribute` property will be compared against. e.g `male`, `0` | |
| `limit` | `integer` | **Optional**. The number of values matching your criteria that will be returned by the function. e.g. `1` will return the first value that matched your criteria. | |
| `output` | `string` | Syntax dependent on the type of array the function is used upon. See the **Simple attributes** and **Objects** sections below, depending on your use case. | |
### Simple Attributes
For simple values, you should use the helper function with the following syntax:
```jsx
{{#findMatching '{
"data": "[attribute]",
"criteria": [
{
"operator": "[operator]",
"value": "[value]"
}
],
"limit": 1
}'}}
{{this}}
{{/findMatching}}
```
To output the values that match your criteria, you should use `{{this}}`. `{{this}}` will output the value satisfying your given condition/s.
### Use Cases
#### Display all devices from a given manufacturer
For this example, we output the first 2 values containing the brand name `Apple`. We use a user with the attribute below to display the result of the function:
```javascript
traits.devices = [
"Apple iPhone X","Apple iPad Pro","Samsung Galaxy S6", "Apple iPhone 5"
];
```
The syntax of the helper function with our selected criteria is:
```jsx
Your Apple devices:
{{#findMatching '{
"data": "user.[traits.devices]",
"criteria": [
{
"operator": "contains",
"value": "Apple"
}
],
"limit": 2
}'}}
- {{this}}
{{/findMatching}}
```
Once the function is evaluated, it displays the following block in the section where it is used in the message:
```markup
- Apple iPhone X
- Apple iPad Pro
```
### Objects
For object attributes, you should use the helper function with the following syntax:
```jsx
{{#findMatching '{
"data": "[attribute]",
"criteria": [
{
"operator": "[operator]",
"value": "[value]"
}
],
"limit": [limit]
}'}}
{{[property]}}
{{/findMatching}}
```
| Property | Description |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `property` | The property of the object/s matching your criteria. For example, when working with a subscription, this may be the `startDate` |
{% hint style="info" %}
You may output as many properties as needed from the `object` attribute matching your criteria.
{% endhint %}
### Use Cases
#### **Searching a list of subscriptions**
For this example, we filter a user's subscriptions to find all of **Pet Food** subscriptions with deliveries scheduled in the **next 7 days**. The date used for the purpose of the calculation is **15/06/2018**. To display the result of the function, we use an example user with the attribute below:
```javascript
traits.subscriptions = [
{
"name": "Green Petfood InsectDog hypoallergenic - 15 kg",
"category": "Pet Food",
"deliveryDate": "2018-06-20"
},
{
"name": "Ziwi Peak | Air Dried Dog Food Beef | 4 kg",
"category": "Pet Food",
"deliveryDate": "2018-06-21"
}
];
```
Additionally, to display the subscription delivery date in our preferred format, we use the formatting function `#computeDate`. The syntax of the helper function with our selected criteria and date formatting is:
```jsx
Your subscriptions with deliveries scheduled in the next 7 days:
{{#findMatching '{
"data": "user.[traits.subscriptions]",
"criteria": [
{
"property": "category",
"operator": ">=",
"value": "Pet Food"
},
{
"property": "deliveryDate",
"operator": "<",
"value": "+7d"}
]
}'}}
{{subscriptionName}}
Delivering on: {{computeDate '{
"dateTrait": "deliveryDate",
"outputFormat": "dd/mm/yyyy"
}'}}
{{/findMatching}}
```
Once the function is evaluated, it displays the following block in the section where it is used in the message:
```markup
Your subscriptions with deliveries scheduled in the next 7 days:
Green Petfood InsectDog hypoallergenic - 15 kg
Delivering on: 20/06/2018
Ziwi Peak | Air Dried Dog Food Beef | 4 kg
Delivering on: 21/06/2018
```
#### **Fetching a specific subscription from a user profile and searching the product feed for additional information**
For this example, we filter a user's subscriptions to find the first **Laundry Detergent** subscription with a delivery scheduled in the **next 7 days**. The date used for the purpose of the calculation is **11/06/2018**. To display the result of the function, we use an example user with the attribute below:
```javascript
traits.subscriptions = [
{
"name": "Tide Pods Laundry Detergent Plus",
"sku": "TD1215",
"category": "Laundry Detergent",
"deliveryDate": "2018-06-13"
}
];
```
Additionally, to display additional information regarding the product included in the subscription, we use the product helper function `#findProduct`. The syntax of the helper function with our selected criteria and additional product information is:
```jsx
{{#findMatching '{
"data": "user.[traits.subscriptions]",
"criteria": [
{
"property": "category",
"operator": ">=",
"value": "Laundry Detergent"
},
{
"property": "deliveryDate",
"operator": "<",
"value": "+7d"}
],
"limit": 1
}'}}
Delivering this week:
{{subscriptionName}}
{{#findProduct {{sku}}}}
{{/findProduct}}
{{/findMatching}}
```
Once the function is evaluated, it displays the following block in the section where it is used in the message:
```markup
Delivering this week:
Tide Pods Laundry Detergent Plus
```
UTM Parameters are parameters added to URLs to track the effectiveness of online marketing campaigns. When a link containing UTM parameters is clicked, the parameters identify the marketing campaign which has led to the link being clicked. This information can be parsed using analytics tools to guide future marketing activities.
### each Function
The #each handlebar can display a certain child within an array which cannot be accessed via the value mapping. While this function does not allow filtering itself, we can use it with the Conditional Functions to filter required results.
```handlebars
{{#each user.[traits.TRAIT-NAME}} {{CHILD-NAME}} {{/each}}
```
This will fetch the data which is in the array. However, it will fetch all of the selected fields when the fields are available multiple times.
You can use conditions inside of the loop to conditionally display the information:
```handlebars
{{#each user.[traits.NAME-HERE]}}
{{#cif '{
"property": "[ATTRIBUTE]",
"operator": "OPERATOR",
"value": "VALUE"}'
}}
{{ATTRIBUTE 1}}
{{ATTRIBUTE 2}}
{{else}}TEXT
{{/cif}}
{{/each}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://documentation.crossengage.io/data-and-engagement-platform/messages/personalization/general-helper-functions/filtering-arrays.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.