Vertex AI Search and Conversation has been renamed to Vertex AI Agent Builder. We are in the process of updating content to reflect the new branding.

Configure serving controls

Serving controls change the default behavior of a search request.

To change the results of a request, first create a control, and then attach it to the serving config. A control only affects search requests served by serving configs that the control is attached to. If a control isn't attached to any serving config, it has no effect.

The following types of controls are available. Choose a control based on your use case:

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 metadata, or unstructured data with metadata
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 with metadata, or unstructured data with metadata
Synonyms control	Associates queries with each other	Search apps with structured or unstructured data stores
Redirect control	Redirects to a specified URI	All search apps

When creating a control, you can optionally define a condition that determines when the control is applied. Conditions are defined using condition fields. The following condition fields are available:

queryTerms. The control is applied when specific queries are searched for.
activeTimeRange. The control is applied when a request occurs within a specified time range.

If both types of conditions are specified for a control, the control is applied to the search request when both condition types are satisfied. If multiple values for the same condition are specified, only one of the values needs to match 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 with SearchRequest.query="gShoe" or a request with SearchRequest.query="gBoot", but won't be satisfied with SearchRequest.query="gSandal" or any other string.

If no conditions are specified, the control is always applied.

For more information, see servingConfigs.search in the API reference.

About boost controls

A boost control is defined as a control with a boostAction.

The syntax for a boostAction is as follows:

{
    "boost": "BOOST",
    "filter": "FILTER"
}

BOOST: A float between -1 and 1. When the value is negative, results are demoted to appear later in search results. When the value is positive results are promoted to appear earlier in search results.
FILTER: A string specifying requirements that must be met by the document. If the document matches all the requirements, the boost is applied. Otherwise there is no change. For the filtering syntax, see Filter expression syntax.

About filter controls

A filter control is defined as a control with a filterAction.

The syntax for a filterAction is as follows:

{
    "filter": "FILTER"
}

FILTER: A string specifying requirements that must be met by the document. If the document matches all the requirements, the result is included in the result list. Otherwise, the result is removed from the result list. For the filtering syntax, see Filter expression syntax.

About synonyms controls

A synonyms control is defined as a control with a synonymsAction.

The syntax for a synonymsAction is as follows:

{
    "synonyms": "SYNONYMS"
}

SYNONYMS: Strings that will be associated with each other, making it more likely for each to show similar results. You must specify at least two strings, and you can specify up to 100 strings. Strings must be UTF-8 and lowercase. No duplicate strings are allowed.

For example:

{
    "synonyms": ["pixel", "android phone", "google phone"]
}

About redirect controls

A redirect control allows redirecting users to a provided URI.

Redirect controls are defined as a control with a redirectAction.

Syntax for redirectAction:

{
    "redirect_uri": "REDIRECT_URI"
}

REDIRECT_URI: A URI of at most 2000 characters.

For example, if the value of the query term is "support", you can set a redirect to your technical support page instead of returning (or failing to return) search results for "support".

{
    "redirect_uri": ["https://www.example.com/support"]
}

About the `queryTerms` condition

queryTerms is optional. Use it if you want a control to be used when specific queries are searched for. When the queryTerms condition is used, the control is applied when the value of queryTerms matches a term in SearchRequest.query.

Query terms can only be used when the Control.searchUseCase is set as SOLUTION_TYPE_SEARCH.

Up to 10 different queryTerms can be specified on a single Control.condition. If no query terms are specified, the field is ignored.

The syntax for a single queryTerm is as follows:

{
    "value": "VALUE_1",
    "fullMatch": "FULL_MATCH_1"
}

VALUE_1: A lowercase UTF-8 string with length [1, 5000]. If FULL_MATCH_1 is true, it can have at most three space-separated terms.
FULL_MATCH_1: A boolean. When set to true, it requires SearchRequest.query to completely match the queryTerm.value. When set to false, it requires SearchRequest.query to contain queryTerm.value as a substring.

About the `activeTimeRange` condition

activeTimeRange is optional. It checks that the time a request was received is between activeTimeRange.startTime and activeTimeRange.endTime.

Up to 10 activeTimeRange ranges can be specified on a single Control.condition. If no activeTimeRange ranges are specified, the field is ignored.

The syntax for a single activeTimeRange is as follows:

[
  {
    "startTime": "START_TIMESTAMP_1",
    "endTime": "END_TIMESTAMP_1"
  }
]

START_TIMESTAMP_1: Defines the earliest time (inclusive) that the control will be applied. Timestamps are in RFC 3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits—for example, "2023-10-02T15:01:23Z".
END_TIMESTAMP_1: Defines the latest time (inclusive) that the control will be applied. This time must be in the future.

API instructions: Change default search request behavior with serving controls

To change the default search request behavior, you create a serving control and attach it to the default serving config.

Before you begin

If you want to create serving controls, contact your Google account team and ask to be added to the allowlist for serving controls.

Create a serving control

Use the following instructions to create a serving control.

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

Find your data store ID. If you already have your data store ID, skip to the next step.
1. In the Google Cloud console, go to the Agent Builder page and in the navigation menu, click Data stores.
  
  Go to the Data stores page
2. Click the name of your data store.
3. On the Data page for your data store, get the data store ID.

Choose the condition type and field values for your serving control.

The following is a truncated example of a condition:

{
  "queryTerms": [
      {
        "value": "VALUE_1",
        "fullMatch": FULL_MATCH_1
      },
      {
        "value": "VALUE_2",
        "fullMatch": FULL_MATCH_2
      },
    ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP_1",
      "endTime": "END_TIMESTAMP_1"
    },
    {
      "startTime": "START_TIMESTAMP_2",
      "endTime": "END_TIMESTAMP_2"
    },
  ]
}

Run the following curl commands to create your controls.

Boost control: Click to see the curl command to create a boost control.

Run the following curl command:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-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/dataStores/DATA_STORE_ID/controls?CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "boostAction": "BOOST_ACTION",
    }'

Filter control: Click to see the curl command to create a filter control.

Run the following curl command:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "filterAction": "FILTER_ACTION",
    }'

Synonyms control: Click to see the curl command to create a synonyms control.

Run the following curl command:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "synonymsAction": "SYNONYMS_ACTION",
    }'

Redirect control: Click to see the curl command to create a redirect control.

Run the following curl command:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "redirectAction": "REDIRECT_ACTION",
    }'

PROJECT_ID: The project number or ID of your Google Cloud project.
DATA_STORE_ID: The unique ID of the data store.
CONTROL_ID: A unique identifier (within a data store) for the control. The ID can contain lowercase 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 to use the control. Must be a UTF-8 string with length [1,128].
USE_CASE: Must be either SEARCH_USE_CASE_SEARCH or SEARCH_USE_CASE_BROWSE. If SEARCH_USE_CASE_BROWSE is specified, then Condition.queryTerms can't be used in the condition.
CONDITION: (Optional) Defines when the control should be applied.
BOOST_ACTION: Used to define a boost control. See the boostAction API reference.
FILTER_ACTION: Used to define a filter control. See the filterAction API reference.
SYNONYMS_ACTION: Used to define a synonyms control. See the synonymsAction API reference.
REDIRECT_ACTION: Used to specify a redirection URI. See the redirectAction API reference.

Attach the control to the default serving config.

Boost control: Click for the curl command for a boost control.

Run the following curl command to attach a boost control to a serving configuration to enable use on serving requests:

    curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=boost_control_ids" \
    -d '{
      "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2" … ]
    }'

BOOST_ID_1 and BOOST_ID_2: Represent the control IDs that you created in the previous step.

Filter control: Click the curl command for a filter control.

Run the following curl command to attach a filter control to a serving configuration to enable use on serving requests:

    curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=filter_control_ids" \
    -d '{
      "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2" … ]
    }'

FILTER_ID_1 and FILTER_ID_2: Represent the control IDs that you created in the previous step.

Synonyms control: Click for the curl command for a synonyms control.

Run the following curl command to attach a synonyms control to a serving configuration to enable use on serving requests:

    curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=synonyms_control_ids" \
    -d '{
     "synonymsControlIds": ["SYNONYM_ID_1", "SYNONYM_ID_2" … ]
    }'

SYNONYM_ID_1 and SYNONYM_ID_2: Represent the control IDs that you created in the previous step.

Redirect control: Click for the curl command for a redirect control.

Run the following curl command to attach a redirect control to a serving configuration to enable use on serving requests:

    curl -X PATCH
    -H "Authorization: Bearer $(gcloud auth print-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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=redirect_control_ids" \
    -d '{
      "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2" … ]
    }'

REDIRECT_ID_1 and REDIRECT_ID_2: Represent the control IDs that you created in the previous step.

Configure serving controls

About boost controls

About filter controls

About synonyms controls

About redirect controls

About the queryTerms condition

About the activeTimeRange condition

API instructions: Change default search request behavior with serving controls

Before you begin

Create a serving control

About the `queryTerms` condition

About the `activeTimeRange` condition