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

Serving controls

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 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 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.
  • Filter: Removes results that do not pass the filter from the returned result list.
  • Redirect: Redirects your users to a specific page depending on the search query.
  • Linguistic: Customizes search query linguistics. 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. Depending on the control type, you can specify multiple condition fields.

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.

When creating a boost/bury control, you can use filter expressions to specify the conditions based on Product fields. See Filter and order results for the filter expression syntax. 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.

You can set query terms and applicable time ranges as the control conditions. As a control action, specify a filter for products to boost or bury, and set the boost/bury value.

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

To create a boost/bury control in Cloud console, 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 pre-defined 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 in Cloud console, 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 in Cloud console, 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 in Cloud console, 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 in Cloud console, 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 in Cloud console, 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 in Cloud console, 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 Cloud console, see Create a new serving control.

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