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

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": 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": 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))

Operators

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

String operators

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"

value in array

The IN operator checks if the value of the variable is included in the array used as the filter value.

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

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

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

Numeric operators

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

value in array

The IN operator checks if the value of the variable is included in the array used as the filter value.

size.width IN [9, 15]
Tip:

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

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

Boolean operators

equals

The == operator checks if boolean values are identical.

available == true

not equals

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

available != true

Check if filter value is in array

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.

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