Context

Some recommendation and search requests allow you to use a context whose attributes will be used when building a filter. For example, you can recommend items in context of an item or items currently in the basket; or in context of the profile which created the basket.

This allows you to build dynamic filters instead of using hardcoded values, resulting increased personalization of your recommendations.

Item context

In the following example, the brand attribute of a context item is used to filter the results of a request to items which have the same brand:

brand == context.brand

If the value of the context item’s brand is abcd, the result is the following filter:

brand == "abcd"
Important: If the context consists of multiple items, the value of that context’s is an array of values from all the context items.

Example:
In the following example, the filter matches items whose brand attribute is in the array of context item brands:

brand IN context.brand

If the context items’ brands are abcd and efgh, the result is the following filter:

brand IN ["abcd","efgh"]

Example:
In the following example, the filter matches items whose price.value attribute is higher than the average price.value attribute of multiple context items:

price.value > AVG(context.price.value)

If the context items’ prices are 10.49, 1.99, and 62.99, the result is the following filter:

price.value > AVG([10.49, 1.99, 62.99])
Important:

The item context is taken from the item catalog instead of the index. Because of this:

  • attributes do not need to be configured as filterable to be used as context.
  • the context’s array-type attributes are not affected by the behavior described in “Indexing attributes in arrays”.

Profile context

When the context is a profile, you can use attributes, tags, segmentations, expressions, and aggregates as filter values.

Limits

In one request, you can use:

  • up to 20 profile attributes
  • 1 segmentation
  • 2 aggregates OR 2 expressions OR 1 expression and 1 aggregate

The limits apply to unique elements. For example, you can refer to the same segmentation a few times, but you can’t include 2 different segmentations.

Note:

Profile attributes

In the following example, the brand of the item must be the same as the profile’s favoriteBrand attribute:

brand == client.attributes.favoriteBrand 

If the favoriteBrand attribute has the value "abcd", the result is the following filter:

brand == "abcd"

If the attribute doesn’t exist in the profile, the filter is ignored.

Profile tags

In the following example, the tag "vip" must exist in the profile’s tags:

"tag" IN client.tags

Example:
A profile has the "vip" tag.
When you create the following IF statement:

IF("vip" IN client.tags, discount > 0, discount == 0)

it evaluates to:

discount > 0

Profile segmentations

You can check if a profile belongs to a segmentation.
The segmentation is identified by its UUID and calculated at the time of the request.

client.segmentations HAS <segmentation_uuid>

Example:
A profile belongs to segmentation 39d39ad1-6d7b-4401-b067-998bf7d56d9f.
When you create the following IF statement:

IF(client.segmentations HAS "39d39ad1-6d7b-4401-b067-998bf7d56d9f", discount > 0, discount == 0)

it evaluates to:

discount > 0

Profile expressions

You can access the result of an expression calculated for the context profile.
The expression is identified by UUID and calculated at the time of the request.

client.expressions.uuid

Example:
Expression 0abc195a-548e-460d-a904-1e285b8adb96 returns 15.0 for the context profile.
If you create the following filter:

discount > client.expressions.0abc195a-548e-460d-a904-1e285b8adb96

it evaluates to:

discount > 15.0

If the expression does not exist, its value in the filter is null.

Profile aggregates

You can access the result of an aggregate calculated for the context profile.
The aggregate is identified by UUID and calculated at the time of the request.

client.aggregates.uuid

Example:
Aggregate 08dfe176-2a37-3234-bf4f-3fa9b3b309bc returns 180.0 for the context profile.
If you create the following filter:

price.value < client.aggregates.08dfe176-2a37-3234-bf4f-3fa9b3b309bc

it evaluates to:

price.value < 180.0

If the aggregate does not exist, its value in the filter is null.

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

If an attribute does not exist in the context, its value becomes null == true and the filter which uses it becomes unprocessable. If that filter is part of a larger expression, it is ignored.

Example 1: The following filter matches NO ITEMS:

discount == context.thisAttributeDoesNotExist

Example 2: The following filter matches items whose discount == 0, because the other condition is unprocessable.

discount == 0 AND discount == context.thisAttributeDoesNotExist

Check if a value exists

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

The following filter uses an IF statement to check if an attribute exists and act accordingly:

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

The context attribute does not exist, so the discount == 0 filter is applied.

😕

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