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"
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 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])
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”.

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.

Note:

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.

😕

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