Filters

The simplest possible IQL query consists of a single item filter. The filter returns true (matched) or false (not matched).

Elements of a filter

An item filter has three elements:

  • A variable, which is an item attribute based on which you are filtering.
  • An operator which defines how the attribute’s value is compared with the filter value.
  • A filter value to compare the attribute with.
    This value can be a constant or inserted dynamically from a context.
    size     ==     10
    ^        ^      ^
variable  operator  filterValue
Important:

In POST request to APIs, the quotation marks around the filterValue must be escaped, for example:

{
    "filter": "color == \"red\"",
    ...
}

Data sources for filters

An item feed is the source for searches and recommendations. The feed is generated from a catalog in Synerise or an external XML source.

An item feed is indexed for the purpose of search and recommendation queries. In certain situations, the two indexes work differently. Those situations are described in this guide.

Note: The indexes are updated periodically. An item that was recently added to the item feed is not immediately available in search/recommendation queries.

To learn more about configuring the item feed, see AI Engine Configuration.

Item attributes

An attribute name is used as a variable, and its value is compared to a filter value. For example, the following filter is true when an item’s brand attribute is abcd:

brand == "abcd"

Variables are case-sensitive, but filter values are not.
For example, the filter brand == "ABCD" is the same as brand == "abcd", but Brand == "abcd" filters only by an attribute named Brand, not brand.

Important:
  • In search requests, items can be filtered only by attributes which were defined as filterable when configuring the search index.
  • In recommendation requests, items can be filtered only by attributes which were defined as filterable when configuring the AI model.

Attributes with the following data type can be set as filterable:

type example(s)
string "foo"
boolean true;false
numeric 12; 12.34
attributes in nested objects {"object":{"attr1":"value1","attr2":"value2"}}
array of strings, numerics

Arrays must be type-consistent. If different data types (for example, strings and numbers) are included in one array, a filter may not work correctly.		 ["foo","bar"]
[12,45]
[12.34,53.18]

Example items

For the purpose of filter examples in this section, the following items are used: 

[
    {
        "itemId": "s1",
        "brand": "Abcd",
        "size": {
            "width": 10,
            "height": 20
        },
        "available": true,
        "tags": ["New", "Winter sale"]
        "promoted": "T",
        "price": {
            "value": 129.99
        },
        "winterPromotion": true,
        "category": "X > Y > Z",
        "additionalCategories": ["hiking", "warm", "L > M > N"]
    },
    {
        "itemId": "m1",
        "brand": "Efgh",
        "size": {
            "width": 5,
            "height": 17
        },
        "available": true,
        "tags": ["Winter sale"],
        "price": {
            "value": 249.99
        },
        "category": "X > Y > V"
    }
]

Top level attributes

In order to access an attribute from the root level of the item’s object, use the following syntax:

attributeName == filterValue

For example, brand == "Abcd"

Nested attributes

To access a nested value, use dot notation:

objectName.attributeName == filterValue

For example, size.width == 5

Indexing attributes in arrays (recommendations only)

When attributes are nested in arrays or arrays of objects, there is a difference in their indexing for the purposes of recommendation filters:

  • all values of a textual attribute are indexed
  • only the first value of a numeric attribute is indexed
Important: This logic does not affect context items. Context items are taken from the item feed, not the index.

Example 1:

Consider the following item: 

{
    "itemId": "s1",
    "tags": ["New", "Winter sale"],
    "sizes": [10, 15]
}

  • The tags variable contains the New and Winter sale values.
  • The sizes variable is 10, because only the first number in an array is indexed.

Example 2:

Consider the following item: 

{
    "itemId": "s1",
    "entries": [
        {
            "brand": "Abcd",
            "size": {
                "width": 10,
                "height": 20
            }
        },
        {
            "brand": "Xyz",
            "size": {
                "width": 15,
                "height": 25
            }
        }
    ]
}

  • The entries.brand variable contains the Abcd and Xyz values.
  • The entries.size.width variable is 10, because it’s the width defined in the first object of an array of objects which contain the numerical width attribute.

Category

category is a special type of attribute that describes a hierarchical structure.
It is saved in the following format:

"X > Y > Z"

where X is the top level category and Z is a leaf level category.

To filter items by category, use the following syntax:

category == CATEGORY("X > Y > Z", 0)

The above example finds items which are in the "X > Y > Z" category or its subcategories.

For an explanation of the 0 argument and advanced operations on categories, see the category function.

Additional categories

An item sometimes has a main category and a couple of additional categories to which it belongs, saved in the additionalCategories array.

When the system creates a category filter, it combines the values from category (string) and additionalCategories (array of strings), hiding that complexity from the user.

However, these categories are not combined in a context item. If you want to use the context’s additional categories in a filter, you must refer to them explicitly.

For example, the following filter checks an item’s category against the context’s category and additional categories:

(category == CATEGORY(context.category, 0)) OR (category == CATEGORY(context.additionalCategories, 0))

Metrics

In IQL, you can use some pre-defined metrics which exist in all workspaces. Metrics are considered item attributes.

The following example checks if the value of a metric for the tested item is more than 10.

extra.metrics.9 > 10

The following metrics are available:

Metric Attribute name
Number of page visits in last 7 days extra.metrics.9
Number of page visits in last 30 days extra.metrics.3
Number of item purchases yesterday extra.metrics.6
Number of item purchases in last 7 days extra.metrics.10
Number of item purchases in last 30 days extra.metrics.1
Number of item purchases on the same day last week extra.metrics.7
Total value of item sales in last 30 days, with tax extra.metrics.2

Operators

Operators are used to define the condition between the value of an attribute and the value to filter by.

Filtering against strings

Filter values are not case-sensitive. For example, brand == "abcd" is the same as brand == "ABCD".

equals

The == operator checks if the strings are identical.

brand == "Abcd"

not equals

The != operator checks if the strings are not identical.

brand != "Abcd"

Filtering against numbers

value comparisons

The <, <=, ==, >=, > operators compare the numbers.

size.width >= 10

value in range

The FROM / TO operator checks if a variable value is in a range between two values, including those values.

size.width FROM 6 TO 15
Tip:

An alternative way to build this filter is to use the AND operator:

size.width >= 6 AND size.width <= 15

Filtering against arrays

value in array

Example 1:

Checking if an item’s attribute value exists in an array:

brand IN ["Abcd", "Efgh"]
Tip:

An alternative way to build this filter is to use the OR operator:

brand == "Abcd" OR brand == "Efgh"

Example 2:

Checking if a value exists in an array, where the array is an item’s attribute (tags):

The IN operator checks if a filter value is included in an array-type attribute’s value.

"New" IN tags

The filter value can only be a string.
Note that in this case, the filter value is to the left of the operator, and the variable (item attribute) is on the right.

array has value

The HAS operator checks if an array includes a variable (this is an alternative to the IN operator).

[9, 15] HAS size.width
Tip:

An alternative way to build this filter is to use the OR operator:

size.width == 9 OR size.width == 15

value not in array

You can filter by checking if the value of a variable is NOT in an array.

brand NOT IN ["Abcd", "Efgh"]
Note:

This filter isn’t available in AI Search. Instead, you can use the ‘NOT’ operator with the ‘IN’ filter, for example:

NOT brand IN ["Abcd", "Efgh"]

Filtering against booleans

equals

The == operator checks if boolean values are identical.

available == true

not equals

The != operator checks if boolean values are not identical.

available != true

What happens if an attribute does not exist in the item?

If an attribute does not exist in the item, its value is null.

Check if an attribute exists

The IS DEFINED operator allows you to check if an attribute exists and has a non-null value.

winterPromotion IS DEFINED
😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

Close modal icon Placeholder alt for modal to satisfy link checker