Filter expressions
To configure filters, you must use a properly formatted filter expression. Filter expressions are
composed of dataset and field identifiers in
dataset
.field
format, along with logical
operators, keywords, and values. For values, you can specify fixed values
or add placeholder parameters set the filter criteria when you get
recommendations.
For a complete list of filter expression elements, see Filter expression elements. For examples of filter expressions, see Filter expression examples.
Amazon Personalize ignores case only when matching event types.
Creating filter expressions
The general structure of a filter expression is as follows:
EXCLUDE/INCLUDE ItemID/UserID WHERE
dataset type
.field
IN/NOT IN (value/parameter
)
You can either manually create filter expressions or get help with expression syntax and structure by using the Expression builder in the console. You can use filter expressions to filter items or users based on data from the following datasets:
-
Interactions: Use filter expressions to include or exclude items that a user has interacted with from recommendations (for example, user events such as click or stream). Or include or exclude users that have taken certain actions from user segments (interactions with certain event types). Interactions filters can't be used with the Item-Attribute-Affinity recipe.
Amazon Personalize considers up to 100 of the most recent interactions per user per event type. This is an adjustable quota. You can request a quota increase using the Service Quotas console
. -
Items: Use filter expressions to include or exclude items based on specific item conditions. You can't use filters to include or exclude items based on unstructured textual item metadata such as product descriptions.
-
Users: For item recommendations for users, use filter expressions to include or exclude items from recommendations based on properties of the user you are getting recommendations for (the
CurrentUser
). If you have a Users dataset, you can add anIF
condition to your expression to check conditions for theCurrentUser
regardless of the dataset that is being used in the expression.For user segments, use filter expressions to include or exclude users from user segments based on properties of users.
When creating a filter expression, note the following limitations:
-
You can't use filters to include or exclude items based on unstructured textual item metadata such as product descriptions.
-
You can't chain Interaction and Item datasets into one expression. To create a filter that filters by Interaction and then Item datasets (or the opposite), you must chain two or more expressions together. For more information, see Combining multiple expressions.
-
You can't create filter expressions that filter using values with a boolean type in your schema. To filter based on boolean values, use a schema with a field of type String and use the values
"True"
and"False"
in your data. Or you can use type int or long and values0
and1
. -
The maximum number of distinct dataset fields for a filter, either in one expression or across multiple expressions chained together, is 5. The maximum number of distinct dataset fields across all filters in a dataset group is 10.
Filter expression elements
Use the following elements to create filter expressions:
- INCLUDE or EXCLUDE
-
Use
INCLUDE
to limit recommendations to only items that meet the filter criteria OR useEXCLUDE
to remove all items that meet the filter criteria. - ItemID/UserId
-
Use
ItemID
after theINCLUDE
orEXCLUDE
element for filtering item recommendations. UseUserId
for filtering users from user segments. - WHERE
-
Use
WHERE
to check conditions for items or users. You must use theWHERE
element after theItemID
orUserID
. - AND/OR
-
To chain multiple conditions together within the same filter expression, use
AND
orOR
. Conditions chained together usingAND
orOR
can only affect fields of the dataset used in the first condition. - Dataset.field
-
Provide the dataset and the metadata field that you want to filter recommendations by in
dataset
.field
format. For example, to filter based on the genres field in your Items dataset, you would use Items.genres in your filter expression. You can't use filters to include or exclude items based on textual item metadata. - IF condition
-
Use an
IF
condition only to check conditions for theCurrentUser
and only once at the end of an expression. However, you can extend anIF
condition usingAND
. - CurrentUser.field
-
To filter item recommendations based on the user you are getting recommendations for, in only an IF condition, use
CurrentUser
and provide the user field. For example,CurrentUser.AGE
. - IN/NOT IN
-
Use
IN
orNOT IN
as comparison operators to filter based on matching (or not matching) one or more string values. Amazon Personalize filters only on exact strings. - Comparison operators
-
Use =, <, <=, >, >= operators to test numerical data, including data passed in a placeholder parameter, for equality.
- Asterisk (*) character
-
Use
*
to include or exclude interactions of all types. Use*
only for filter expressions that use theEVENT_TYPE
field of anInteractions
dataset. - Pipe separator
-
Use the pipe separator (
|
) to chain multiple expressions together. For more information, see Combining multiple expressions. - Parameters
-
For expressions that use comparison operators or the
IN
operator, use the dollar sign ($) and a parameter name to add a placeholder parameter as a value. For example,$GENRES
. For this example, when you get recommendations, you supply the genre or genres to filter by. For information on the number of parameters you can use, see Service quotas.Note You define a parameter name when you add it to an expression. The parameter name does not have to match the field name. We recommend that you use a parameter name that is similar to the field name and easy to remember. You use the parameter name (case sensitive) when you apply the filter to recommendations requests. For an example that shows how to apply a filter with placeholder parameters when using the AWS SDKS, see Applying a filter (AWS SDKs).
Filter expression examples
Use the filter expressions in the following sections to learn how to build your own filter expressions.
Item recommendation filter expressions
The following filter expressions show how to filter item recommendations based on interactions, item metadata, and user metadata. They are organized by data type.
Interaction data
The following expression excludes items based on an event type (such as click) or event types that
you specify when you get recommendations using the $EVENT_TYPE
parameter.
EXCLUDE ItemID WHERE Interactions.EVENT_TYPE IN ($EVENT_TYPE)
The following expression excludes items that a user clicked or streamed.
EXCLUDE ItemID WHERE Interactions.EVENT_TYPE IN ("click", "stream")
The following expression includes only items that the user has clicked.
INCLUDE ItemID WHERE Interactions.EVENT_TYPE IN ("click")
Item data
The following expression excludes items based on a category or categories that you specify when you
get recommendations using the $CATEGORY
parameter.
EXCLUDE ItemID WHERE Items.CATEGORY IN ($CATEGORY)
The following expression excludes items in the shoe
category that
do not have a description of boot
.
EXCLUDE ItemID WHERE Items.CATEGORY IN ("shoe") AND Items.DESCRIPTION NOT IN ("boot")
The following expression includes only items with a price less than or equal to the price that you specify when you get recommendations
using the $PRICE
parameter.
INCLUDE ItemID WHERE Items.PRICE <= $PRICE
The following expression includes only items that have been created earlier than a timestamp (in Unix epoch time) that you specify when you get recommendations.
INCLUDE ItemID WHERE Items.CREATION_TIMESTAMP < $DATE
The following expression includes only items with a genre or genres that you specify when you
get recommendations using the $GENRE
parameter.
INCLUDE ItemID WHERE Items.GENRE IN ($GENRE)
User data
The following expression excludes items with a genre or genres that you specify when you get
recommendations using the $GENRE
parameter, but only if the current user's
age is equal to the value that you specify when you get recommendations using the
$AGE
parameter.
EXCLUDE ItemID WHERE Items.GENRE IN ($GENRE) IF CurrentUser.AGE = $AGE
The following expression includes only items in the watch
category, with a
description of luxury
, if the current user's age is over 18
.
INCLUDE ItemID WHERE Items.CATEGORY IN ("watch") AND Items.DESCRIPTION IN ("luxury") IF CurrentUser.AGE > 18
User segment filter expressions
The following filter expressions show how to filter user segments based on interactions data and user metadata. They are organized by data type.
User data
The following filter expression includes only users with a membership status equal to the value that you specify when you get user segments.
INCLUDE UserID WHERE Users.MEMBERSHIP_STATUS IN ($MEMBERSHIP)
The following filter expression excludes users with an AGE
less than a value you specify when you get user segments.
EXCLUDE UserID WHERE Users.AGE < $AGE
Interaction data
The following filter expression includes only users who have clicked or rated items.
INCLUDE UserID WHERE Interactions.EVENT_TYPE IN ("click, rating")
The following filter expression excludes users from user segments who have interactions with an event type you specify when you get user segments.
EXCLUDE UserID WHERE Interactions.EVENT_TYPE IN ($EVENT_TYPE)
Combining multiple expressions
To combine multiple expressions together you use a pipe
separator (|
). Use a combination of expressions when you want to Items and Interactions datasets with one filter.
Each expression is first evaluated independently and the
result is either the union or the intersection of the two results.
Matching expressions example
If both expressions use EXCLUDE
or both expressions use INCLUDE
, the result is the union of the two results as follows (A and B are different expressions):
-
Exclude A | Exclude B
is equal toExclude result from A or result from B
-
Include A | Include B
is equal toInclude result from A or result from B
The following example shows how to combine two expressions that use INCLUDE
.
The first expression includes only items with a category or categories
that you specify when you get recommendations using the $CATEGORY
parameter.
The second expression includes items the user has marked as a favorite
.
Recommendations will include only items with the category you specify along with items that the user has
marked as a favorite.
INCLUDE ItemID WHERE Items.CATEGORY IN ($CATEGORY) | INCLUDE ItemID WHERE Interactions.EVENT_TYPE IN ("favorite")
INCLUDE and EXCLUDE example
If one or more expression uses INCLUDE
and one more expression uses
EXCLUDE
, the result is the subtraction of the EXCLUDE
expression result from the INCLUDE
expression result as follows (A, B, C, and
D are different expressions).
-
Include A | Exclude B
is equal toInclude result from A - result from B
-
Include A | Include B | Exclude C | Exclude D
is equal toInclude (A or B) - (C or D)
Expression order does not matter: If the EXCLUDE expression comes before the INCLUDE expression, the result is the same.
The following example shows how to combine an INCLUDE
expression and
a EXCLUDE
expression. The first expression includes only items with a genre or genres
that you specify when you get recommendations using the $GENRE
parameter.
The second expression excludes items that the user has clicked or streamed. Recommendations will
include only items with a genre that you specify that have not have been clicked or streamed.
INCLUDE ItemID WHERE Items.GENRE IN ($GENRE) | EXCLUDE ItemID WHERE Interactions.EVENT_TYPE IN ("click", "stream")