Functions

Functions allow you to perform some additional operations when building the IQL query string.

CATEGORY

The CATEGORY function allows you to:

• access categories from the context
• access context attributes that are formatted as categories, but not named category (for example, a custom favoriteCategory attribute in a profile)
• manipulate category levels

The function takes two arguments:

• the source of the category value
• how many category levels you want to drop or include (0 does not drop any levels).
  Positive numbers drop levels from the bottom, negative numbers include from the top.

Example 1:
Accessing category from the item context and dropping one level from the bottom (right):

category == CATEGORY(context.category, 1)

If the context category is X > Y > Z the result of the function is the following filter:

category == "X > Y"

Example 2:
Accessing category from the item context including two levels from the top (left):

category == CATEGORY(context.category, -1)

If the context category is X > Y > Z the result of the function is the following filter:

category == "X"

Example 3:
Adding an OR statement and the additionalCategories attribute, no levels dropped:

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

Example 4:
Accessing a category saved as a custom profile attribute "favoriteCategory": "foo > bar":

category == CATEGORY(client.attributes.favoriteCategory, 0)

The resulting filter is:

category == "foo > bar"

Numeric functions

You can perform mathematical operations on item context and profile context attributes.

MIN

Returns the lowest value from an array.

attributeName >= MIN([])

Example:
In the following example, the context is a few items with a size.width attribute:

size.width >= MIN(context.size.width)

The resulting filter is:

size.width >= MIN([10.0,14.0,20.0])

which calculates into:

size.width >= 10.0

MAX

Returns the highest value from an array.

attributeName >= MAX([])

Example:
In the following example, the context is a few items with a size.width attribute:

size.width >= MAX(context.size.width)

The resulting filter is:

size.width >= MAX([10.0,14.0,20.0])

which calculates into:

size.width >= 20.0

AVG

Returns the average value of an array.

attributeName >= AVG([])

Example:
In the following example, the context is a few items with a size.width attribute:

size.width >= AVG(context.size.width)

The resulting filter is:

size.width >= AVG([10.0,14.0,20.0])

which calculates into:

size.width >= 14.666666666666666

ADD

Adds values.
The first argument is a context attribute or a number, the second attribute is a number.

attributeName == ADD(value,number)

Example 1:
In the following example, the context is one item with "size": 10:

size > ADD(context.size,5)

The resulting filter is:

size > ADD(10.0,5.0)

which evaluates to:

size > 15

MULTIPLY

Multiplies values.
The first argument is a context attribute or a number, the second attribute is a number.

attributeName == MULTIPLY(value,number)

Example:
In the following example, the context is one item with "price": 5:

price > MULTIPLY(context.price,0.7)

The resulting filter is:

price > MULTIPLY(5.0,0.7)

which evaluates to:

price > 3.5

Check if value is null

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

For example, the following filter matches items in which the winterPromotion has a non-null value:

winterPromotion IS DEFINED

You can also check contexts:

IF(context.thisAttributeDoesNotExist IS DEFINED, discount > 0, discount == 0)

Nesting functions

You can use function inside functions.
Example:

effectivePrice <= MULTIPLY(MIN(context.effectivePrice), 1.2)

In the above example:

1. (MIN(context.effectivePrice) gets the lowest value of an attribute from the context items.
2. MULTIPLY(...), 1.2 multiplies that lowest value by 1.2.
3. The resulting filter matches items whose effectivePrice is at least 20% higher than in the cheapest context item.

ALL/NONE

This special function lets include or exclude all items from the results.

• ALL - take all items
• NONE - take no items

This is especially useful in the IF statement.