# Filter expressions
<a name="filter-expressions"></a>

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
<a name="filter-expression-guidelines-requirements"></a>

 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
<a name="creating-filter-expressions"></a>

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
<a name="filter-expression-structure"></a>

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
<a name="filter-expression-elements"></a>

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
<a name="filter-expression-examples"></a>

 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
<a name="item-recommendation-filter-examples"></a>

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
<a name="item-interaction-filter-examples"></a>

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
<a name="item-filter-examples"></a>

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
<a name="user-filter-examples"></a>

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
<a name="user-segment-filter-examples"></a>

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
<a name="action-recommendation-filter-examples"></a>

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
<a name="action-interaction-filter-examples"></a>

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
<a name="action-filter-examples"></a>

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
<a name="user-action-filter-examples"></a>

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
<a name="multiple-expression-example"></a>

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