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 client who 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 attribute is higher than the average price attribute of multiple context items:
price > AVG(context.price)
If the context items’ prices are 10.49, 1.99, and 62.99, the result is the following filter:
price > 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”.
Client context
When the context is a client, you can use attributes, tags, segmentations, expressions, and aggregates as filter values.
Limits
In one request, you can use:
- up to 20 client 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.
Client attributes
In the following example, the brand of the item must be the same as the client’s favoriteBrand attribute:
brand == client.attributes.favoriteBrand
If the favoriteBrand attribute has the value "abcd", the result is the following filter:
brand == "abcd"
Client tags
In the following example, the tag "vip" must exist in the client’s tags:
"tag" IN client.tags
Example:
A client 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
Client segmentations
You can check if a client belongs to a segmentation.
The segmentation is identified by its UUID and calculated at the time of the request.
client.segmentations CONTAINS <segmentation_uuid>
Example:
A client belongs to segmentation 39d39ad1-6d7b-4401-b067-998bf7d56d9f.
When you create the following IF statement:
IF(client.segmentations CONTAINS "39d39ad1-6d7b-4401-b067-998bf7d56d9f", discount > 0, discount == 0)
it evaluates to:
discount > 0
Client expressions
You can access the result of an expression calculated for the context customer.
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 client.
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.
Client aggregates
You can access the result of an aggregate calculated for the context customer.
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 client.
If you create the following filter:
price < client.aggregates.08dfe176-2a37-3234-bf4f-3fa9b3b309bc
it evaluates to:
price < 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.
