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 customfavoriteCategory
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:
(MIN(context.effectivePrice)
gets the lowest value of an attribute from the context items.MULTIPLY(...), 1.2
multiplies that lowest value by1.2
.- 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 itemsNONE
- take no items
This is especially useful in the IF statement.