Filtering Recommendations

To configure filters, you must use a properly formatted filter expression.

Filter expressions are composed of dataset and property identifiers in dataset.property format, along with logical operators, keywords, and values. For values, you can specify fixed values or add placeholder parameters, which allow you to 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

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 based on data from the following datasets:

  • Interactions: Use filter expressions to include or exclude items that a user has interacted with (for example, user events such as click or stream). When filtering, the number of interactions Amazon Personalize considers for a user depends on the max_user_history_length_percentile and min_user_history_length_percentile hyperparameters you defined before training.

  • Items: Use filter expressions to include or exclude items based on specific item conditions.

  • Users: Use filter expressions to include or exclude items based on specific CurrentUser conditions. If you have created a Users dataset, you can add CurrentUser to any expression regardless of the dataset that is being used in the expression.

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 Multiple Expressions Example.

Filter Expression Elements

Use the following elements to create filter expressions:

  • INCLUDE: Use INCLUDE to limit recommendations to only items that meet the filter criteria.

  • EXCLUDE: Use EXCLUDE to remove items that meet the filter criteria from recommendations.

  • ItemID: Use ItemID after the INCLUDE or EXCLUDE element.

  • WHERE: Use WHERE to check conditions for items. You must use the WHERE element after the ItemID.

  • AND/OR: Use AND or OR to chain multiple conditions together within the same filter expression. Conditions chained together using AND or OR can only affect properties of the dataset used in the first condition.

  • Dataset.property: Provide the dataset and the metadata property that you want to filter recommendations by in dataset.property format. For example, to filter based on the genres property in your Items dataset, you would use Items.genres in your filter expression.

  • IF: Use IF 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.

  • 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.

  • Use =, <, <=, >, >= operators to test numerical data for equality.

  • Use * to include or exclude interactions of all types. Use * only for filter expressions that use the EVENT_TYPE property of an Interactions dataset.

  • Use the pipe separator (|) to chain multiple expressions together. For more information, see Multiple Expressions Example.

  • For expressions that use = and IN operators, 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.

You define a parameter name when you add it to an expression. The parameter name does not have to match the property name. We recommend that you use a parameter name that is similar to the property name and easy to remember. You use the parameter name (case sensitive) when you apply the filter to recommendations requests.

Filter Expression Examples

Use the following examples to learn how to build your own filter expressions. They are organized by dataset type.

Interactions

The following expression excludes items based on an event type (such as click) 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 items that the user has interacted with in any way.

INCLUDE ItemID WHERE Interactions.EVENT_TYPE IN ("*")

Items

The following expression excludes items based on a category 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 genre that you specify when you get recommendations using the $GENRE parameter.

INCLUDE ItemID WHERE Items.GENRE IN ($GENRE)

Users

The following expression excludes items with a genre 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

Multiple Expressions Example

To filter by multiple datasets, chain multiple expressions together using a pipe separator (|). Each expression is first evaluated independently and the result is a union of the two results.

The following example includes two expressions. The first includes only items with a genre that you specify when you get recommendations using the $GENRE parameter. The second excludes items that the user has clicked or streamed. Recommendations will include only items with a genre that you specify when you get recommendations, but only items that have not have been clicked or streamed.

INCLUDE ItemID WHERE Items.GENRE IN ($GENRE) | EXCLUDE ItemID WHERE Interactions.EVENT_TYPE IN ("click", "stream")

Applying a Filter (AWS Python SDK)

When you use the get_recommendations or get_personalized_ranking methods, apply a filter by passing filterArn and any filter values as parameters.

The following is an example of the get_recommendations method. 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.

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.

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\""
      ....
    }
)

Filtering Batch Recommendations

Filtering batch recommendations works nearly the same as filtering real-time recommendations. To filter batch recommendations, you create a filter and then apply it to a CreateBatchInferenceJob operation or new batch inference job in the Amazon Personalize console. Amazon Personalize then filters the recommendations from the batch job’s output JSON file. For more information about batch inference jobs, see Getting Batch Recommendations (Amazon Personalize Console).

For filters with placeholder parameters, such as $GENRE, provide the values in a filterValues object in your input JSON. For a filterValues object, each key is a parameter name and each value is the criteria that you are passing as a parameter. For multiple values, separate each value with a comma. The following is an example of a JSON input file with filter values. The GENRES key corresponds to a $GENRES placeholder in the filter expression.

{"userId": "5","filterValues":{"GENRES":"\"horror\",\"comedy\",\"drama\""}}
{"userId": "3","filterValues":{"GENRES":"\"horror\",\"comedy\""}}
{"userId": "34","filterValues":{"GENRES":"\"drama\""}}

Filtering Batch Recommendations (Console)

  1. Use the console or the SDK to create a filter.

  2. When you create the batch recommendation job, on the Create batch inference job page, for Filter configuration - optional, Filter name, choose the filter.

\[Image NOT FOUND\]

Filtering Batch Recommendations (AWS SDK)

  1. Use the console or the SDK to create a filter.

  2. Include the FilterArn parameter in the CreateBatchInferenceJob request.

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"}}
)

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"
)