filter

Filters a list or list-like object by retaining items that return true for the filter conditions.

The first parameter takes the data to filter, and the second defines the filter conditions. For the second parameter, use a predefined helper function or write a lambda expression that returns a Boolean true or false.

How to filter JSON arrays is covered in greater depth in Filtering > Filtering a JSON array.

Tip

To filter a table region, use filterRows instead.

Parameters

INPUT (list, column, or JSON array)
The list or list-like object to filter.
FUNCTION (function)
A function defining the filter conditions. Use a predefined helper function or write a lambda expression that returns a Boolean true or false. Use a lambda to apply two or more conditions.

Helper functions

The helper functions are for single-condition filters only. They work by comparing a value against a constant, which is typically a hard-coded value or a variable returning a value.

Helper Function	Description	Equivalent Lambda Expression
`gt(constant)`	Tests if value is greater than the constant.	`x -> x > constant`
`gte(constant)`	Tests if value is greater than or equal to the constant.	`x -> x >= constant`
`lt(constant)`	Tests if value is less than the constant.	`x -> x < constant`
`lte(constant)`	Tests if value is less than or equal to the constant.	`x -> x <= constant`
`eq(constant)`	Tests if value is equal to the constant.	`x -> x == constant`

Tip

You must use a lambda expression to apply two or more filter conditions.

Examples — filtering lists

These examples show how to apply a single-condition filter to a list. This can sometimes be done with a helper function in the second parameter, but you can use a lambda expression if you prefer.

ATL in Script	Filtered List	Printed Result
`[[filter((12, 4, 56, 20, 83), gt(20))]]`	(56, 83)	56 and 83
`[[filter((12, 4, 56, 20, 83), x -> x > 20)]]`	(56, 83)	56 and 83
`[[filter((12, 4, 56, 20, 83), lte(20))]]`	(12, 4, 20)	12, 4 and 20
`[[filter((12, 4, 56, 20, 83), x -> x <= 20)]]`	(12, 4, 20)	12, 4 and 20
`[[filter((12, 4, 56, 20, 83), eq(20))]]`	(20)	20
`[[filter((12, 4, 56, 20, 83), x -> x == 20)]]`	(20)	20

To apply two or more filter conditions, you must use a lambda expression.

ATL in Script	Filtered List	Printed Result
`[[filter((12, 4, 56, 20, 83), x -> x > 15 && x < 80)]]`	(56, 20)	56 and 20
`[[filter((12, 4, 56, 20, 83), x -> x < 15 \|\| x > 80)]]`	(12, 4, 83)	12, 4 and 83

Tip

The first example above uses the AND operator (&&) to combine two logical conditions, and the second uses the OR operator (||). If you use AND, the value must meet both conditions to pass the filter. If you use OR, the value passes by meeting either condition.

You can use other ATL functions to help define filter conditions.

ATL in Script	Filtered List	Printed Result
[[ team = ('Linda', 'Piotr', 'Kapila', 'Lucia') filter(team, name -> endsWith(name,'a') && len(name) < 6) ]]	(Linda, Lucia)	Linda and Lucia

This ATL filters a list of strings. The lambda uses endsWith in the first condition and len in the second. The filter retains values that end with the 'a' character AND have fewer than six characters overall.

Examples — filtering JSON data

Assume a "Describe the JSON Object" project with this data:

{
    "finances": [
        {
            "branch": "Boston",
            "region": "East",
            "sales": 247293.49,
            "target": 300000.00
        },
        {
            "branch": "Chicago",
            "region": "Central",
            "sales": 403603.17,
            "target": 400000.00
        },
        {
            "branch": "Los Angeles",
            "region": "West",
            "sales": 457359.45,
            "target": 400000.00
        },
        {
            "branch": "New York",
            "region": "East",
            "sales": 468745.37,
            "target": 400000.00
        },
        {
            "branch": "Philadelphia",
            "region": "East",
            "sales": 337856.14,
            "target": 300000.00
        }
    ]
}

The "finances" array contains five JSON objects, each containing four key–value pairs. An array is a list-like object (essentially a list of objects), so you can input an array to the filter function's first parameter.

To get objects for which region = 'East' AND sales exceeds target by more than 15%:

[[filter(WholeJSON.finances, x -> x.region == 'East' && percentageChange(x.sales, x.target) > 15)]]

This example uses dot notation for field reference. If preferred, use bracket notation instead:

[[filter(WholeJSON.finances, x -> x['region'] == 'East' && percentageChange(x['sales'], x['target']) > 15)]]

The filtered array contains one object:

{
    "finances": [
        {
            "branch": "New York",
            "region": "East",
            "sales": 468745.37,
            "target": 400000.00
        }
    ]
}

Here's how you might work with the filtered array to produce narrative text:

[[

filtData = filter(WholeJSON.finances, x -> x.region == 'East' && percentageChange(x.sales,x.target) > 15)

successfulBranches = map(filtData, x -> x.branch)

if(len(successfulBranches) == 0)
{In the East region, no branches exceeded their target by more than 15%.} 

elseif(len(successfulBranches) == 1)
{In the East region, only [[successfulBranches]] exceeded its target by more than 15%.}

else{In the East region, [[successfulBranches]] each exceeded their target by more than 15%.}

]]

The output text:

In the East region, only New York exceeded its target by more than 15%.

Tip

For a wider range of examples, see Filtering > Filtering a JSON array.