Configure serving controls for search Stay organized with collections Save and categorize content based on your preferences.
Serving controls (also called controls) change the defaultbehavior of how a request is served when results are returned. Serving controlsact at a data-store level.
For example, controls can boost and bury results, filter entries from returnedresults, associate strings with each other as synonyms, or redirect results tospecified URIs.
This page describes serving controls for search apps. For information aboutusing serving controls with media recommendations, seeCreate and manage mediaserving configs.
About serving controls
To change the results of a request, first create a serving control. Then, attachthat control to theserving config of a search app. Aserving config configuresmetadata that's used to generate serving time results, such as search results oranswers. A serving control only affects requests served by the app if thecontrol is attached to the app's serving config.
Some controls, such as boost controls, have dependencies on data stores. If adata store is removed from an app, then any data store-dependent controls arealso removed from that app and become inactive, but are not deleted.
Serving control types
The following types of serving controls are available:
| Control | Description | Available for |
|---|---|---|
| Boost control | Changes the returned order of results | Search apps with data stores that support a schema, such as data stores that contain structured data, websites with structured data (advanced website indexing), unstructured data with metadata, or media data |
| Filter control | Removes entries from returned results | Search apps with data stores that support a schema, such as data stores that contain structured data, websites (advanced website indexing), unstructured data with metadata, or media data |
| Synonyms control | Associates queries with each other | Search apps with website (advanced website indexing), structured, unstructured, or media data stores |
| Redirect control | Redirects to a specified URI | All search apps |
| Promote control | Promotes a specified link for a query | All search apps |
About conditions
When creating a control, you can optionally define a condition that determineswhen the control is applied. Conditions are defined using condition fields. Thefollowing condition fields are available:
Query terms (
queryTerms). An optional control that's applied when specific queries aresearched for. When thequeryTermscondition is used, the controlis applied when the value ofqueryTermsmatches a term inSearchRequest.query. Query terms can only be used when theControl.searchUseCaseis set asSOLUTION_TYPE_SEARCH. Up to 10 differentqueryTermscan be specified on a singleControl.condition. If no queryterms are specified, thequeryTermsfield is ignored.For a promote serving control,
queryTermscan't be specified if you'respecifying thequeryRegexcondition, which is applicable to basic website searchonly. Additionally, thefullMatchfield for basic website search,must be set totrueifqueryTermsis specified. For all other search apps,onlyqueryTermsis supported andfullMatchcan be set totrueorfalse.Time range (
activeTimeRange). An optional control that's applied when a requestoccurs within a specified time range. It checks that the time a request wasreceived is betweenactiveTimeRange.startTimeandactiveTimeRange.endTime.Up to 10activeTimeRangeranges can be specified on a singleControl.condition. If theactiveTimeRangefield isn't specified, the fieldis ignored.queryRegex. Only available for apromote serving controlfor basic website search only. This isan optional condition that applies the control when thequery matches the specified regular expression. This condition can't bespecified if you're specifying thequeryTermscondition.
If multiple conditions are specified for a control, the control is appliedto the search request when both condition types are satisfied. If multiplevalues for the same condition are specified, only one of the values needs tomatch for that condition to be satisfied.
For example, consider the following condition with two query terms specified:
"queryTerms":[{"value":"gShoe","fullMatch":true},{"value":"gBoot","fullMatch":true}]The condition will be satisfied for a request withSearchRequest.query="gShoe" or a request withSearchRequest.query="gBoot",but won't be satisfied withSearchRequest.query="gSandal" or any otherstring.
If no conditions are specified, the control is always applied.
For more information, see theCondition field in the APIreference.
Create and attach boost serving controls
A boost serving control reorders the results by promoting or demoting them basedon the applied conditions. Boost works by applying a multiplying factor to theranking of a document that meets the boost conditions.
To create and attach boost control, do the following:
Console
In the Google Cloud console, go to theAI Applications page.
Select the app for which you want to create the boost control.
On your app's overview page, make sure you are on theSystem overview tab.
In theSignalstage, click theBoost/Bury tile.
ClickCreate control.
In theCreate control pane, do the following:
ForName Your Control, enter a name for your boost/bury control and clickContinue.
ForSet Rule Scope & Impact, define the actions that you want to trigger with this control:
Select a data store from the list. If you want the action to beapplied to multiple data stores, create a control for each datastore.
ForFilter, add a filter.
This is a string specifying requirements that must bemet by the document. Only if the document matches all therequirements, the boost condition is applied. Otherwise there is nochange. If you don't specify a filters, then the boost is applied toall documents in the data store.
To understand how to write filter expressions, seeFilter expression syntax andExamples of filter expressions.
ForBoost/bury value, select a boost/bury value in the range [-1, 1] using the slider.The slider moves in steps of 0.01.
ClickContinue.
ForOptional: When This Rule Activates, set the following conditions that trigger the control. If no conditions are configured, the control is always in effect:
AddPartial match query terms. The control takes effect when thesequery terms match partially.
AddExact match query terms. The control takes effect when these queryterms match exactly.
To add an active time range, clickAdd time range and setStart time 1 andEnd time 1. This defines the window when thecondition is active. You can add a maximum of 10 time ranges.
ClickContinue.
If you want to apply this control as soon as it's created, forAdditional settings, turn onPublish this control immediately and clickContinue.
ClickSubmit.
REST
A boost serving control is defined as a control with aboostAction.
Use the following instructions to create a boost serving control.
For field details, see theengines.controls API reference and theengines.controls.create API reference.
Find your app ID. If you already have your app ID, skip to the next step.
In the Google Cloud console, go to theAI Applications page.
On theApps page, find the name of your app and get the app's ID fromtheID column.
Run the following curl commands to create your controls.
curl-XPOST\-H"Authorization: Bearer$(gcloudauthprint-access-token)"\-H"Content-Type: application/json"\-H"X-Goog-User-Project:PROJECT_ID"\"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID"\-d'{"displayName": "DISPLAY_NAME","solutionType": "SOLUTION_TYPE_SEARCH","useCases": [ "USE_CASE"],"conditions": { "queryTerms": [ { "value": "VALUE", "fullMatch":FULL_MATCH } ], "activeTimeRange": [ { "startTime": "START_TIMESTAMP", "endTime": "END_TIMESTAMP" } ]},"boostAction": { "boost":BOOST_VALUE, "filter": "FILTER", "dataStore": "DATA_STORE_RESOURCE_PATH" }}'
Replace the following:
PROJECT_ID: the number or ID of your Google Cloud project.APP_ID: the ID of the Vertex AI Search app.CONTROL_ID: a unique identifier for the control.The ID can contain [1-63] characters that can be letters, digits, hyphens,and underscores.DISPLAY_NAME: the human-readable name for the control.Google recommends that this name provide an indication of when or why touse the control. Must be a UTF-8 encoded string with length [1,128].USE_CASE: must be eitherSEARCH_USE_CASE_SEARCHorSEARCH_USE_CASE_BROWSE. IfSEARCH_USE_CASE_BROWSEis specified,thenCondition.queryTermscan't be used in the condition.CONDITION: an optional field that defines when thecontrol should be applied. Contains the following fields:VALUE: the specific query value to matchagainst. It's a lowercase UTF-8 string with length[1, 5000]. IfFULL_MATCH_1istrue, this field can have atmost three space-separated terms.FULL_MATCH: a boolean that indicates whetherthe search query needs to exactly match the query term. When set totrue, it requiresSearchRequest.queryto completely match thequeryTerm.value. When set tofalse, it requiresSearchRequest.queryto containqueryTerm.valueas a substring.START_TIMESTAMP: a timestamp in RFC 3339 UTC"Zulu" format to indicate the start of a time range.END_TIMESTAMP: a timestamp in RFC 3339 UTC"Zulu" format to indicate the end of a time range.
BOOST_VALUE: a floating point number in the range [-1,1]. When the value isnegative, results are demoted (they appear lower down in theresults). When the value is positive, results are promoted(they appear higher up in the results). For more information, seeboostAction.FILTER: a string specifying requirements that mustbe met by the document. If the document matches all the requirements, theboost is applied. Otherwise there is no change. If this field is empty, thenthe boost is applied to all documents in the data store. For the filteringsyntax, seeFilter expression syntax.Note: The document fieldtitlecan't be filtered.DATA_STORE_RESOURCE_PATH: the full resource path ofthe data store whose documents should be boosted by this control. Theformat of the full resource path isprojects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID.This data store must be attached to the engine specified in the request.
Attach the control to the app's serving config using the
engines.servingConfigs.patchmethod.curl-XPATCH\-H"Authorization: Bearer$(gcloudauthprint-access-token)"\-H"Content-Type: application/json"\-H"X-Goog-User-Project:PROJECT_ID"\"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=boost_control_ids"\-d'{ "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2"]}'
Replace
BOOST_ID_Nwith the control IDs that youcreated in the previous step.
Create and attach filter serving controls
A filter serving control filters by a given criteria or rule. For example, forhotel site, you can apply a filter for(price < 175 AND petfriendly = "true")that only shows pet-friendly hotels under the price of $175 USD per night.
A filter serving control is defined as a control with afilterAction.
Use the following instructions to create a filter serving control.
For field details, see theengines.controls API reference and theengines.controls.create API reference.
Console
In the Google Cloud console, go to theAI Applications page.
Select the app for which you want to create the filter control.
On your app's overview page, make sure you are on theSystem overview tab.
In theSignalstage, click theFilter tile.
ClickCreate control.
In theCreate control pane, do the following:
ForName Your Control, enter a name for your filter control and clickContinue.
ForRule Scope & Impact, set the following:
Select a data store from the list that you want to attach this filter control to. If you want the action to be applied to multiple data stores, create a control for each data store.
ForFilter, tell the rule which specific items to look for. You can combine search terms usingAND,OR,NOT, and group terms with(). For exact phrases, use quotes"". An example:category: "electronics" AND price < 500, status: "open" AND priority:"P1".
To understand how to write filter expressions, seeFilter expression syntax andExamples of filter expressions.
ClickContinue.
ForOptional: When This Rule Activates, define the actions that you want to trigger with this control. If no conditions are configured, the control is always in effect:
AddPartial match query terms. The control takes effect when thesequery terms match partially.
AddExact match query terms. The control takes effect when these queryterms match exactly.
To add an active time range, clickAdd time range and setStart time 1 andEnd time 1. This defines the window when thecondition is active. You can add a maximum of 10 time ranges.
ClickContinue.
If you want to apply this control as soon as it's created, forAdditional settings, turn onPublish this control immediately and clickContinue
ClickSubmit.
REST
Find your app ID. If you already have your app ID, skip to the next step.
In the Google Cloud console, go to theAI Applications page.
On theApps page, find the name of your app and get the app's ID fromtheID column.
Run the following curl commands to create your controls.
curl-XPOST\-H"Authorization: Bearer$(gcloudauthprint-access-token)"\-H"Content-Type: application/json"\-H"X-Goog-User-Project:PROJECT_ID"\"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID"\-d'{"displayName": "DISPLAY_NAME","solutionType": "SOLUTION_TYPE_SEARCH","useCases": ["USE_CASE"],"conditions": { "queryTerms": [ { "value": "VALUE", "fullMatch":FULL_MATCH } ], "activeTimeRange": [ { "startTime": "START_TIMESTAMP", "endTime": "END_TIMESTAMP" } ]},"filterAction": { "filter": "FILTER" }}'
Replace the following:
PROJECT_ID: the number or ID of your Google Cloud project.APP_ID: the ID of the Vertex AI Search app.CONTROL_ID: a unique identifier for the control.The ID can contain [1-63] characters that can be letters, digits, hyphens,and underscores.DISPLAY_NAME: the human-readable name for the control.Google recommends that this name provide an indication of when or why touse the control. Must be a UTF-8 encoded string with length [1,128].USE_CASE: must be eitherSEARCH_USE_CASE_SEARCHorSEARCH_USE_CASE_BROWSE. IfSEARCH_USE_CASE_BROWSEis specified,thenCondition.queryTermscan't be used in the condition.CONDITION: an optional field that defines when thecontrol should be applied. Contains the following fields:VALUE: the specific query value to matchagainst. It's a lowercase UTF-8 string with length[1, 5000]. IfFULL_MATCH_1istrue, this field can have atmost three space-separated terms.FULL_MATCH: a boolean that indicates whetherthe search query needs to exactly match the query term. When set totrue, it requiresSearchRequest.queryto completely match thequeryTerm.value. When set tofalse, it requiresSearchRequest.queryto containqueryTerm.valueas a substring.START_TIMESTAMP: a timestamp in RFC 3339 UTC"Zulu" format to indicate the start of a time range.END_TIMESTAMP: a timestamp in RFC 3339 UTC"Zulu" format to indicate the end of a time range.
FILTER: a string specifying requirements that mustbe met by the document. If the document matches all the requirements, thedocument is returned in the results. Otherwise the document is not in theresults.For the filtering syntax, seeFilter expression syntax.For more information, see
filterAction.Note: The document fieldtitlecan't be filtered.
Attach the control to the app's serving config using the
engines.servingConfigs.patchmethod.curl-XPATCH\-H"Authorization: Bearer$(gcloudauthprint-access-token)"\-H"Content-Type: application/json"\-H"X-Goog-User-Project:PROJECT_ID"\"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=filter_control_ids"\-d'{ "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2"]}'
Replace
FILTER_ID_Nwith the control IDs that youcreated in the previous step.
Create and attach synonyms serving controls
A synonyms serving control is defined as a control with asynonymsAction.
Use the following instructions to create a synonyms serving control.
For field details, see theengines.controls API reference and theengines.controls.create API reference.
Console
In the Google Cloud console, go to theAI Applications page.
Select the app for which you want to create the synonyms control.
On your app's overview page, make sure you are on theSystem overview tab.
In thePreparestage, click theSynonyms tile.
ClickCreate control.
In theCreate control pane, do the following:
ForName Your Control, enter a name for your synonyms control and clickContinue.
ForRule Scope & Impact:
Enter the synonyms you want to have considered in the control. Forexample, entercats followed by a return (not comma), thenfeline.
When you are finished entering synonyms, clickContinue.
ForOptional: When This Rule Activates, define the actions that you want to trigger with this control. If no conditions are configured, the control is always in effect:
To add an active time range, clickAdd time range and setStart time 1 andEnd time 1. This defines the window when thecondition is active. You can add a maximum of 10 time ranges.
ClickContinue.
If you want to apply this control as soon as it's created, forAdditional settings, turn onPublish this control immediately and clickContinue
ClickSubmit.
REST
Run the following curl commands to create your controls.
curl-XPOST\-H"Authorization: Bearer$(gcloudauthprint-access-token)"\-H"Content-Type: application/json"\-H"X-Goog-User-Project:PROJECT_ID"\"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID"\-d'{"displayName": "DISPLAY_NAME","solutionType": "SOLUTION_TYPE_SEARCH","useCases": ["USE_CASE"],"conditions": { "queryTerms": [ { "value": "VALUE", "fullMatch":FULL_MATCH } ], "activeTimeRange": [ { "startTime": "START_TIMESTAMP", "endTime": "END_TIMESTAMP" } ]},"synonymsAction": { "synonyms": ["SYNONYMS_1","SYNONYMS_2"] }}'
Replace the following:
PROJECT_ID: the number or ID of your Google Cloud project.APP_ID: the ID of the Vertex AI Search app.CONTROL_ID: a unique identifier for the control.The ID can contain [1-63] characters that can be letters, digits, hyphens,and underscores.DISPLAY_NAME: the human-readable name for the control.Google recommends that this name provide an indication of when or why touse the control. Must be a UTF-8 encoded string with length [1,128].USE_CASE: must be eitherSEARCH_USE_CASE_SEARCHorSEARCH_USE_CASE_BROWSE. IfSEARCH_USE_CASE_BROWSEis specified,thenCondition.queryTermscan't be used in the condition.CONDITION: an optional field that defines when thecontrol should be applied. Contains the following fields:VALUE: the specific query value to matchagainst. It's a lowercase UTF-8 string with length[1, 5000]. IfFULL_MATCH_1istrue, this field can have atmost three space-separated terms.FULL_MATCH: a boolean that indicates whetherthe search query needs to exactly match the query term. When set totrue, it requiresSearchRequest.queryto completely match thequeryTerm.value. When set tofalse, it requiresSearchRequest.queryto containqueryTerm.valueas a substring.START_TIMESTAMP: a timestamp in RFC 3339 UTC"Zulu" format to indicate the start of a time range.END_TIMESTAMP: a timestamp in RFC 3339 UTC"Zulu" format to indicate the end of a time range.
SYNONYMS_N: a list of strings that are associatedwith each other, making it more likely for each to show similar results.While it's more likely that you get similar results, when yousearch for each of the synonym entries, you might not receive all therelevant results for all the associated synonyms.You must specify at least two synonyms and you can specify up to 100synonyms. Each synonym must be UTF-8 encoded and in lowercase. No duplicatestrings are allowed. For example, you can add "pixel", "android phone", and"google phone" as synonyms.For more information, seesynonymsAction.
Attach the control to the app's serving config using the
engines.servingConfigs.patchmethod.curl-XPATCH\-H"Authorization: Bearer$(gcloudauthprint-access-token)"\-H"Content-Type: application/json"\-H"X-Goog-User-Project:PROJECT_ID"\"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=synonyms_control_ids"\-d'{ "synonymsControlIds": ["SYNONYMS_ID_1", "SYNONYMS_ID_2"]}'
Replace
SYNONYMS_ID_Nwith the control IDs that youcreated in the previous step.
Create and attach redirect serving controls
A redirect serving control allows redirecting users to a provided URI.Redirect controls are defined as a control with aredirectAction.
Use the following instructions to create a redirect serving control.
For field details, see theengines.controls API reference and theengines.controls.create API reference.
Find your app ID. If you already have your app ID, skip to the next step.
In the Google Cloud console, go to theAI Applications page.
On theApps page, find the name of your app and get the app's ID fromtheID column.
Run the following curl commands to create your controls.
curl-XPOST\-H"Authorization: Bearer$(gcloudauthprint-access-token)"\-H"Content-Type: application/json"\-H"X-Goog-User-Project:PROJECT_ID"\"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID"\-d'{"displayName": "DISPLAY_NAME","solutionType": "SOLUTION_TYPE_SEARCH","useCases": ["USE_CASE"],"conditions": { "queryTerms": [ { "value": "VALUE", "fullMatch":FULL_MATCH } ], "activeTimeRange": [ { "startTime": "START_TIMESTAMP", "endTime": "END_TIMESTAMP" } ]},"redirectAction": { "redirectURI": "REDIRECT_URI" }}'
Replace the following:
PROJECT_ID: the number or ID of your Google Cloud project.APP_ID: the ID of the Vertex AI Search app.CONTROL_ID: a unique identifier for the control.The ID can contain [1-63] characters that can be letters, digits, hyphens,and underscores.DISPLAY_NAME: the human-readable name for the control.Google recommends that this name provide an indication of when or why touse the control. Must be a UTF-8 encoded string with length [1,128].USE_CASE: must be eitherSEARCH_USE_CASE_SEARCHorSEARCH_USE_CASE_BROWSE. IfSEARCH_USE_CASE_BROWSEis specified,thenCondition.queryTermscan't be used in the condition.CONDITION: an optional field that defines when thecontrol should be applied. Contains the following fields:VALUE: the specific query value to matchagainst. It's a lowercase UTF-8 string with length[1, 5000]. IfFULL_MATCH_1istrue, this field can have atmost three space-separated terms.FULL_MATCH: a boolean that indicates whetherthe search query needs to exactly match the query term. When set totrue, it requiresSearchRequest.queryto completely match thequeryTerm.value. When set tofalse, it requiresSearchRequest.queryto containqueryTerm.valueas a substring.START_TIMESTAMP: a timestamp in RFC 3339 UTC"Zulu" format to indicate the start of a time range.END_TIMESTAMP: a timestamp in RFC 3339 UTC"Zulu" format to indicate the end of a time range.
REDIRECT_URI_N: a URI where you are redirected. Canhave a maximum length of 2000 characters. For example, if the value of thequery term is "support", you can set a redirect to your technical supportpage instead of returning (or failing to return) search results for"support". In this example, the redirect URI becomes"https://www.example.com/support".For more information, seeredirectAction.
Attach the control to the app's serving config using the
engines.servingConfigs.patchmethod.curl-XPATCH\-H"Authorization: Bearer$(gcloudauthprint-access-token)"\-H"Content-Type: application/json"\-H"X-Goog-User-Project:PROJECT_ID"\"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=redirect_control_ids"\-d'{ "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2"]}'
Replace
REDIRECT_ID_Nwith the control IDs that youcreated in the previous step.
Create and attach promote serving controls
A promote serving control lets you display a link as a promoted result andis available for the following types of search data stores:
Website data stores with basic website search: For these data stores, youdon't need to attach a promote control to the serving config of the app.Creating and enabling a promote control activates the promotecontrol. You can turn a promote control on or off by enablingor disabling it.
Data stores with structured and unstructured data, website datawith advanced website indexing, and blended search apps: For thesedata stores, you need to attach the promote control to theserving config.
Promote controls are defined using apromoteAction.
To successfully create a promote control, one of the following fields isrequired in the creation request:
queryTerms: This condition can't be specified if you're specifying thequeryRegexcondition, which is applicable to basic website search only.For basic website search,fullMatchmust be set totrueifqueryTermsis specified. For all other search apps, onlyqueryTermsissupported andfullMatchcan be set totrueorfalse.queryRegex. Only available for apromote serving controlfor basic website search only. This condition applies the control when thequery matches the specified regular expression. This condition can't bespecified if you're specifying thequeryTermscondition.
That is, for basic website search, you must either specify thequeryTermsfield withfullMatch set totrue or specify thequeryRegex field. For allother types of search, specify thequeryTerms field withfullMatch set totrue orfalse.
Use the following instructions to create a promote serving control.
For field details, see theengines.controls API reference and theengines.controls.create API reference.
Console
In the Google Cloud console, go to theAI Applications page.
Select the app for which you want to create the filter control.
On your app's overview page, make sure you are on theSystem overview tab.
In theSignalstage, click thePromote tile.
ClickCreate control.
In theCreate control pane, do the following:
ForName Your Control, enter a name for your filter control and clickContinue.
ForRule Scope & Impact, set the following:
Select a data store from the list that you want to attach this filter control to. If you want the action to be applied to multiple data stores, create a control for each data store.
Enter thePromote title, such asView latest video.
Enter thePromote URL, such as the location of the video.
Enter thePromote image URL, such as a thumbnail or screenshot.
Enter a briefPromote description, such as what the video is about. The maximum is 250 characters.
ForOptional: When This Rule Activates, define the actions that you want to trigger with this control. If no conditions are configured, the control is always in effect:
AddExact match query terms. The control takes effect when these queryterms match exactly.
To add an active time range, clickAdd time range and setStart time 1 andEnd time 1. This defines the window when thecondition is active. You can add a maximum of 10 time ranges.
ClickContinue.
ClickSubmit.
REST
Run the following curl commands to create your controls.
curl-XPOST\-H"Authorization: Bearer$(gcloudauthprint-access-token)"\-H"Content-Type: application/json"\-H"X-Goog-User-Project:PROJECT_ID"\"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID"\-d'{"displayName": "DISPLAY_NAME","solutionType": "SOLUTION_TYPE_SEARCH","useCases": ["USE_CASE"],"conditions": { "queryTerms": [ { "value": "VALUE", "fullMatch": true } ], "activeTimeRange": [ { "startTime": "START_TIMESTAMP", "endTime": "END_TIMESTAMP" } ], "queryRegex": "VALUE_REGEX"},"promoteAction": { "dataStore": "DATA_STORE_RESOURCE_PATH", "searchLinkPromotion": { "document": "DOCUMENT_RESOURCE_PATH", "title": "TITLE", "uri": "URI", "description": "DESCRIPTION", "enabled":ENABLED_TRUE|FALSE, } }}'
Replace the following:
PROJECT_ID: the number or ID of your Google Cloud project.APP_ID: the ID of the Vertex AI Search app.CONTROL_ID: a unique identifier for the control.The ID can contain [1-63] characters that can be letters, digits, hyphens,and underscores.DISPLAY_NAME: the human-readable name for the control.Google recommends that this name provide an indication of when or why touse the control. Must be a UTF-8 encoded string with length [1,128].USE_CASE: must be eitherSEARCH_USE_CASE_SEARCHorSEARCH_USE_CASE_BROWSE. IfSEARCH_USE_CASE_BROWSEis specified,thenCondition.queryTermscan't be used in the condition.Condition: an optional object that defines when thecontrol should be applied. Contains the following fields:queryTerms: It can't be used with thequeryRegexfield.VALUE: the specific query value to matchagainst. It's a lowercase UTF-8 string with length[1, 5000].
activeTimeRange:START_TIMESTAMP: a timestamp in RFC 3339 UTC"Zulu" format to indicate the start of a time range.END_TIMESTAMP: a timestamp in RFC 3339 UTC"Zulu" format to indicate the end of a time range.
queryRegex: only available for data stores withbasic website search. This field can't be used with thequeryTermsfield.VALUE_REGEX: a regular expression to matchthe query against.
DATA_STORE_RESOURCE_PATH: the full resource path ofthe data store whose search results contain the promoted URL. Theformat of the full resource path isprojects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID.This data store must be attached to the engine specified in the request.DOCUMENT_RESOURCE_PATH: a field to specify the document resource path ofthe document to be promoted:- For search data stores with structured and unstructured data, you mustprovide either the document resource path in the
DOCUMENT_RESOURCE_PATHfield, the URI in theURIfield, or both. The format of the fullresource path isprojects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID. - For website data stores, this field must be unset and set the URI fieldinstead.
- For search data stores with structured and unstructured data, you mustprovide either the document resource path in the
TITLE: a required field to specify the titleof the document or the web page to be promoted. This title is displayed inthe search result.URI: a required field to specify the URI link wherethe search result leads the user. This URI need not be included in thedata store.- For search data stores with structured and unstructured data, you mustprovide either the document resource path in the
DOCUMENT_RESOURCE_PATHfield, the URI in theURIfield, or both. - For website data stores, this is a requiredfield and you must set it.
- For search data stores with structured and unstructured data, you mustprovide either the document resource path in the
DESCRIPTION: an optional field to describe thedocument or web page to be promoted, which is displayed in the searchresult.ENABLED_TRUE|FALSE: an optional boolean field toindicate whether the promote control is turned on and attached to the app.This field is applicable to website data stores withbasic website search only.When you set this field tofalse, the promote serving control is turnedoff and for the control to take effect, you must update the control byenabling it, as explained in the next step.For more information, seepromoteAction.
Response
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/controls/PROMOTE_CONTROL_ID", "displayName": "PROMOTE_CONTROL_NAME", "solutionType": "SOLUTION_TYPE_SEARCH", "conditions": [ { "queryTerms": [ { "value": "VALUE", "fullMatch": true } ] } ], "useCases": [ "SEARCH_USE_CASE_SEARCH" ], "promoteAction": { "dataStore": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/dataStores/DATA_STORE_ID", "searchLinkPromotion": { "title": "URI_TITLE", "uri": "URI", "description": "URI_DESCRIPTION", "enabled":ENABLED_TRUE|FALSE } }}For all search apps except for basic website search, attach the controlto the app's serving config using the
engines.servingConfigs.patchmethod. The order in which thepromoteControlIdsare attached in the following request is the order inwhich the promoted results are returned.curl-XPATCH\-H"Authorization: Bearer$(gcloudauthprint-access-token)"\-H"Content-Type: application/json"\-H"X-Goog-User-Project:PROJECT_ID"\"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=promote_control_ids"\-d'{ "promoteControlIds": ["PROMOTE_ID_1", "PROMOTE_ID_2"]}'
Replace
PROMOTE_ID_Nwith the control IDs that youcreated in the previous step.Optional: For basic website search, you need not attach the control to theapp's serving config. However, for basic website search you can turn apromote control on or off after the control is created,call the
engines.control.patchmethod.curl-XPATCH\-H"Authorization: Bearer$(gcloudauthprint-access-token)"\-H"Content-Type: application/json"\-H"X-Goog-User-Project:PROJECT_ID"\"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID?updateMask=promoteAction.searchLinkPromotion.enabled"\-d'{"promoteAction": { "searchLinkPromotion": { "enabled":ENABLED_TRUE|FALSE, }}}'
Example
When you send a search request to the app with a query that matches the queryor query regular expression specified for the promote control, the promoted link appears inthe response.
For example, suppose that you create a promote control with the followingconfiguration in a data store with basic website search:
{ "conditions": [ { "queryTerms": [ { "value": "artificial intelligence", "fullMatch": true } ] } ]" ... promoteAction": { "dataStore": "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/dataStores/basic-website-data-store" \ "searchLinkPromotion": { "title": "What is AI?", "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence", "description": "Explain what is AI" "enabled": true } }}Then, you send the followingsearch request:
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/engines/basic-website-app/servingConfigs/default_search:search" \ -d '{"query": "artificial intelligence"}'You should receive a JSON response similar to the following truncated response.The response contains thesearchLinkPromotions field that contains thepromoted link.
{ "results": [...], "totalSize": 3, "attributionToken": "_gHw_QoMCMSbhboGELuI1qwCEiQ2NzQwYmYzYi0wMDAwLTJmYTctYTk1OC0yNDA1ODg4MzZmYjgiB0dFTkVSSUMqvAGrxIotzua1L5neqC_n7YgtxPzLMIOymiK0kq4wxPi8MPn2sy3LmrQw6d3EMNSynRWc1rctnN3YMOuCsS3ogrEto4CXIsLwnhX89rMtkKS0MJbeqC-jibMtkPeyMMTGsTCZ3dgw5O2ILa7Eii2NpLQw5t3EMN6PmiKOvp0VwfzLMICymiKq-LMt0ea1L634sy3Fy_MXtreMLbeSrjDHxrEwzpq0MMH4vDCgibMtn9a3LZSSxTCOkckw24-aIjAB", "guidedSearchResult": {}, "summary": {}, "searchLinkPromotions": [ { "title": "What is AI?", "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence", "description": "Explain what is AI" } ]}Modify serving controls
To modify a control's configuration, do the following:
In the Google Cloud console, go to theAI Applications page.
Select the app for which you want to modify controls.
In theSystem overview tab, select either thePrepare orSignal stage where your control is located.
In the list of the app's controls, click for a control that you want to modify and clickEdit.
Edit the control in theEdit control pane.
To enable or disable a control, in the list of theapp's filter controls, clickfor a control that you want to enable or disable and clickEnable orDisable, respectively.
To delete a control, in the list of theapp's controls, clickfor a control that you want to delete and clickDelete.
What's next
- To understand the impact of a serving control on the search quality of acustom search app, evaluate the search quality. For more information, seeEvaluate search quality.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-19 UTC.