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"
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])
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.
- If the request refers to a campaign (for example, in the “Get recommendations by campaign” endpoint), the campaign’s filters and the additional filters share the limit.
- If the request uses boosting strategies (for example, in the “Scoring be metric” endpoint), the boosting strategies and the filters share the limit.
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.
