Retail is being renamed to Vertex AI Search for retail. We are in the process of updating content to reflect the new branding.

About serving controls

You can apply serving controls to serving configs to customize how 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 Search for Retail console or using the API Control.create method.

You can then attach the new serving control to any search serving configs 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 the Search for Retail console, see Create serving controls.

The following serving controls are available:

Boost/bury: Affects result ranking and order in the returned result list. Available for search and recommendations.
Filter: Removes results that don't pass the filter from the returned result list. Available for search only.
Redirect: Redirects your users to a specific page depending on the search query. Available for search only.
Pinning: Exact position in the results is specified for a certain product.
Linguistic: Customizes search query linguistics. Available for 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 search or recommendations. Boost/bury for recommendations is in Public Preview.

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

For search filters, use the filter expression syntax documented in Filter and order results.
For recommendations filters, use the filter expression syntax documented in Filter recommendations.

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 search and recommendations boost/bury controls:

Search: You can set query terms and applicable time ranges as the control conditions.
Recommendations: 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.

Pinning controls

Pinning controls let you specify an exact position in the results you want a certain product to appear.

You can create a pinning control for search or browse. It is not supported for recommendations.

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

As a control action, add a Rule to your search or browse Condition which will be the action field pin_action.

You can then apply a pin value between [1,120] to indicate the fixed position to pin the results to matching those conditions given.

Rule Condition: Must specify non-empty [Condition.query_terms][] (for search only) or [Condition.page_categories][] (for browse only), but not both.
Action Input: [pin_position, product_id] pairs are mapped (the input position can be a value from 1 to 120). The maximum size is the maximum request page size. 10 is the number of allowed pairs in the pin map.
Action Result: Pin products with matching IDs to the position specified in the final result order. To name an example, suppose the query is "shoes", the [Condition.query_terms][] is "shoes" and the pin_map has {1, pid1}. The product with pid1 is pinned to the top position in the final results.

Enabling pins and applied rules

When a pinning control is enabled:

Products with product IDs which match a pin appear in the final response in the exact position specified by the control.
Pins to the second page or later (higher page number) are not allowed, that is, any pin that is set to a position higher than the request page_size is ignored.
A maximum of 10 products can be pinned with one control.
The product_id must be the ID of an existing product in the catalog.

The product is always recalled in every search and appears on the page unless:

Filters and sorting are applied. These prevent pins from appearing.
The sort order (such as having the search results sorted by price) is not the default.

Pin behavior

If a product is pinned, it will ignore any boosts or buries from the request or from other controls.
If a product is pinned to multiple positions, the most recently updated control takes precedence.
Two products cannot be pinned to the same position inside the same pinning control (pin map).
- If multiple controls match the same query and each of those have a different pin for the same product ID, the [pin_pos, p_id] pair from the most recently updated control takes precedence.

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, 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 search treats them the same during searches.

You can set query terms and applicable time ranges as the control conditions. You don't 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, search can then expand the query to include results for "dish towel", and for "kicthen towel" also.

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

Note that synonyms don't change the original query. For example, a two way synonym of "A<==>B" will have the following effect:

For query "A", the results returned should be Result set A (when no synonym rule applied) + Some of Result set B, but may still be less than the union of Result Set A + Result set B.
For query "B", the results returned should be Result set B + Some of Result Set A, but may still be less than Result Set A + Result set B.

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" don't expand to include the term "rose."

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

Note that just as with two-way synonyms, the original query is executed and the synonyms are provided as hints to that query. Synonyms for entirely different words may only result in small numbers of the synonym terms being included in the results. For example, a synonym rule for "dog=>cat" will still return mostly dogs, plus some cats, while the "rose=>pink" example should return pink items with an emphasis on pink roses.

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

Ignore controls

Ignore controls prevents search from using certain query terms during searches.

An ignore control is not a negative operator – it does not guarantee that Vertex AI Search for retail won't provide any results for that term. To prevent this from happening entirely, use a filter control. An ignore control applied to a single word query may still return results as there may be Google-defined synonyms or query expansion that will match some products.

For example, an ignore control for the word "oil" will still return oil paints for a query of "oil paints." The query will be passed as "paints," and there may be many oil paints matched, but the result set will be larger as the search is for "paints." This type of control might be useful if "oil paints" were a popular query on your site and you sell many different types of paints, but not many oil-based paints.

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

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 shouldn't 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", 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 the Search for Retail console, see Create a new serving control.

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