This is the documentation for Recommendations AI, Retail Search, and the new Retail console.

Filter recommendations

This page describes filtering results for Recommendations AI using product attributes.

You can filter prediction results by specifying a filter expression in predict requests. The filter expression is a logical expression that is evaluated for each product. The list of products in the response is narrowed down to products where the expression evaluates to true.

There are two versions of filtering for Recommendations AI:

  • Version 1: Uses manually created filter tags. Filter expressions are based on filter tags, which you must manually add to any products in your catalog that you plan to filter.

    The following filter expression example uses filter tags to specify products tagged as "Red" or "Blue", as well as the tag "New-Arrival", and are not tagged as "promotional":

    tag=("Red" OR "Blue") tag="New-Arrival" tag=(NOT "promotional")
    

    For more about using v1 filtering, see Use recommendation filters.

  • Version 2 (Public Preview): Uses product attributes. Filter expressions are based on product attributes. These can be predefined system attributes, such as categories and colors, or custom attributes you define, such as attributes.styles. When you set a product attribute as filterable, Recommendations AI can then automatically use those attributes as tags for recommendations filtering, instead of requiring that you manually add filter tags.

    The following filter expression example, like the one for version 1 filtering, also filters for any red or blue products set as "New-Arrival" and not set as promotional. However, this example filters using product attributes:

    colors: ANY("red", "blue") AND attributes.status: ANY("New-Arrival") AND NOT attributes.is_promotional: ANY("true")
    

If a model has both manually created tags and filterable product attributes, it can serve predict requests using either version of filtering. However, it's not possible to include both v1 filtering and v2 filtering expressions in the same predict request.

The sections in this how-to guide only apply to version 2 of filtering, which filters recommendations using product attributes.

Recommendations filtering limits

Each filterable attribute consumes some memory in each of your models. The following limits help prevent adverse effects on serving performance:

  • Up to 10 custom attributes can be set as filterable in your catalog.
  • Up to 100,000,000 filterable attribute values can be present in your catalog.

    The total number of attribute values in your catalog can be estimated by multiplying the number of products in your catalog by the number of filterable attributes.

    For example, if you have a catalog with 1,000 products and 3 attributes set as filterable, the total number of attribute values can be estimated as 3*1000=3000.

    If you are using version 1 recommendations filtering alongside version 2, the number of filter tags count towards your quota. Make sure that the number of filter tags added to the total number of attribute values is less than 100,000,000.

If you exceed the limits, the Retail API prevents you from setting additional attributes as filterable. If you need to exceed these limits, request a quota increase.

The total number of tags is computed during model training. If the total number exceeds the limit, model training fails. If more than 10 filterable custom attributes are found during model training, only 10 are used.

Recommendations AI filter expression syntax

The filter expression syntaxes for Retail Search and Recommendations AI are similar. However, the Recommendations AI has several limitations.

The Recommendations AI filter expression syntax can be summarized by the following EBNF:

  # A single expression or multiple expressions that are joined by "AND" or "OR".
  filter = expression, { " AND " | "OR", expression };

  # An expression can be prefixed with "-" or "NOT" to express a negation.
  expression = [ "-" | "NOT " ],
                    # A parenthesized expression
                    | "(", expression, ")"
                    # A simple expression applying to a textual field.
                    # Function "ANY" returns true if the field contains any of the literals.
                    ( textual_field, ":", "ANY", "(", literal, { ",", literal }, ")"

  # A literal is any double-quoted string. You must escape backslash (\) and
  # quote (") characters.
  literal = double-quoted string;

  textual_field = see the tables below;

Filter syntax restrictions

The following restrictions apply:

  • The depth of embedding AND and OR operators in parentheses is limited. The logical expressions in the filter must be in conjunctive normal form (CNF). The most complex supported logical expression can be an AND-connected list of clauses that only contain OR operators, such as: (... OR ... OR ...) AND (... OR ...) AND (... OR ...)
  • Expressions can be negated with the NOT keyword or with -. This only works with ANY()-expressions with a single argument that do not include inventory-related attributes.
  • availability-based restrictions must be on the top-level. They cannot be used as part of an OR-clause or a negation (NOT).
  • Because supported fields are textual only, less-than, greater-than, and range- check operations are not supported.
  • The maximum number of arguments of ANY() expressions is 100.
  • The maximum number of terms in an OR-clause is 10.
  • The maximum number of terms in the top-level AND-clause is 20.

The following table shows valid filter expression examples, as well as invalid examples and the reasons they are invalid.

Expression Valid Notes
colors: ANY("red", "green") Yes
NOT colors: ANY("red") Yes
NOT colors: ANY("red", green") No Negates an `ANY()` with more than one argument.
colors: ANY("red", "green") OR
categories: ANY(\"Phone > Android > Pixel\")
Yes
(colors: ANY("red") OR colors: ANY("green")) AND
categories: ANY(\"Phone > Android > Pixel\")
Yes
(colors: ANY("red") AND colors: ANY("green")) OR
categories: ANY(\"Phone > Android > Pixel\")
No Not in conjunctive normal form.
(colors: ANY("red")) AND (availability: ANY("IN_STOCK") Yes
(colors: ANY("red")) OR (availability: ANY("IN_STOCK")) No Combines availability in an OR expression with other conditions.

Inventory-related attribute filtering

Filtering on inventory-related attributes is based on the real-time state of your products.

IN_STOCK is the only availability attribute value supported by version 2 of recommendations filtering.

Inventory-related attributes can be used in AND-clauses, but not in OR-clauses.

Supported textual fields

Supported textual fields are summarized in the following table.

field description
"productId" The product ID (the last segment of Product.name).
"brands" The Product.brands.
"categories" The Product.categories.
"genders" The Audience.genders.
"ageGroups" The Audience.age_groups.
"colorFamilies" The ColorInfo.color_families.
"colors" The ColorInfo.colors.
"sizes" The Product.sizes.
"materials" The Product.materials.
"patterns" The Product.patterns.
"conditions" The Product.conditions.
"attributes.key" The textual custom attribute in Product object. Key can be any key in the Product.attributes map, if the attribute values are textual.

Filter recommendations results

To use version 2 of filtering for Recommendations AI:

  1. Turn on recommendations filtering for a model that will serve filtered recommendations.
  2. Turn on recommendations filtering for product attributes that you plan to filter on.
  3. Use filterable product attributes in predict requests.

For more about using v1 filtering, see Use recommendation filters.

Set recommendations filtering for a model

You can turn on filtering for Recommendations AI using the Retail console or the Models API resource.

From the console, you can create a new model that has recommendations filtering enabled. Updating this option for an existing model isn't available from the console.

Using the Models API resource, you can create a new model with recommendations filtering turned on or update this setting for an existing model using models.Patch.

Set filtering for a model using the console

Using the Retail console, select the Auto generate tags option during model creation to allow recommendation filtering for that model.

See Create models for instructions on creating a recommendation model using the console.

This setting can't be updated in the console for existing models. To update this setting for a model, use the models.Patch API method.

Set filtering for a model using the API

You can turn on recommendations filtering for a model using models.Create when creating a new model or models.Patch when updating an existing model.

To allow filtering, set the filteringOption field for your model. This field's allowed values are:

  • RECOMMENDATIONS_FILTERING_DISABLED (default): Filtering is turned off for the model.
  • RECOMMENDATIONS_FILTERING_ENABLED: Filtering is turned on for primary products.

The following curl example creates a new model that has recommendations filtering turned on.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
       'name': 'MODEL_NAME',
       'displayName': 'MODEL_DISPLAY_NAME',
       'type': 'home-page',
       'filteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED',
     }" \
     "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/models"

The following curl example updates the filtering option setting for an existing model.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
       'filteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED',
     }" \
     "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/models/MODEL_ID?updateMask=filteringOption"

Set attributes as filterable

To filter recommended products, turn on filtering for the product attributes that you will use in filter expressions. You can update this setting using the Retail console or using the Attributes API resource.

Do not make more attributes filterable than needed. There is a limit on the number of filterable attributes.

Set attributes as filterable using the console

You can set an attribute as filterable Controls page in the Google Cloud console.

  1. Go to the Retail Controls page in the Google Cloud console.

    Go to the Controls page

  2. Go to the Site-wide controls tab.

    This tab displays a table of all product attributes you can set site-wide controls for.

  3. Click Modify Controls.

  4. Set Filterable (recs) to True for the product attribute.

  5. Click Save Controls.

You can start using the attribute for filtering after the next model training cycle has completed.

Set attributes as filterable using the API

AttributesConfig represents a list of attributes for a catalog.

Set the AttributesConfig.filteringOption field for CatalogAttribute. This field's allowed values are:

  • RECOMMENDATIONS_FILTERING_DISABLED (default): Filtering is turned off for the attribute.
  • RECOMMENDATIONS_FILTERING_ENABLED: Filtering is turned on for the attribute.

The following curl example queries your existing product attributes.

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \ "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/attributesConfig"

The following curl example sets the product attribute categories as filterable.

When updating an existing attribute, keep the attribute's original values for indexableOption, dynamicFacetableOption, and searchableOption as they appear in the previous step. If your chosen attribute did not appear when viewing attributesConfig as in the previous example, then use the default settings as shown in the following example.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
        'name': 'projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/attributesConfig',
        'catalogAttributes': {
          'categories': {
            'key': 'categories',
            'indexableOption': 'INDEXABLE_ENABLED',
            'dynamicFacetableOption': 'DYNAMIC_FACETABLE_DISABLED',
            'searchableOption': 'SEARCHABLE_DISABLED',
            'recommendationsFilteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED'
          }
        },
        'attributeConfigLevel': 'CATALOG_LEVEL_ATTRIBUTE_CONFIG'
     }" \
"https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/attributesConfig"

You can start using the attribute for filtering after the next model training cycle has completed.

Use filterable attributes in a predict request

After your model has been retrained, you can use filterable product attributes in your predict requests.

Set the request parameter value filterSyntaxV2 to true to activate version 2 recommendations filtering. If the parameter is not set, version 1 filtering remains active. If a model has both manually created tags and filterable product attributes, it can serve predict requests using either version of filtering. However, it's not possible to include both v1 filtering and v2 filtering expressions in the same predict request.

The following partial curl example shows filterSyntaxV2 set to true, and a filter expression using the product attributes colors and categories. This example assumes colors and categories are set as filterable.

"params": {
  "filterSyntaxV2": true
},
"filter": "(categories: ANY(\"Phone > Android > Pixel\") OR colors: ANY(\"red\", \"green\")) AND (availability: ANY(\"IN_STOCK\"))"

The following curl example shows a complete predict request.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
        'userEvent': {
          'eventType': 'detail-page-view',
          'visitorId': 'VISITOR_ID',
          'productDetails': {
            'product': {
              'id': 'PRODUCT_ID'
            }
          }
        },
        'params': {
          'returnProduct': true,
          'filterSyntaxV2': true,
          'strictFiltering': true,
        },
        'filter': 'categories: ANY(\"xyz\")',
        useMostRecentServingConfig: true
     }" \
     "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/placements/SERVING_CONFIG:predict"