Recommendation filters

Filters can apply additional logic on top of recommendation results served by the AI engine.

They are used in two situations:

• For filtering, to exclude or include items from a recommendation.
• For score boosting, to promote or demote matching items.

Filtering concerns all attributes of items that you declared to be filterable while configuring AI engine and also you can use static customer attributes such as city, name, birthdate, segmentations, and tags.

The acceptable format of the attributes include: string, integer, float, boolean, nested objects, and arrays.
The attribute names are case sensitive, however the filter values are not. So, the filter brand == "ABC" is equivalent to brand == "abc", but different than Brand == "ABC".

Filter limits

While building the filter conditions, remember about the limits.

Filter building methods

You can create a filter by using two filter wizards:

• Visual Builder - You can construct the filter conditions similarly to creating a segmentation in the Analytics module. The list below presents the features available in the wizard:
  • Creating separate filters and then defining conditional dependencies between them
  • A separate option for matching/not matching filter conditions
  • A separate option for defining formula of conditions
  • Lack of the elements: functions, take none and take all options (available in the IQL Query wizard)
  • The range of options available to build filter conditions and the form of building the conditions may restrict the scope of business applications
• IQL query - Advanced may construct a formula of the filter, which is similar to creating expressions. The list below presents the capabilities of the wizard:
  • Possibility to create filter conditions for advanced business applications
  • Building one formula involves all conditions and dependencies between them
  • Additional elements that visual builder lacks: functions, segmentations, tags, take all, and take none options

Visual builder

In the visual builder, you need to define the filters by:

• selecting one or more attributes
• describing the condition for the attribute using operators and their values
• defining the dependency between the filters by preparing a formula

Selecting attributes

1. An item feed is already chosen and filterable attributes have been defined.
2. From the dropdown list, select an attribute of an item (in this example, brand is the selected attribute).
   Result: The Operator button appears.

The category attribute

The category attribute allows for additional settings. Its structure represents the hierarchy of categories that the item belongs to (read more here).
It allows you to define what part of the category should be taken into account by the filter. For a given category value, you can define the part using the level range.

• Positive values define how many subcategories from the right should be dropped.
  For example, if the category is “X > Y > Z” the level range is 1, the resulting category value is “X > Y” (Z is dropped).
• Negative values define how many subcategories from the left will be included.
  For example, if the category is “X > Y > Z” the level range is -1, the resulting category value is “X” (only X is included).

Describing conditions by operators

The next step is defining the conditions concerning the selected attribute by using operators. The list of operators contains:

• Is defined - If the selected attribute has any other value than null. For example, if a filter is set to “brand is defined”, the result contains only those items which have a specified brand (in the item feed).
• Equal - If the selected attribute has an exact value. For example, if a filter is set to “brand equals acme”, then the result contains items of Acme brand.
• Does not equal - It excludes a particular value of an attribute. For example, if a filter is set to “brand does not equal acme”, then the result contains all items except for the items of Acme brand.
• In - It checks whether the attribute is present in a selected array(s). For example, if a filter is set to “attribute.color in red, blue /array/”, then the result contains all items that are in the red and blue color.
• Less than - For example, if a filter is set to “price.value less than 50”, then the result contains items that are cheaper than 50 dollars (or other currency you use).
• Less than or equals - For example, if a filter is set to “attribute.size less than or equals 43”, then the result contains items of size 43 or less.
• More than - For example, if a filter is set to “attribute.quantity more than 10”, then the result contains those items whose quantity in your stock is greater than 10.
• More than or equals - For example, if a filter is set to “discountAmount more than or equals 20”, then the result contains items which are discounted by $20 or more.

Defining the values of operators

The examples presented in the Describing conditions by operators section, already contain the value of the operator. There are five types of the values:

• - Selected value - Out of the list of attributes sourced from the feed, you select one, like in the example: “brand equals acme”

• - Context selected value - In the case of similar items, visually similar items, cross-sell recommendations, you can display items of the same attribute as the item the customer is currently browsing. For example:

  

• - Customer context selected value - It allows you to use the customer attribute as the value of the item attribute. For example, you can filter displayed items by size, using the size value stored in a customer attribute.

• - An array - Allows to include items in a specific group, like in the example: “attribute.color in red, blue /array/” (available only for the In operator)

• - Number - Allows you to define the numerical value.

• - Aggregate - Allows you to select an aggregate as a value of the attribute from the item catalog.

  • The aggregate result must match the item attribute type defined in the feed. For example, if the attribute of an item is a number (price), you must select an aggregate that produces a number as the result.
  • You can use two various aggregates or expressions, or one expression and one aggregate. This limit applies per one recommendation campaign for filtering and boosting options. Multiple occurrences the same aggregate count as one towards the limit.
  • If the condition contains an aggregate whose result is null, this condition is skipped, unless it’s the only condition.
  • Using null as a condition in an aggregate is impossible. Using a null value as a string is not supported.

• - Expression - Allows you to select an expression as a value of the attribute from the item catalog.

  • The expression result must match the item attribute type defined in the feed. For example, if the expression of an item is a text string (favorite color of the customer), you must select the expression that produces a result which is a text string as well.
  • You can use two various expressions or aggregates, or one expression and one aggregate. This limit applies to one recommendation campaign for filtering and boosting options. Multiple occurrences the same expression count as one towards the limit.
  • If the condition contains an expression whose result is null, this condition is skipped, unless it’s the only condition.
  • Using null as a condition in an aggregate is impossible. Using a null value as a string is not supported.

• - Formula - it is created in the IQL Query builder. It allows you to define the advanced conditions, which can be done with the available operators and its value types. For example, if you want to display in the recommendation frame items which are discounted more than the currently viewed item.

  Click here to see the tutorial for the Formula example

You can change the type of the value operator by clicking this icon:

Defining filter conditions

You can define how filters coexist by defining the dependency between them by using logical operators. Below you can find exemplary configuration of filters.

IQL Query

The IQL Query wizard allows for a greater flexibility of creating the formula of the filter due to the wide range of elements and the possibility combine them using mathematical operators.

Elements of the formula

The filter formula can be built of the following elements:

• String (a sequence of characters)

• Number

• Boolean

• Array (a group of elements)

• Take All (include all items)

• Take None (include no items)

• Attributes:

  • Attribute - any parameter from the product feed
  • Item Context - a parameter of an item a customer is currently viewing
  • Customer Context - a customer attribute you can use as an item parameter value
  • Boolean

• Segmentations

• Profile Tags

• Functions

  Click to see the list of functions

  Function	Description	Syntax & Example of use
  ADD	Adds a constant to value of a selected variable	1. Syntax 2. Example of use In this example, the result includes items which are more expensive than the item the customer is currently browsing.
  AVG	Returns the average value of a selected attribute (for example, a shoe size)	1. Syntax 2. Example of use In this example, the result includes items that have the average size in relation to size of the item the customer is currently browsing.
  CATEGORY	Allows to define the categories to be included or excluded while filtering items	1. Syntax 2. Example of use In this example, the result includes items of exactly the same category as the item the customer is currently browsing. In this example, all items that belong exactly to Electronics > Phones and Smartphones > Smartphones, or in one of the subcategories of Electronics > Phones and Smartphones > Smartphones are included in the result. The filter also includes items that have the category defined in the additionalCategories parameter. Note: The number allows to manipulate the category value. A positive number defines how many subcategories from the right should be dropped. If in the second example 0 was replaced with 1, these would be the categories included in the filter: Electronics > Phones and Smartphones. A negative number defines how many subcategories from the left should be included. If in the second example 0 was replaced with -1, Electronics would be included in the filter.
  IF	Allows logical comparisons between values and defining actions to be performed when the condition is met or not.	1. Syntax 2. Example of use Explanation is available in the Examples of use section (example 3).
  MULTIPLY	Multiplies the value of a variable by a specified constant	1. Syntax 2. Example of use In this example, the result includes items whose final price is higher than the price of the item the customer is currently browsing multiplied by 0.8.
  MIN	This function returns the lowest value in a set of values	1. Syntax 2. Example of use In this example, the result includes items whose size is larger than the smallest size of the item the customer is currently browsing.
  MAX	This function returns the highest value in a set of values.	1. Syntax 2. Example of use In this example, the result includes items whose size is larger than the largest size of the item the customer is currently browsing.
  NOT	Negates a filter	1. Syntax 2. Example of use In this example, the result includes items of all colors except for pink.

The elements of the filter formula can be combined with the following mathematical operators:

• Apart from the symbols of mathematical operations such as addition, subtraction, multiplication, or division, you can use operators such as AND, HAS, IN, and OR.
• AND and OR have the same function in the formula as AND and OR in the Visual Builder (which is defining conditional dependencies between filters).
• The IN operator works the same in both wizards and allows you to check if a value is included in an array. The first argument is a value, and the second is an array.
• The HAS operator is available only in the IQL wizard. It allows you to check if an array includes a value. The first argument is an array, and the other is a value.
• The brackets () let you group elements, for example to dictate the order of mathematical operations.

Creating a formula in the wizard

Using the elements listed above and mathematical operators, you can create a filter formula that defines the conditions an item must meet in order to match the filter.

In the tutorial below, the condition of the filters states that the recommendation displays only items that are of the same brand as the item currently displayed by a customer and the number of available items in the stock is higher than 12. If an item doesn’t meet two conditions simultaneously, it won’t be included in the result of the filter.

Comparison between filters

The table below shows the same business application of the filter in the two filter wizards. The further parts of the article include the explanation of the similar examples as those presented in the table.

Visual Builder	IQL Query
Not applicable
Not applicable
Not applicable
Not applicable