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

Create serving controls

This page describes how to create serving controls.

Serving controls are rules that you define and apply to individual serving configs. For more information about serving configurations, see About serving configs.

Serving controls enable you to create rules that customize how your serving configurations serve results.

You can create a serving control in the Search for Retail console consisting of a condition, which triggers the control, and an action that takes place when the condition triggers. You can then attach the new serving control to a serving configuration.

Serving configs have a multi-to-multi relationship with controls. You can add multiple controls to a serving config, and a single control can be associated with multiple serving configs.

When you create serving controls and serving configs, you select a product (recommendations or search) that it can be used for. Serving controls can be associated only with serving configs of the same product type. For example, a serving control created for recommendations can't be associated with a serving config that was created for search.

Serving configs manage which controls are applied during a search or prediction request. Only the controls on the active serving config for a request are considered at serving time. For example, suppose you have created two controls: a control called "gShoe Sale" that boosts results for the brand gShoe when "shoes" is searched for and a control called "More Shoes" that expands queries using the term "running shoes" to include "sport shoes". If you attach only the "gShoe Sale" control to a serving config, then search requests using that serving config boosts gShoe results for queries using the term "shoes", but the "More Shoes" control has no effect because it is not attached to the serving config you are using.

You can create controls and then add or swap them into a live serving configuration.

Create or modify serving controls at any time on the Controls page or inline using the Controls.create method. In the console, you can optionally create controls during the serving config creation process.

You can create up to 100 serving controls. If you need more serving controls, request additional quota. For how to request additional quota, see Increase your quotas. A serving config can have up to 100 serving controls of any type besides redirect controls, whose limit is 1000 per serving config.

Serving controls are available for:

Boost/bury: Affects result ranking and order in the returned result list. Available for search and recommendations.
Filter: Removes results that do not 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.
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.
- Do not associate: Prevent a group of terms from being used in search when specific terms appear.
- Ignore: Prevent a term from being used in searches.
- Replacement: Replaces terms in the search query.

For examples of these controls, see About serving controls.

Redirect control tutorial

This tutorial shows you to how to use the redirect control.

To follow step-by-step guidance for this task directly in the Cloud Shell Editor, click Guide me:

Guide me

Create a new serving control

Create a new serving control on the Controls page in the Google Cloud console or inline using the Controls.create method.

Controls have different requirements depending on their type. Go to the creation procedure for the type of control you plan to create:

Create a boost/bury control
Create a filter control
Create a redirect control
Create a two-way synonym control
Create a one-way synonym control
Create a do-not-associate control
Create an ignore control
Create a replacement control

Create a boost/bury control

See Boost/bury controls for more about this control type.

This control type is available for search and recommendations.

Create a search boost/bury control
Create a recommendations boost/bury control

Create a search boost/bury control

To create a search boost/bury control:

Console

Go to the Controls page in the Search for Retail console.

Go to the Controls page
On the Serving controls tab, click Create control.

The Create control pane opens.

In the Preferences section:

In the Control name field, enter a name for your new control.
Optional: To change the automatically created control ID, click Edit and enter a new control ID.
In the Product selection section, select Search.
Choose Boost/bury controls as the control type.
Click continue to proceed to the Triggers section.

In the Triggers section, set conditions that trigger the control:

Select what type of user behavior triggers this control:
- Browse categories: The rule is triggered when a user browses categories on your site (search.request.query is empty).
- Search: The rule is triggered when a user searches on your site (search.request.query isn't empty).
You can set specific categories or queries that can trigger this control in the following step. To set this control to trigger when any category is browsed, or any query is searched for, skip the following step.
Optional: Set a control condition that triggers the rule based on if a specific category is browsed or a specific query is searched for.

To set this control to trigger on any category or any query, skip this step.

The available option depends on if you chose Browse categories or Search:
- If you chose Browse categories: In the Categories field, enter which categories will trigger this control when browsed.
- If you chose Search: Click the Add query button to add query terms (for example, running shoes) to be filtered, and select one of the following for each term:
  - Partial match: This control applies when a query contains a partial match to this query term.
  - Full match: This control applies only when a query contains a full match to this query term.
  When one of these terms is included in a query, the control is applied.
If you specify time range conditions in addition to this type of condition, the control is applied only if both conditions are met.
Optional: Click the Add Time Range button to add one or more time ranges during which this control can be applied.

If you specify a category or query term condition in addition to a time range conditions, the control is applied only when both conditions are met.
Click Continue to proceed to the Actions section.

In the Actions section:

Add filters for product attributes in the Boost/bury product field.

Use the filter expression syntax documented in Filtering and ordering.

For example, to specify red and blue versions of "product1" and "product2": (id: ANY("product1","product2")) AND (colorFamily: ANY("Red","Blue"))
For Boost/bury value, use the slider to set the strength of the boost. Positive values boost the results, and negative values bury them.
Click Continue to proceed to the Serving configs section.

In the Serving configs section:

Select which serving configs to apply the control to.
Submit your control settings.

It takes a few minutes for newly created or updated controls to be ready to serve live traffic. You can test if your changes have been applied on the console Evaluate page.

You can find the new control listed on the Serving controls tab of the Controls page.

curl

Make a Control.create request with a control ID and an instance of Control contained in the request body.

For field details, see the Controls API reference and the Controls.create API reference.

A boost/bury control can be triggered when a user browses categories on your site (search.request.query is empty), or when a user searches on your site (search.request.query isn't empty).

The following example shows fields for a browse-triggered control, where searchSolutionUseCase is set to SEARCH_SOLUTION_USE_CASE_BROWSE.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "searchSolutionUseCase": [
                "SEARCH_SOLUTION_USE_CASE_BROWSE"
              ],
              "rule": {
                "condition": {
                  "pageCategories": [
                      "CATEGORY_ABC",
                      "CATEGORY_XYZ"
                  ],
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "boostAction": {
                  "boost": BOOST_NUMBER,
                  "productsFilter": "FILTER_EXPRESSION"
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

The following example shows fields for a search-triggered control, where searchSolutionUseCase is set to SEARCH_SOLUTION_USE_CASE_SEARCH.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "searchSolutionUseCase": [
                "SEARCH_SOLUTION_USE_CASE_SEARCH"
              ],
              "rule": {
                "condition": {
                  "queryTerms": [
                    {
                      "value": "VALUE_1",
                      "fullMatch": "FULLMATCH_BOOLEAN_1"
                    },
                    {
                      "value": "VALUE_2",
                      "fullMatch": "FULLMATCH_BOOLEAN_2"
                    }
                  ],
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "boostAction": {
                  "boost": BOOST_NUMBER,
                  "productsFilter": "FILTER_EXPRESSION"
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

It takes a few minutes for newly created or updated controls to be ready to serve live traffic. You can test if your changes have been applied on the console Evaluate page.

To add a control to a serving config, use the ServingConfig.addControl method:

For more about this method, see the ServingConfig.addControl API reference.
For an example of this method, see Manage serving configs.

Create a recommendations boost/bury control

To create a recommendations boost/bury control:

Console

Go to the Controls page in the Search for Retail console.

Go to the Controls page
On the Serving controls tab, click Create control.

The Create control pane opens.

In the Preferences section:

In the Control name field, enter a name for your new control.
(Optional) To change the automatically created control ID, click Edit and enter a new control ID.
In the Product selection section, select Recommendation.
Choose Boost/bury controls as the control type.
Click Continue to proceed to the Actions section.

In the Actions section:

Add filters for product attributes in the Boost/bury product field.

Use the filter expression syntax documented in Filter recommendations.

For example, to specify red and blue versions of "product1" and "product2": (id: ANY("product1","product2")) AND (colorFamily: ANY("Red","Blue"))
For Boost/bury value, use the slider to set the strength of the boost. Positive values boost the results, and negative values bury them.
Click Continue to proceed to the Serving configs section.

In the Serving configs section:

Select which serving configs to apply the control to.
Submit your control settings.

It takes a few minutes for newly created or updated controls to be ready to serve live traffic. You can test if your changes have been applied on the console Evaluate page.

You can find the new control listed on the Serving controls tab of the Controls page.

curl

Make a Control.create request with a control ID and an instance of Control contained in the request body.

For field details, see the Controls API reference and the Controls.create API reference.

To create a filter expression, use the filter expression syntax documented in Filter recommendations.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_RECOMMENDATION" ],
                "boostAction": {
                  "boost": BOOST_NUMBER,
                  "productsFilter": "FILTER_EXPRESSION"
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

It takes a few minutes for newly created or updated controls to be ready to serve live traffic. You can test if your changes have been applied on the console Evaluate page.

To add a control to a serving config, use the ServingConfig.addControl method:

For more about this method, see the ServingConfig.addControl API reference.
For an example of this method, see Manage serving configs.

Create a filter control

See Filter controls for more about this control type.

Console

Go to the Controls page in the Search for Retail console.

Go to the Controls page
On the Serving controls tab, click Create control.

The Create control pane opens.

In the Preferences section:

In the Control name field, enter a name for your new control.
Optional: To change the automatically created control ID, click Edit and enter a new control ID.
Choose Filter controls as the control type.
Click continue to proceed to the Triggers section.

In the Triggers section:

Select what type of user behavior triggers this control:
- Browse categories: The rule is triggered when a user browses categories on your site (search.request.query is empty).
- Search: The rule is triggered when a user searches on your site (search.request.query isn't empty).
Optional: Set a control condition that triggers the rule based on what category is browsed, or what query is searched for. The available option depends on if you chose Browse categories or Search:
- If you chose Browse categories: In the Categories field, enter which categories will trigger this control when browsed.
- If you chose Search: Click the Add query button to add query terms (for example, running shoes) to be filtered, and select one of the following for each term:
  - Partial match: This control applies when a query contains a partial match to this query term.
  - Full match: This control applies only when a query contains a full match to this query term.
  When one of these terms is included in a query, the control is applied.
If you specify a time range condition in addition to this condition, the control is applied only if both conditions are met.
Optional: Click the Add Time Range button to add one or more time ranges during which this control can be applied.

If you specify a category or query term condition in addition to this time range condition, the control is applied only when both conditions are met.
Click Continue to proceed to the Actions section.

In the Actions section:

Add filters for product attributes in the Filter action field.

Use the filter expression syntax documented in Filtering and ordering.

For example, to specify red and blue versions of "product1" and "product2": (id: ANY("product1","product2")) AND (colorFamily: ANY("Red","Blue"))
Click Continue to proceed to the Serving configs section.

In the Serving configs section:

Select which serving configs to apply the control to.
Submit your control settings.

It takes a few minutes for newly created or updated controls to be ready to serve live traffic. You can test if your changes have been applied on the console Evaluate page.

You can find the new control listed on the Serving controls tab of the Controls page.

curl

Make a Control.create request with a control ID and an instance of Control contained in the request body.

For field details, see the Controls API reference and the Controls.create API reference.

A filter control can be triggered when a user browses categories on your site (search.request.query is empty), or when a user searches on your site (search.request.query isn't empty).

The following example shows fields for a browse-triggered control, where searchSolutionUseCase is set to SEARCH_SOLUTION_USE_CASE_BROWSE.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "searchSolutionUseCase": [
                "SEARCH_SOLUTION_USE_CASE_BROWSE"
              ],
              "rule": {
                "condition": {
                  "pageCategories": [
                      "CATEGORY_ABC",
                      "CATEGORY_XYZ"
                  ],
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "filterAction": {
                  "filter": "FILTER_EXPRESSION"
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

The following example shows fields for a search-triggered control, where searchSolutionUseCase is set to SEARCH_SOLUTION_USE_CASE_SEARCH.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "searchSolutionUseCase": [
                "SEARCH_SOLUTION_USE_CASE_SEARCH"
              ],
              "rule": {
                "condition": {
                  "pageCategories": [
                      "CATEGORY_ABC",
                      "CATEGORY_XYZ"
                  ],
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "filterAction": {
                  "filter": "FILTER_EXPRESSION"
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

To add a control to a serving config, use the ServingConfig.addControl method:

For more about this method, see the ServingConfig.addControl API reference.
For an example of this method, see Manage serving configs.

Create a redirect control

See Redirect controls for more about this control type.

Console

Go to the Controls page in the Search for Retail console.

Go to the Controls page
On the Serving controls tab, click Create control.

The Create control pane opens.

In the Preferences section:

In the Control name field, enter a name for your new control.
Optional: To change the automatically created control ID, click Edit and enter a new control ID.
Choose Redirect controls as the control type.
Click continue to proceed to the Triggers section.

In the Triggers section, create at least one query term or time range trigger. Redirect controls require at least one trigger:

Select what type of user behavior triggers this control:
- Browse categories: The rule is triggered when a user browses categories on your site (search.request.query is empty).
- Search: The rule is triggered when a user searches on your site (search.request.query isn't empty).
Set a control condition that triggers the rule based on what category is browsed, or what query is searched for. The available option depends on if you chose Browse categories or Search:
- If you chose Browse categories: In the Categories field, enter which categories will trigger this control when browsed.
- If you chose Search: Click the Add query button to add query terms (for example, running shoes) to be filtered, and select one of the following for each term:
  - Partial match: This control applies when a query contains a partial match to this query term.
  - Full match: This control applies only when a query contains a full match to this query term.
  When one of these terms is included in a query, the control is applied.
If you specify a time range condition in addition to this condition, the control is applied only if both conditions are met.
Click the Add Time Range button to add one or more time ranges during which this control can be applied.

If you specify a category or query term condition in addition to this time range condition, the control is applied only when both conditions are met.
Click Continue to proceed to the Actions section.

In the Actions section:

Enter the URI to redirect to when this control is triggered.
Click Continue to proceed to the Serving configs section.

In the Serving configs section:

Select which serving configs to apply the control to.
Submit your control settings.

It takes a few minutes for newly created or updated controls to be ready to serve live traffic. You can test if your changes have been applied on the console Evaluate page.

You can find the new control listed on the Serving controls tab of the Controls page.

curl

Make a Control.create request with a control ID and an instance of Control contained in the request body.

For field details, see the Controls API reference and the Controls.create API reference.

A redirect control can be triggered when a user browses categories on your site (search.request.query is empty), or when a user searches on your site (search.request.query isn't empty).

The following example shows fields for a browse-triggered control, where searchSolutionUseCase is set to SEARCH_SOLUTION_USE_CASE_BROWSE.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "searchSolutionUseCase": [
                "SEARCH_SOLUTION_USE_CASE_BROWSE"
              ],
              "rule": {
                "condition": {
                  "queryTerms": [
                    {
                      "value": "VALUE_1",
                      "fullMatch": "FULLMATCH_BOOLEAN_1"
                    },
                    {
                      "value": "VALUE_2",
                      "fullMatch": "FULLMATCH_BOOLEAN_2"
                    }
                  ],
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "redirectAction": {
                  "redirectUri": "REDIRECT_URI",
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

The following example shows fields for a search-triggered control, where searchSolutionUseCase is set to SEARCH_SOLUTION_USE_CASE_SEARCH.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "searchSolutionUseCase": [
                "SEARCH_SOLUTION_USE_CASE_SEARCH"
              ],
              "rule": {
                "condition": {
                  "queryTerms": [
                    {
                      "value": "VALUE_1",
                      "fullMatch": "FULLMATCH_BOOLEAN_1"
                    },
                    {
                      "value": "VALUE_2",
                      "fullMatch": "FULLMATCH_BOOLEAN_2"
                    }
                  ],
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "redirectAction": {
                  "redirectUri": "REDIRECT_URI",
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

To add a control to a serving config, use the ServingConfig.addControl method:

For more about this method, see the ServingConfig.addControl API reference.
For an example of this method, see Manage serving configs.

Create a two-way synonym control

See Two-way synonym controls for more about this control type.

Console

Go to the Controls page in the Search for Retail console.

Go to the Controls page
On the Serving controls tab, click Create control.
In the Control name field, enter a name for your new control.

The Create control pane opens.

In the Preferences section:

Optional: To change the automatically created control ID, click Edit and enter a new control ID.
Choose Two-way synonym control as the control type.
Click continue to proceed to the Triggers section.

In the Triggers section:

Optional: Click the Add Time Range button to add one or more time ranges during which this control can be applied.
Click Continue to proceed to the Actions section.

In the Actions section:

In the Synonyms field, enter 2 to 100 query terms (for example, shirt and top) that should be synonyms of each other.

When any one of these terms is included in a query, search considers the other query terms as synonyms of the included term.
Click Continue to proceed to the Serving configs section.

In the Serving configs section:

Select which serving configs to apply the control to.
Submit your control settings.

It takes a few minutes for newly created or updated controls to be ready to serve live traffic. You can test if your changes have been applied on the console Evaluate page.

You can find the new control listed on the Serving controls tab of the Controls page.

curl

Make a Control.create request with a control ID and an instance of Control contained in the request body.

For field details, see the Controls API reference and the Controls.create API reference.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "rule": {
                "condition": {
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                    ]
                },
                "twoWaySynonymAction": {
                  "synonyms": [
                    "SYNONYM_1",
                    "SYNONYM_2"
                  ]
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

To add a control to a serving config, use the ServingConfig.addControl method. See Add controls to serving configs inline.

Create a one-way synonym control

See One-way synonym controls for more about this control type.

Console

Go to the Controls page in the Search for Retail console.

Go to the Controls page
On the Serving controls tab, click Create control.

The Create control pane opens.

In the Preferences section:

In the Control name field, enter a name for your new control.
Optional: To change the automatically created control ID, click Edit and enter a new control ID.
Choose One-way synonym control as the control type.
Click continue to proceed to the Triggers section.

In the Triggers section:

Optional: Click the Add Time Range button to add one or more time ranges during which this control can be applied.
Click Continue to proceed to the Actions section.

In the Actions section:

In the Query terms field, enter terms (for example, shoes) that should have synonyms associated with them when any of them is included in a query.
In the Synonyms field, enter terms that should be used as synonyms for the query terms you specified (for example, sneakers and sandals as one-way synonyms for the query term shoes).
Click Continue to proceed to the Serving configs section.

In the Serving configs section:

Select which serving configs to apply the control to.
Submit your control settings.

It takes a few minutes for newly created or updated controls to be ready to serve live traffic. You can test if your changes have been applied on the console Evaluate page.

You can find the new control listed on the Serving controls tab of the Controls page.

curl

Make a Control.create request with a control ID and an instance of Control contained in the request body.

For field details, see the Controls API reference and the Controls.create API reference.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "rule": {
                "condition": {
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "oneWaySynonymAction": {
                  "synonyms": [
                    "queryTerms": [
                      "QUERY_TERM_1",
                      "QUERY_TERM_2"
                    ],
                    "synonyms": [
                      "SYNONYM_1",
                      "SYNONYM_2"
                    ]
                  ]
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

To add a control to a serving config, use the ServingConfig.addControl method:

For more about this method, see the ServingConfig.addControl API reference.
For an example of this method, see Manage serving configs.

Create a do-not-associate control

See Do-not-associate controls for more about this control type.

Console

Go to the Controls page in the Search for Retail console.

Go to the Controls page
On the Serving controls tab, click Create control.

The Create control pane opens.

In the Preferences section:

In the Control name field, enter a name for your new control.
Optional: To change the automatically created control ID, click Edit and enter a new control ID.
Choose Do not associate control as the control type.
Click continue to proceed to the Triggers section.

In the Triggers section:

Optional: Click the Add Time Range button to add one or more time ranges during which this control can be applied.
Click Continue to proceed to the Actions section.

In the Actions section:

In the Query terms field, enter terms (for example, gShoe) that you want to explicitly disambiguate from others.
In the Dissociated terms field, enter terms that should not be associated in search results with the query terms you have specified.

For example, you can dissociate the query term gShoe from the term cheap.
Click Continue to proceed to the Serving configs section.

In the Serving configs section:

Select which serving configs to apply the control to.
Submit your control settings.

It takes a few minutes for newly created or updated controls to be ready to serve live traffic. You can test if your changes have been applied on the console Evaluate page.

You can find the new control listed on the Serving controls tab of the Controls page.

curl

Make a Control.create request with a control ID and an instance of Control contained in the request body.

For field details, see the Controls API reference and the Controls.create API reference.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "rule": {
                "condition": {
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "doNotAssociateAction": {
                    "queryTerms": [
                      "QUERY_TERM_1",
                      "QUERY_TERM_2"
                    ],
                    "doNotAssociateTerms": [
                      "DISSOCIATED_TERM_1",
                      "DISSOCIATED_TERM_2"
                    ]
                  ]
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

To add a control to a serving config, use the ServingConfig.addControl method:

For more about this method, see the ServingConfig.addControl API reference.
For an example of this method, see Manage serving configs.

Create an ignore control

See Ignore controls for more about this control type.

Console

Go to the Controls page in the Search for Retail console.

Go to the Controls page
On the Serving controls tab, click Create control.

The Create control pane opens.

In the Preferences section:

In the Control name field, enter a name for your new control.
Optional: To change the automatically created control ID, click Edit and enter a new control ID.
Choose Do not associate control as the control type.
Click continue to proceed to the Triggers section.

In the Triggers section:

Optional: Click the Add Time Range button to add one or more time ranges during which this control can be applied.
Click Continue to proceed to the Actions section.

In the Actions section:

In the Ignore terms field, enter terms (for example, shoddy) that you want a search to ignore when they are entered as query terms.
Click Continue to proceed to the Serving configs section.

In the Serving configs section:

Select which serving configs to apply the control to.
Submit your control settings.

It takes a few minutes for newly created or updated controls to be ready to serve live traffic. You can test if your changes have been applied on the console Evaluate page.

You can find the new control listed on the Serving controls tab of the Controls page.

curl

Make a Control.create request with a control ID and an instance of Control contained in the request body.

For field details, see the Controls API reference and the Controls.create API reference.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "rule": {
                "condition": {
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "ignoreAction": {
                  "ignoreTerms": [
                      "IGNORE_TERM_1",
                      "IGNORE_TERM_2"
                    ]
                  ]
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

To add a control to a serving config, use the ServingConfig.addControl method:

For more about this method, see the ServingConfig.addControl API reference.
For an example of this method, see Manage serving configs.

Create a replacement control

See Replacement controls for more about this control type.

Console

Go to the Controls page in the Search for Retail console.

Go to the Controls page
On the Serving controls tab, click Create control.

The Create control pane opens.

In the Preferences section:

In the Control name field, enter a name for your new control.
Optional: To change the automatically created control ID, click Edit and enter a new control ID.
Choose Replacement control as the control type.
Click continue to proceed to the Triggers section.

In the Triggers section:

Optional: Click the Add Time Range button to add one or more time ranges during which this control can be applied.
Click Continue to proceed to the Actions section.

In the Actions section:

In the Query terms field, enter query terms (for example, gShoe) that you want to have replaced by the replacement term.
In the Replacement term field, enter the term that should replace the query terms you specified.

For example, you can replace the query term gShoe with the replacement term Google Shoe.
Click Continue to proceed to the Serving configs section.

In the Serving configs section:

Select which serving configs to apply the control to.
Submit your control settings.

It takes a few minutes for newly created or updated controls to be ready to serve live traffic. You can test if your changes have been applied on the console Evaluate page.

You can find the new control listed on the Serving controls tab of the Controls page.

curl

Make a Control.create request with a control ID and an instance of Control contained in the request body.

For field details, see the Controls API reference and the Controls.create API reference.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "rule": {
                "condition": {
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "replacementAction": {
                    "queryTerms": [
                      "QUERY_TERM_1",
                      "QUERY_TERM_2"
                    ],
                    "replacementTerm": "REPLACEMENT_TERM"
                  }
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

To add a control to a serving config, use the ServingConfig.addControl method:

For more about this method, see the ServingConfig.addControl API reference.
For an example of this method, see Manage serving configs.