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

Serving controls

Stay organized with collections Save and categorize content based on your preferences.

You can apply serving controls to serving configs to customize how Retail Search treats search queries and returns results. A serving control is a rule consisting of a condition-action pair, where the condition dictates when the serving control will execute, and the action specifies what behavior the serving control will enact.

You can create a serving control in the Google Cloud console or using the API Control.create method.

You can then attach the new serving control to any Retail Search serving configurations you have created. Only controls on an active serving configuration for a request are considered at serving time.

For more about how to create serving controls in Google Cloud console, see Creating and managing controls.

The following serving controls are available:

  • Boost/bury: Affects result ranking and order in the returned result list. Available for Retail Search and Recommendations AI.
  • Filter: Removes results that do not pass the filter from the returned result list. Available for Retail Search only.
  • Redirect: Redirects your users to a specific page depending on the search query. Available for Retail Search only.
  • Linguistic: Customizes search query linguistics. Available for Retail Search only. Several types of linguistic controls are available:
    • Synonym: Expands considered synonyms for a search query.
    • One-way synonym: Expands considered synonyms unidirectionally for specific terms.
    • Ignore: Prevents a term from being used in searches.
    • Do not associate: Prevent terms from being used in searches when specific terms appear.
    • Replacement: Replaces terms in the search query.

Control conditions

Control conditions dictate when a serving control will execute.

Control condition fields can be query terms, time ranges, or both. Some control types allow multiple condition fields, or don't allow any.

The condition fields available:

  • Query terms: Triggered when the term appears in the search query.
    • A full match requires the entire search query to match the query term.
    • Multiple query terms can be specified. Triggers as long as one of the query terms appears in the search query.
  • Active time range: Triggered when the date of the search query is in the time range.
    • Multiple time ranges can be specified. Triggers as long as date of query is within the time range (inclusive).

The condition fields that you specify determine whether the control will be applied.

  • Multiple condition fields are combined using AND. This means that if you specify both time range and query terms, both condition fields need to be triggered for the control to apply.
  • Multiple condition sub-fields are combined using OR. This means that if you have multiple query terms the query terms will be triggered if any one query term matches. If you have multiple time ranges, then time range will be triggered if any one time range matches.
  • No condition fields specified mean the control always applies. However, some controls require a field to be defined.

For more about condition settings, see the Controls.condition API reference.

Control actions

A control action specifies what behavior the serving control will enact if the conditions are met during a search.

What kind of action you can specify depends on the type of serving control you create. For example, the action for a boost/bury control is to apply a boost/bury value to products that the filter you specify, while the action for a one-way synonym control is to apply an associated term that you specify.

Boost/bury controls

Boost/bury controls enable you to show certain search results as higher or lower in ranking.

You can create a boost/bury control for Retail Search or Recommendations AI. Boost/bury for Recommendations AI is in Public Preview.

When creating a boost/bury control, you can use filter expressions to specify the conditions based on Product fields.

You can then apply a boost value between -1.0 and 1.0 to indicate how much to boost or bury product results matching those conditions. A positive value boosts the results, and a negative value buries them.

Setting a high boost strength gives the item a large promotion, but doesn't necessarily mean that the boosted item will be the top result at all times. Results that are significantly more relevant to the search query can still trump heavily favored but irrelevant items. Likewise, setting the boost strength to -1.0 would give the item a large demotion, but results that are deeply relevant might still be shown.

As an example of using boost/bury, you could prioritize cheaper products and deprioritize the expensive ones.

Control conditions differ between Retail Search and Recommendations AI boost/bury controls:

  • Retail Search: You can set query terms and applicable time ranges as the control conditions.
  • Recommendations AI: Control conditions aren't available. The control always applies.

As a control action, specify a filter for products to boost or bury, and set the boost/bury value.

To create a boost/bury control, see Create a new serving control.

For more about boost/bury control settings, see the Controls.BoostAction API reference.

Filter controls

With filter controls, you can dynamically add predefined filters based on a specific search request.

You can use filter expressions based on Product fields. See Filter and order results for the filter expression syntax.

You can set query terms and applicable time ranges as the control conditions. As a control action, specify a filter to apply at query time.

For example, given the query "blue shoes", you can use a filter control to automatically filter search results on the color blue. You can also use filter controls to prevent certain results from being returned to shoppers.

To create a filter control, see Create a new serving control.

For more about filter control settings, see the Controls.FilterAction API reference.

Redirect controls

You can use a redirect control to redirect your shoppers to different pages based on their intent, instead of only showing them search results.

You can set query terms and applicable time ranges as the control conditions. As a control action, specify a redirect URI to redirect to if the conditions are matched.

For example, you could create a redirect control so that during a promotion for a the product "gShoe", queries with "running shoes" or "sports" shoes redirects to the gShoe product page.

To create a redirect control, see Create a new serving control.

For more about redirect control settings, see the Controls.RedirectAction API reference.

Linguistic controls

You can create additions or overrides to how words are treated by default.

For example, if you are a merchandiser, you might want to expand queries that have the term "running shoes" to include "sport shoes", so that search results include both keywords. With linguistic controls, you can create a linguistic synonym control where the condition is that "running shoes" is entered as the search term, and the action is include the synonym "sport shoes" with that search. When a shopper on your site enters "running shoes" as a query, Retail Search finds that match in the linguistic control you created, and expands the search to include "sport shoes" when it returns search results to the shopper.

Two-way synonym controls

Use two-way synonym controls to link several terms together so that Retail Search treats them the same during searches.

You can set query terms and applicable time ranges as the control conditions. You do not need to set a separate control action; if a term you specified is used as a query, the control action is to use other terms you specified as the synonyms.

For example, you could set a two-way synonym control that associates the terms "dish towel" and "kitchen towel" as synonyms. When a shopper on your site enters "kitchen towel" as a query, Retail Search can then expand the query to include results for "dish towel", and vice versa.

To create a synonym control, see Create a new serving control.

For more about two-way synonym control settings, see the Controls.TwowaySynonymsAction API reference.

One-way synonym controls

One-way synonym controls link terms together unidirectionally.

You can set query terms and applicable time ranges as the control conditions. As a control action, specify the terms to use as one-way synonyms.

For example, you could set a one-way synonym control that expands searches for the term "rose" to include the term "pink". Because it is a one-way synonym, searches for the term "pink" do not expand to include the term "rose."

To create a one-way synonym control, see Create a new serving control.

For more about one-way synonym control settings, see the Controls.OnewaySynonymsAction API reference.

Ignore controls

Ignore controls prevents Retail Search from using certain query terms during searches.

An ignore control does not guarantee that Retail Search won't provide any results. To prevent this from happening entirely, use a filter control.

You can set query terms and applicable time ranges as the control conditions. You do not need to set a separate control action; if a term you specified is used as a query, the control action is to ignore that term.

For example, you could create a control that ignores query terms that use offensive language.

To create an ignore control, see Create a new serving control.

For more about ignore control settings, see the Controls.IgnoreAction API reference.

Do-not-associate controls

Do-not-associate controls prevent query terms from being queried together during searches with other terms that you specify.

You can set query terms and applicable time ranges as the control conditions. As a control action, specify the terms that should not be associated with the query terms.

For example, you could create a control that prevents a brand name (such as "gShoe") from being grouped with the term "cheap" and "poor quality" in a query, so that if a shopper searches for "poor quality cheap gShoe", Retail Search searches only for "gShoe."

If a relevant result for the query term also contains a term specified as "do not associate", that relevant result might still be returned. To prevent this from happening entirely, use a filter control.

To create a do-not-associate control, see Create a new serving control.

For more about do-not-associate control settings, see the Controls.DoNotAssociateAction API reference.

Replacement controls

Replacement controls replace one or more given query terms with a different term that you specify. You can specify multiple terms that can be mapped to single term (but not vice versa).

You can set query terms and applicable time ranges as the control conditions. As a control action, specify the term that should be used as a replacement.

For example, you could create a control that replaces nicknames for a brand with the full brand name that is more commonly used in product descriptions.

To create a replacement control in Google Cloud console, see Create a new serving control.

For more about replacement control settings, see the Controls.ReplacementAction API reference.