# Filtering recommendations and user segments
When getting recommendations with a domain recommender or custom campaign, you can filter results based on custom criteria. For example, you might not want to recommend products that a user has already purchased or recommend only items for a particular age group.
Similarly, with USER\$1SEGMENTATION recipes, you might not want to include certain types of users in user segments. By filtering your results, you can control the items that will be recommended to users or the users that will be included in user segments.
You can create, edit, delete, and apply filters using the Amazon Personalize console, the AWS Command Line Interface (AWS CLI), and the AWS SDKs.
+ For real-time recommendations, you apply a filter and specify any filter parameter values when you call the GetRecommendations, GetActionRecommendations, or GetPersonalizedRanking operations. You can also apply a filter when you get recommendations from a campaign or a recommender in the console.
When you get real-time item recommendations with personalized or related items recipes or use cases, you can specify a promotion in your request. A *promotion* uses a filter to define additional business rules that apply to a configurable subset of recommended items. For more information, see [Promoting items in real-time recommendations](promoting-items.md).
+ For batch workflows, you include any filter parameter values in your input JSON. Then you specify the filter's Amazon Resource Name (ARN) when you create a batch inference job or batch segment job. For more information, see [Filtering batch recommendations and user segments (custom resources)](filter-batch.md).
**Filter updates for new records**
For data that you import with the PutEvents or PutActionInteractions operations, Amazon Personalize updates any filters in the dataset group with the new data within seconds of import. For example, if your filter removes purchased items from recommendations, and you record a purchase event for a user with the PutEvents operation, this item would be removed from future recommendations for this user within seconds of recording the event.
For all other data imported in bulk or individually, Amazon Personalize updates any filters in the dataset group with the new data within 20 minutes from the last import.
**Topics**
+ [
# Filter expressions
](filter-expressions.md)
+ [
# Filtering real-time recommendations
](filter-real-time.md)
+ [
# Filtering batch recommendations and user segments (custom resources)
](filter-batch.md)
# 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.
You can use filter expressions to filter items, users, or actions from recommendations based on data from the following datasets:
+ **Item interactions**: You can use filter expressions to include or exclude items or users based on interactions data. For example, you can exclude items that a user has already clicked (for item recommendations), or include only users who have rated items (for the Item-Affinity recipe). For all recipe types, you can filter only based on event type. You can't filter based on other interaction metadata, such as contextual metadata. You can't use item interactions filters with the [Item-Attribute-Affinity recipe](item-attribute-affinity-recipe.md).
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](https://console.aws.amazon.com/servicequotas/). If you don't import item interactions for a user for three months, your filters no longer consider the user's historical data. To consider this data, you must import the user's entire event history again.
+ **Action interactions**: Use filter expressions to include or exclude actions that a user has interacted with based on event type. For example, you might exclude actions that a user has already taken. You can't filter based on other action interaction metadata.
Amazon Personalize considers up to 300 of the most recent action interactions per user per event type. This is an adjustable quota. You can request a quota increase using the [Service Quotas console](https://console.aws.amazon.com/servicequotas/).
+ **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. If your domain use case or custom recipe generates related items recommendations, such as the Similar-Items recipe or the *More Like X* domain use case, you can use filter expressions to include or exclude items based on the properties of the item you specify in your recommendation request.
+ **Users**: For *item* and *action* recommendations, if you have a Users dataset, you can exclude or include items or actions based on a `CurrentUser`. For personalized recommendations, popular items, and action recommendations, this is the user you are getting recommendations for. For related items, this an optional user you can specify in your recommendation request.
For *user segments*, you can use filter expressions to include or exclude users from user segments based on attributes, such as `Users.MEMBERSHIP_STATUS`.
+ **Actions**: Use filter expressions to include or exclude actions based on specific action conditions. Amazon Personalize automatically excludes actions based on `Action expiration timestamp` and `Repeat frequency` data. You can't create additional custom filters that filter based on this data.
For a complete list of filter expression elements, see [Filter expression elements](creating-filter-expressions.md#filter-expression-elements). For examples of filter expressions, see [Filter expression examples](filter-expression-examples.md).
**Topics**
+ [
# Guidelines and requirements
](filter-expression-guidelines-requirements.md)
+ [
# Filter expression structure and elements
](creating-filter-expressions.md)
+ [
# Filter expression examples
](filter-expression-examples.md)
# Guidelines and requirements
When creating a filter expression, note the following guidelines and requirements:
+ You can't use filters to include or exclude items based on unstructured textual item metadata such as product descriptions.
+ If you are filtering based on item or action interactions data, you can only filter based on event type. You can't filter based on other interaction metadata, such as contextual metadata.
+ Amazon Personalize ignores case only when matching event types.
+ You can't use Item Interaction and Item datasets in 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](multiple-expression-example.md).
+ You can't use Item interaction and Action datasets in one expression. To create a filter that filters by Item interaction and then Action datasets (or the opposite), you must chain two or more expressions together. For more information, see [Combining multiple expressions](multiple-expression-example.md).
+ You can't use item interactions filters with the [Item-Attribute-Affinity recipe](item-attribute-affinity-recipe.md).
+ 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 values `0` and `1`.
+ The maximum number of distinct dataset fields for a filter, either in one expression or across multiple expressions chained together, is **10**. The maximum number of distinct dataset fields across all filters in a dataset group is **20**.
+ You can apply a filter with the CurrentItem element only if your domain use case or custom recipe generates related items recommendations, such as the Similar-Items recipe or the *More Like X* domain use case.
+ You can't use placeholder parameters in a filter expression that uses the NOT\$1IN operator. Instead, use the IN operator and use the opposite Action. For example, use Include instead of Exclude (or the reverse).
+ You can't create filters that filter based on `Action expiration timestamp` and `Repeat frequency` data. Amazon Personalize automatically filters action recommendations based on this data.
# Filter expression structure and elements
This section includes information about the structure of filter expressions and their elements.
**Topics**
+ [
## Filter expression structure
](#filter-expression-structure)
+ [
## Filter expression elements
](#filter-expression-elements)
## Filter expression structure
The general structure of a filter expression is as follows:
```
EXCLUDE/INCLUDE ItemID/ActionID/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](filter-real-time.md#using-filter-expression-builder) in the console.
## 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* use `EXCLUDE` to remove all items that meet the filter criteria.
**ItemID/ActionID/UserID**
Use one of these elements after the `INCLUDE` or `EXCLUDE` element. The element you use depends on whether you are filtering items (for item recommendations), actions (for action recommendations), or users (for user segments).
**WHERE**
Use `WHERE` to check conditions for items, actions, or users. You must use the `WHERE` element after the `ItemID`, `ActionID`, or `UserID`.
**AND/OR**
To chain multiple conditions together within the same filter expression, use `AND` or `OR`. Conditions chained together using `AND` or `OR` 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 item recommendations based on the genres field in your Items dataset, you would use Items.genres in your filter expression.
**IF condition**
Use an `IF` condition *only* to check conditions for the `CurrentUser` and only *once* at the end of an expression. However, you can extend an `IF` condition using `AND`.
**CurrentUser.attribute**
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`.
**CurrentItem.attribute**
For only related items recipes and use cases, use `CurrentItem`.`attribute` to filter items based on an attribute of the item you specify in your request for related items recommendations. For example, `CurrentItem.GENRE` or `CurrentItem.PRICE`.
You can apply a filter with the CurrentItem element only if your domain use case or custom recipe generates related items recommendations, such as the Similar-Items recipe or the *More Like X* domain use case. The first time you create a filter with a `CurrentItem` element, filter creation can a few minutes. If you use AWS KMS for encryption, filter creation can take up to 15 minutes.
**IN/NOT IN**
Use `IN` or `NOT 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 =, <, <=, >, >=, and \$1= operators to test numerical data, including data passed in a placeholder parameter, for equality.
**Asterisk (\$1) character**
Use `*` to include or exclude interactions of all types. Use `*` *only* for filter expressions that use the `EVENT_TYPE` field of an `Interactions` dataset.
**Pipe separator**
Use the pipe separator (`|`) to chain multiple expressions together. For more information, see [Combining multiple expressions](multiple-expression-example.md).
**Parameters**
For expressions that use comparison operators or the `IN` operator, use the dollar sign (\$1) 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.
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-real-time.md#applying-filter-sdk).
# Filter expression examples
Use the filter expressions in the following sections to learn how to build your own filter expressions.
**Topics**
+ [
# Item recommendation filter expression examples
](item-recommendation-filter-examples.md)
+ [
# User segment filter expressions
](user-segment-filter-examples.md)
+ [
# Action recommendation filter expression examples
](action-recommendation-filter-examples.md)
+ [
# Combining multiple expressions
](multiple-expression-example.md)
# Item recommendation filter expression examples
The following filter expressions show how to filter item recommendations based on item interactions, item metadata, and user metadata. They are organized by data type.
**Topics**
+ [
## Item interaction data
](#item-interaction-filter-examples)
+ [
## Item data
](#item-filter-examples)
+ [
## User data
](#user-filter-examples)
## Item 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 includes only items that are cheaper than the current item (the item you specify in the request for related items recommendations), and created by the same studio as the current item. You can apply a filter with the CurrentItem element only if your domain use case or custom recipe generates related items recommendations.
```
INCLUDE ItemID WHERE Items.PRICE < CurrentItem.PRICE AND Items.GENRE IN CurrentItem.GENRE
```
The following expression excludes items based on multiple levels of categorical fields. It excludes items with a CATEGORY\$1L1 value of `shoe` that *do not* have a CATEGORY\$1L2 value of `boot`.
```
EXCLUDE ItemID WHERE Items.CATEGORY_L1 IN ("shoe") AND Items.CATEGORY_L2 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)
```
The following expression includes only items that are more expensive than the current item *and* created more recently than a timestamp (in Unix epoch time) that you specify. You might use this filter if you are getting related item recommendations, and want to apply some specific business rules based on price and a varying creation date.
```
INCLUDE ItemID WHERE Items.PRICE < CurrentItem.PRICE AND Items.CREATION_TIMESTAMP > $DATE
```
## 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 with `watch` for CATEGORY\$1L1 and `luxury` for CATEGORY\$1L2, if the current user's age is over `18`.
```
INCLUDE ItemID WHERE Items.CATEGORY_L1 IN ("watch") AND Items.CATEGORY_L2 IN ("luxury") IF CurrentUser.AGE > 18
```
# User segment filter expressions
The following filter expressions show how to filter user segments based on item 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
```
**Item 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 item interactions with an event type you specify when you get user segments.
```
EXCLUDE UserID WHERE Interactions.EVENT_TYPE IN ($EVENT_TYPE)
```
# Action recommendation filter expression examples
The following filter expression examples show how to filter actions based on action interactions data, action data. and user data. They are organized by data type.
**Topics**
+ [
## Action interaction data
](#action-interaction-filter-examples)
+ [
## Action data
](#action-filter-examples)
+ [
## User data
](#user-action-filter-examples)
## Action interaction data
The following filter expression includes only actions in recommendations that the user has interacted with, when those interactions have an event type that you specify when you get recommendations.
```
INCLUDE ActionID WHERE Action_Interactions.EVENT_TYPE IN ($EVENT_TYPE)
```
The following filter expression excludes actions that the user has not taken based on event type.
```
EXCLUDE ActionID WHERE Action_Interactions.EVENT_TYPE IN ("NOT_TAKEN")
```
## Action data
The following expression excludes actions based on a category or categories that you specify when you get recommendations using the `$CATEGORY` parameter.
```
EXCLUDE ActionID WHERE Actions.CATEGORY IN ($CATEGORY)
```
The following expression includes only actions with a value greater than a value that you specify when you get recommendations.
```
INCLUDE ActionID WHERE Actions.VALUE > ($VALUE)
```
## User data
The following expression includes only actions for premium members if the current user has a premium membership.
```
INCLUDE ActionID WHERE Action.MEMBERSHIP_LEVEL IN ("Premium") IF CurrentUser.MEMBERSHIP = $PREMIUM
```
The following expression excludes actions with a `VALUE` less than a value that you specify when you get recommendations if the current user is a premium member.
```
EXCLUDE ActionID WHERE Actions.VALUE < ($VALUE) IF CurrentUser.MEMBERSHIP = $PREMIUM
```
# Combining multiple expressions
To combine multiple expressions together you use a pipe separator (`|`). Use a combination of expressions when you want to use a single filter and filter on Items and Item interactions datasets, or Action and Action interactions datasets. Each expression is first evaluated independently and the result is either the union or the intersection of the two results. The following examples show how to create expressions for Items and Item interactions datasets, but the same rules apply when working with Actions and Action interactions.
**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 to `Exclude result from A or result from B`
+ `Include A | Include B` is equal to `Include 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 to `Include result from A - result from B`
+ `Include A | Include B | Exclude C | Exclude D` is equal to `Include (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")
```
# Filtering real-time recommendations
You can filter real-time recommendations with the Amazon Personalize console, AWS Command Line Interface (AWS CLI), or the AWS SDKs.
When you get personalized item recommendations or similar items, you can specify a promotion in your request. A *promotion* uses a filter to define additional business rules that apply to a configurable subset of recommended items. For more information, see [Promoting items in real-time recommendations](promoting-items.md).
**Topics**
+ [
## Filtering real-time recommendations (console)
](#filter-rt-console)
+ [
## Filtering real-time recommendations (AWS CLI)
](#filter-rt-cli)
+ [
## Filtering real-time recommendations (AWS SDKs)
](#filter-rt-sdk)
## Filtering real-time recommendations (console)
To filter real-time recommendations using the console, create a filter and then apply it to a recommendation request.
**Note**
To filter recommendations using a filter with parameters and a campaign deployed before November 10, 2020, you must redeploy the campaign by using the [UpdateCampaign](API_UpdateCampaign.md) operation or create a new campaign.
### Creating a filter (console)
To create a filter in the console, choose the dataset group that contains the campaign or recommender you want to use to get filtered recommendations. Then provide a filter name and a filter expression.
**To create a filter (console)**
1. Open the Amazon Personalize console at [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home) and sign into your account.
1. Choose the dataset group that contains the campaign or recommender that you want to use to get filtered recommendations.
1. In the navigation pane, choose **Filters** and then choose **Create new filter**. The **Create filter** page displays.
![\[Depicts the create filter page with filter name and expression fields.\]](http://docs.aws.amazon.com/personalize/latest/dg/images/create-filter-page.png)
1. For **Filter name**, enter a name for your filter. You will choose the filter by this name when you apply it to a recommendation request.
1. For **Expression**, choose either **Build expression** or **Add expression manually** and build or insert your expression:
+ To use the expression builder, choose **Build expression**. The expression builder provides structure, fields, and guidelines for building correctly formatted filter expressions. For more information, see [Using the filter expression builder](#using-filter-expression-builder).
+ To input your own expression, choose **Add expression manually**. For more information, see [Filter expression elements](creating-filter-expressions.md#filter-expression-elements).
1. Choose **Finish**. The filter's overview page shows the filter’s Amazon Resource Name (ARN), status, and full filter expression. To delete the filter, choose **Delete**. For information about finding and deleting filters after you have left the overview page, see [Deleting a filter (console)](#delete-filter-console).
![\[Depicts the filter details page with the filter's ARN and expression.\]](http://docs.aws.amazon.com/personalize/latest/dg/images/filter-details-page.png)
### Applying a filter (console)
To apply a filter, in **Test recommender** (for recommenders) or **Test campaign results** (for custom campaigns), choose the filter and enter any filter parameter values. Then get recommendations for a user.
**Important**
For filter expressions that use an `INCLUDE` element, you must provide values for all parameters that are defined in the expression. For filters with expressions that use an `EXCLUDE` element, you can omit the `filter-values`. In this case, Amazon Personalize doesn't use that portion of the expression to filter recommendations.
**To apply a filter (console)**
1. Open the Amazon Personalize console at [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home) and sign into your account.
1. Choose the dataset group that contains the campaign or recommender that you want to use to get filtered recommendations.
1. Depending on your dataset group type or resource type, do either of the following:
1. For a Domain dataset group, in the navigation pane choose **Recommenders**.
1. For a Custom dataset group or custom resources, in the navigation pane choose **Custom resources** then **Campaigns**.
1. On the **Recommenders** or **Campaigns** page, choose the target recommender or campaign.
1. For comparison, start by getting recommendations without applying a filter. Under **Test recommender** / **Test campaign results**, enter the ID of a user that you want to get recommendations for, or the ID of the item for related items, and choose **Get recommendations**. A table containing the top recommendations appears.
![\[Depicts recommendation results without applying a filter.\]](http://docs.aws.amazon.com/personalize/latest/dg/images/Recommendations_no-filter.PNG)
1. From the **Filter name** menu, choose the filter that you created. If your filter has any placeholder parameters, the associated fields for each parameter appear.
1. If you're using a filter with placeholder parameters, for each parameter, enter the value to set the filter criteria. To use multiple values for one parameter, separate each value with a comma.
1. Using the same `User ID` or `Item ID` as in the earlier step, choose **Get recommendations**. The recommendations table appears.
![\[Depicts recommendation results with a filter applied.\]](http://docs.aws.amazon.com/personalize/latest/dg/images/Recommendations_filter.png)
For example, if the user already bought a recommended item, the filter removes it from the recommendation list. In this example, items 2657, 2985 were replaced by the most suitable items that the user didn't buy (items 2641 and 1573).
### Using the filter expression builder
The **Expression builder** on the **Create filter** page provides structure, fields, and guidelines for building correctly formatted filter.
![\[Depicts the fields of the expression builder on the create filter page.\]](http://docs.aws.amazon.com/personalize/latest/dg/images/expression-builder-empty.png)
To build a filter expression:
+ Use the **Type**, **Action**, **Property**, **Operator**, and **Value** fields to create an expression.
For the **Value**, enter a fixed value or, to set filter criteria when you get recommendations, enter *\$1* \$1 a parameter name. For example, `$GENRES`. When you get recommendations, you'll supply the value or values to filter by. In this example, you would provide a genre or list of genres when you get recommendations.
Separate multiple non-parameter values with a comma. You cannot add comma-separated parameters to a filter.
**Note**
After you choose a **Property** (in `dataset.field` format), the **Property** value for any succeeding rows chained by `AND` or `OR` conditions must use the same `dataset`.
+ Use the **\$1** and **X** buttons to add or delete a row from your expression. You can't delete the first row.
+ For new rows, use the `AND`, `IF`, or `OR` operators on the **AND** menu to create a chain of conditions.
For `IF` conditions:
+ Each expression can contain only one `IF` item. If you remove an IF condition, the Expression builder removes any `AND` conditions following it.
+ You can use `IF` conditions only for expressions that filter by the `CurrentUser`.
+ Choose the **Add expression** button to add an additional filter expression for more precise filtering. Each expression is first evaluated independently and the result is a union of the two results.
**Note**
To create a filter that uses both Item and Item interaction datasets, or Action and Action interactions datasets, you *must* use multiple expressions.
#### Expression builder example
The following example shows how to build a filter that excludes items with a genre that you specify when you get recommendations (note the \$1GENRES placeholder parameter). The filter also excludes items with a `DOWNLOAD_COUNT` of more than `200`, but only if the current user's age is greater than `17`.
![\[Shows how to use expression builder to build an example filter expression.\]](http://docs.aws.amazon.com/personalize/latest/dg/images/create-filter-expression-builder.png)
### Deleting a filter (console)
Deleting a filter removes the filter from the list of filters for a dataset group.
**Important**
You can't delete a filter while a batch inference job is in progress.
**To delete a filter (console)**
1. Open the Amazon Personalize console at [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home) and sign into your account.
1. From the **Dataset groups** list, choose the dataset group that contains the filter that you want to delete.
1. In the navigation pane, choose **Filters**.
1. From the list of filters, choose the filter that you want to delete and choose **View Details**. The filter details page appears.
1. Choose **Delete** and confirm the deletion in the confirmation dialog box.
## Filtering real-time recommendations (AWS CLI)
To filter recommendations using the AWS CLI, you create a filter and then apply it by specifying the filter ARN in a [GetRecommendations](API_RS_GetRecommendations.md) or [GetPersonalizedRanking](API_RS_GetPersonalizedRanking.md) request.
**Important**
To filter recommendations using a filter with parameters and a campaign you deployed before November 10, 2020, you must re-deploy the campaign by using the [UpdateCampaign](API_UpdateCampaign.md) call or create a new campaign.
### Creating a filter (AWS CLI)
Use the following `create-filter` operation to create a filter and specify the filter expression.
Replace the `Filter name` with the name of the filter, and the `Dataset group ARN` with the Amazon Resource Name (ARN) of the dataset group. Replace the sample `filter-expression` with your own filter expression.
```
aws personalize create-filter \
--name Filter name \
--dataset-group-arn dataset group arn \
--filter-expression "EXCLUDE ItemID WHERE Items.CATEGORY IN (\"$CATEGORY\")"
```
If successful, the filter ARN is displayed. Record it for later use. To verify that the filter is active, use the [DescribeFilter](API_DescribeFilter.md) operation before you use the filter.
For more information about the API, see [CreateFilter](API_CreateFilter.md). For more information about filter expressions, including examples, see [Filter expression structure and elements](creating-filter-expressions.md).
### Applying a filter (AWS CLI)
When you use the `get-recommendations`, `get-action-recommendations` or `get-personalized-ranking` operations, you apply a filter by passing the `filter-arn` and any filter values as parameters.
The following is an example of the `get-recommendations` operation. Replace `Campaign ARN` with the Amazon Resource Name (ARN) of your campaign `User ID` with the ID of the user that you are getting recommendations for, and `Filter ARN` with the ARN of your filter. If you're getting recommendations from a recommender instead of a campaign, use `recommender-arn` instead of `--campaign-arn` and provide the ARN for the recommender.
If your expression has any parameters, include the `filter-values` object. For each parameter in your filter expression, provide the parameter name (case sensitive) and the values. For example, if your filter expression has a `$GENRE` parameter, provide *"GENRE"* as the key, and a genre or genres, such as `"Comedy"`, as the value. Separate multiple values with a comma. For example, `"\"comedy\",\"drama\",\"horror"\"`.
**Important**
For filter expressions that use an `INCLUDE` element to include items, you must provide values for all parameters that are defined in the expression. For filters with expressions that use an `EXCLUDE` element to exclude items, you can omit the `filter-values`. In this case, Amazon Personalize doesn't use that portion of the expression to filter recommendations.
```
aws personalize-runtime get-recommendations \
--campaign-arn Campaign ARN \
--user-id User ID \
--filter-arn Filter ARN \
--filter-values '{
"Parameter name": "\"value\"",
"Parameter name": "\"value1\",\"value2\",\"value3\""
}'
```
### Deleting a filter (AWS CLI)
Use the following `delete-filter` operation to delete a filter. Replace `filter ARN` with the ARN of the filter.
```
aws personalize delete-filter --filter-arn Filter ARN
```
## Filtering real-time recommendations (AWS SDKs)
To filter recommendations using the AWS SDKs, you create a filter and then apply it by specifying the filter ARN in a [GetRecommendations](API_RS_GetRecommendations.md) or [GetPersonalizedRanking](API_RS_GetPersonalizedRanking.md) request.
**Important**
To filter recommendations using a filter with parameters and a campaign you deployed before November 10, 2020, you must re-deploy the campaign by using the [UpdateCampaign](API_UpdateCampaign.md) call or create a new campaign.
### Creating a filter (AWS SDKs)
Create a new filter with the [CreateFilter](API_CreateFilter.md) operation. The following code shows how to create a filter. Specify the filter name, Amazon Resource Name (ARN) of your dataset group, and provide your filter expression.
------
#### [ SDK for Python (Boto3) ]
```
import boto3
personalize = boto3.client('personalize')
response = personalize.create_filter(
name = 'Filter Name',
datasetGroupArn = 'Dataset Group ARN',
filterExpression = 'EXCLUDE ItemID WHERE Items.CATEGORY IN ($CATEGORY)'
)
filter_arn = response["filterArn"]
print("Filter ARN: " + filter_arn)
```
------
#### [ SDK for Java 2.x ]
```
public static String createFilter(PersonalizeClient personalizeClient,
String filterName,
String datasetGroupArn,
String filterExpression) {
try {
CreateFilterRequest request = CreateFilterRequest.builder()
.name(filterName)
.datasetGroupArn(datasetGroupArn)
.filterExpression(filterExpression)
.build();
return personalizeClient.createFilter(request).filterArn();
}
catch(PersonalizeException e) {
System.err.println(e.awsErrorDetails().errorMessage());
System.exit(1);
}
return "";
}
```
------
#### [ SDK for JavaScript v3 ]
```
// Get service clients module and commands using ES6 syntax.
import { CreateFilterCommand } from "@aws-sdk/client-personalize";
import { personalizeClient } from "./libs/personalizeClients.js";
// Or, create the client here.
// const personalizeClient = new PersonalizeClient({ region: "REGION"});
// Set the filter's parameters.
export const createFilterParam = {
datasetGroupArn: "DATASET_GROUP_ARN" /* required */,
name: "NAME" /* required */,
filterExpression: "FILTER_EXPRESSION" /*required */,
};
export const run = async () => {
try {
const response = await personalizeClient.send(
new CreateFilterCommand(createFilterParam),
);
console.log("Success", response);
return response; // For unit tests.
} catch (err) {
console.log("Error", err);
}
};
run();
```
------
Record the filter ARN for later use. To verify that the filter is active, use the [DescribeFilter](API_DescribeFilter.md) operation before using the filter. For more information about the API, see [CreateFilter](API_CreateFilter.md). For more information about filter expressions, including examples, see [Filter expression structure and elements](creating-filter-expressions.md).
### Applying a filter (AWS SDKs)
When you use the GetRecommendations, GetActionRecommendations, or GetPersonalizedRanking operations, apply a filter by passing a `filterArn` and any filter values as parameters.
The following code shows how to get filtered Amazon Personalize item recommendations for a user. Specify the ID of the user you want to get recommendations for, the Amazon Resource Name (ARN) of your campaign, and the ARN of your filter. If you're getting recommendations from a recommender instead of a campaign, use `recommenderArn` instead of `campaignArn` and provide the ARN for the recommender.
For `filterValues`, for each optional parameter in your filter expression, provide the parameter name (case sensitive) and the value or values. For example, if your filter expression has a `$GENRES` parameter, provide *"GENRES"* as the key, and a genre or genres, such as `"\"Comedy"\"`, as the value. For multiple values, separate each value with a comma. For example, `"\"comedy\",\"drama\",\"horror\""`.
**Important**
For filter expressions that use an `INCLUDE` element to include items, you must provide values for all parameters that are defined in the expression. For filters with expressions that use an `EXCLUDE` element to exclude items, you can omit the `filter-values`. In this case, Amazon Personalize doesn't use that portion of the expression to filter recommendations.
------
#### [ SDK for Python (Boto3) ]
```
import boto3
personalize_runtime = boto3.client("personalize-runtime")
response = personalize_runtime.get_recommendations(
campaignArn = "Campaign ARN",
userId = "User ID",
filterArn = "Filter ARN",
filterValues = {
"Parameter name": "\"value1\"",
"Parameter name": "\"value1\",\"value2\",\"value3\""
....
}
)
```
------
#### [ SDK for Java 2.x ]
The following example uses two parameters, one with two values and one with one value. Depending on your filter expression, modify the code to add or remove parameterName and parameterValue fields.
```
public static void getFilteredRecs(PersonalizeRuntimeClient personalizeRuntimeClient,
String campaignArn,
String userId,
String filterArn,
String parameter1Name,
String parameter1Value1,
String parameter1Value2,
String parameter2Name,
String parameter2Value){
try {
Map filterValues = new HashMap<>();
filterValues.put(parameter1Name, String.format("\"%1$s\",\"%2$s\"",
parameter1Value1, parameter1Value2));
filterValues.put(parameter2Name, String.format("\"%1$s\"",
parameter2Value));
GetRecommendationsRequest recommendationsRequest = GetRecommendationsRequest.builder()
.campaignArn(campaignArn)
.numResults(20)
.userId(userId)
.filterArn(filterArn)
.filterValues(filterValues)
.build();
GetRecommendationsResponse recommendationsResponse = personalizeRuntimeClient.getRecommendations(recommendationsRequest);
List items = recommendationsResponse.itemList();
for (PredictedItem item: items) {
System.out.println("Item Id is : "+item.itemId());
System.out.println("Item score is : "+item.score());
}
} catch (PersonalizeRuntimeException e) {
System.err.println(e.awsErrorDetails().errorMessage());
System.exit(1);
}
}
```
------
#### [ SDK for JavaScript v3 ]
```
// Get service clients module and commands using ES6 syntax.
import { GetRecommendationsCommand } from "@aws-sdk/client-personalize-runtime";
import { personalizeRuntimeClient } from "./libs/personalizeClients.js";
// Or, create the client here:
// const personalizeRuntimeClient = new PersonalizeRuntimeClient({ region: "REGION"});
// Set recommendation request parameters.
export const getRecommendationsParam = {
campaignArn: "CAMPAIGN_ARN" /* required */,
userId: "USER_ID" /* required */,
numResults: 15 /* optional */,
filterArn: "FILTER_ARN" /* required to filter recommendations */,
filterValues: {
PROPERTY:
'"VALUE"' /* Only required if your filter has a placeholder parameter */,
},
};
export const run = async () => {
try {
const response = await personalizeRuntimeClient.send(
new GetRecommendationsCommand(getRecommendationsParam),
);
console.log("Success!", response);
return response; // For unit tests.
} catch (err) {
console.log("Error", err);
}
};
run();
```
------
### Deleting a filter (AWS Python SDK)
Use the following `delete_filter` method to delete a filter. Replace `filter ARN` with the ARN of the filter.
```
import boto3
personalize = boto3.client("personalize")
response = personalize.delete_filter(
filterArn = "filter ARN"
)
```
# Filtering batch recommendations and user segments (custom resources)
Filtering batch recommendations and user segments works nearly the same as filtering real-time recommendations. It follows the same workflow described in [Getting batch item recommendations](getting-batch-recommendations.md) or [Getting batch user segments](getting-user-segments.md). To filter batch recommendations or user segments, you do the following:
1. Create a filter just like you would for real-time recommendations. For more information, see [Filtering real-time recommendations](filter-real-time.md).
1. Prepare your input data and upload it to Amazon S3 as described in [Preparing input data for batch recommendations](batch-data-upload.md) or [Preparing input data for user segments](prepare-input-data-user-segment.md). If your filter uses placeholder parameters, you must add an additional `filterValues` object. For more information, see [Providing filter values in your input JSON](#providing-filter-values). If your filter doesn't use placeholder parameters, your input data can follow the examples in [Batch inference job input and output JSON examples](batch-data-upload.md#batch-inference-job-json-examples) [Batch segment job input and output JSON examples](prepare-input-data-user-segment.md#batch-segment-job-json-examples)
1. Create a separate location for your output data, either a folder or a different Amazon S3 bucket.
1. Create a [batch inference job](creating-batch-inference-job.md) or a [batch segment job](creating-batch-seg-job.md). When you create the job, specify the Amazon Resource Name (ARN) of your filter.
1. When the batch inference or batch segment job is complete, retrieve the recommendations or user segments from your output location in Amazon S3.
**Topics**
+ [
## Providing filter values in your input JSON
](#providing-filter-values)
+ [
## Filtering batch workflows (console)
](#filter-batch-recommendations-console)
+ [
## Filtering batch workflows (AWS SDKs)
](#filter-batch-recommendations-sdk)
## Providing filter values in your input JSON
For filters with placeholder parameters, such as `$GENRE`, you must provide the values for the parameters in a `filterValues` object in your input JSON. For a `filterValues` object, each key is a parameter name. Each value is the criteria that you are passing as a parameter. Surround each value with escaped quotes: `"filterValues":{"GENRES":"\"drama\""}`. For multiple values, separate each value with a comma: `"filterValues":{"GENRES":"\"horror\",\"comedy\",\"drama\""}`
**Batch inference job input JSON example**
The following is an example of the first few lines of a JSON input file for a *batch inference job*. The example includes the `filterValues` object. The `GENRES` key corresponds to a `$GENRES` placeholder in the filter expression. The job in this example uses the User-Personalization recipe. For RELATED\$1ITEMS recipes, provide an itemId instead of the userId. For PERSONALIZED\$1RANKING recipes provide the userID and an itemList.
```
{"userId": "5","filterValues":{"GENRES":"\"horror\",\"comedy\",\"drama\""}}
{"userId": "3","filterValues":{"GENRES":"\"horror\",\"comedy\""}}
{"userId": "34","filterValues":{"GENRES":"\"drama\""}}
```
For more examples of batch inference job input data by recipe see [Batch inference job input and output JSON examples](batch-data-upload.md#batch-inference-job-json-examples). You can use these examples as a starting point and add the `filterValues` object from the above example.
**Batch segment job input JSON example**
The following is an example of the first few lines of a JSON input file with filter values for a *batch segment job*. The `GENRES` key corresponds to a `$GENRES` placeholder in the filter expression.
```
{"itemAttributes": "ITEMS.genres = \"Comedy\" AND ITEMS.genres = \"Action\"","filterValues":{"COUNTRY":"\"Japan\""}}
{"itemAttributes": "ITEMS.genres = \"Horror\"","filterValues":{"COUNTRY":"\"United States\"\""}}
{"itemAttributes": "ITEMS.genres = \"Action\" AND ITEMS.genres = \"Adventure\"","filterValues":{"COUNTRY":"\"England\""}}
```
For more examples of batch inference job input data by recipe see [Batch segment job input and output JSON examples](prepare-input-data-user-segment.md#batch-segment-job-json-examples). You can use these examples as a starting point and add the `filterValues` object from the above example.
## Filtering batch workflows (console)
To filter batch workflows with the Amazon Personalize console, you create a filter and then you create a batch inference job or batch segment job and choose the filter. For complete step by step instructions, see [Creating a batch inference job (console)](creating-batch-inference-job.md#batch-console) and [Creating a batch segment job (console)](creating-batch-seg-job.md#batch-segment-console).
## Filtering batch workflows (AWS SDKs)
To filter batch recommendations with the AWS SDKs, create a filter and include the `FilterArn` parameter in the [CreateBatchInferenceJob](API_CreateBatchInferenceJob.md) or [CreateBatchSegmentJob](API_CreateBatchSegmentJob.md) request.
The following code shows how to create a batch inference job with a filter using the AWS SDK for Python (Boto3). We recommend using a different location for your output data (either a folder or a different Amazon S3 bucket). For complete explanation of all fields, see see [Creating a batch inference job (AWS SDKs)](creating-batch-inference-job.md#batch-sdk).
```
import boto3
personalize = boto3.client("personalize")
personalize_rec.create_batch_inference_job (
solutionVersionArn = "Solution version ARN",
jobName = "Batch job name",
roleArn = "IAM role ARN",
filterArn = "Filter ARN",
jobInput =
{"s3DataSource": {"path": "S3 input path"}},
jobOutput =
{"S3DataDestination": {"path": "S3 output path"}}
)
```