Configure autocomplete

This page describes Vertex AI Search's basic autocomplete feature. Autocomplete generates query suggestions based on the first few characters entered for the query.

Notes:

For information about search-as-you-type for media search apps, see Get search-as-you-type results for a media app.

To use autocomplete with search apps that are connected to multiple data stores (blended search) or have documents with access control or to boost specific languages within autocomplete, see Configure advanced autocomplete.

The suggestions that autocomplete generates vary depending on the type of data that the search app uses:

• Structured and unstructured data. By default, autocomplete generates suggestions based on the content of documents in the data store. After document import, by default, autocomplete doesn't start generating suggestions until there is sufficient quality data, typically a couple of days. If you make autocomplete requests through the API, autocomplete can generate suggestions that are based on the search history or user events.

• Website data. By default, autocomplete generates suggestions from the search history. Autocomplete requires real search traffic. After search traffic begins, autocomplete takes a day or two before generating suggestions. Suggestions can be generated from web-crawled data from public sites with the experimental advanced document data model.

• Healthcare data. By default, a canonical medical data source is used to generate autocomplete suggestions for healthcare data stores. For healthcare search, autocomplete is a Preview feature.

The autocomplete data model determines what type of data autocomplete uses to generate suggestions. There are four autocomplete models:

• Document. The document model generates suggestions from user-imported documents. This model isn't available for website data or healthcare data.

• Completable Fields. The completable fields model suggests text taken directly from structured data fields. Only those fields that are annotated with completable are used for autocomplete suggestions. This model is only available for structured data.

• Search history. The search history model generates suggestions from the history of SearchService.search API calls. Don't use this model if there is no traffic available for the servingConfigs.search method. This model isn't available for healthcare data.

• User event. The user event model generates suggestions from user-imported search events. This model isn't available for healthcare data.

Autocomplete requests are sent using the dataStores.completeQuery method.

The following table shows the autocomplete model types available for each data type.

Autocomplete data model	Data source	Website data	Structured data	Unstructured data
Document	Imported by user		✔* (default)	✔ (default)
Completable fields	Imported by user		✔
Search history	Automatically collected	✔ (default)	✔	✔
User events	Imported by user or automatically collected by widget	✔	✔	✔
Web-crawled content	Crawled from content from public websites specified by user	✔^†

* : The document schema must contain title or description fields, or there must be fields that have been specified as title or description key properties. See Update a schema for structured data.

^† : Web-crawled content can only be used as a data source if the experimental advanced document data model for autocomplete is enabled. See Advanced document data model.

If you don't want to use the default model for your data type, you can specify a different model when you send your autocomplete request. Autocomplete requests are sent using the dataStores.completeQuery method. For information, see API instructions: Send an autocomplete request to choose a different model.

Autocomplete features

Vertex AI Search supports the following autocomplete features to show the most helpful predictions when searching:

Feature	Description	Example or more information
Correct typos	Correct word spellings that are typos.	Milc → Milk.
Remove unsafe terms	Powered by Google Safe Search. Remove inappropriate queries. Supported in English (en), French (fr), German (de), Italian (it), Polish (pl), Portuguese (pt), Russian (ru), Spanish (es), and Ukranian (uk).	Text that's offensive, such as porn, racy, vulgar, violence.
Denylist	Remove terms that are listed in the denylist.	For more information, see Use an autocomplete denylist.
Deduplicate Terms	Powered by AI-driven semantic understanding. For near-identical terms, either term matches, but only the more popular one is suggested.	Shoes for Women, Womens Shoes, and Womans Shoes are deduplicated, and only the most popular one is suggested.
Tail match suggestions	Not available in US and EU multi-regions. Optional setting. If there are no autocomplete matches for the entire query, suggest matches for only the trailing word of the query. Not available for healthcare search.	For more information, see Tail match suggestions.

Tail match suggestions

Tail match suggestions are made using exact prefix matching against the last word in a query string.

For example, say the query "songs with he" is sent in an autocomplete request. When tail matching is enabled, autocomplete might find that the full prefix "songs with he" does not have any matches. However, the last word in the query, "he", has an exact prefix match with "hello world" and "hello kitty". In that case, the returned suggestions are "songs with hello world" and "songs with hello kitty" because there are no full match suggestions.

You can use this feature to reduce empty suggestion results and increase suggestion diversity, making this especially useful in cases where data sources (user event count, search history, and document topic coverage) is limited. However, enabling tail match suggestions can reduce the overall quality of suggestions. Because tail match only matches the trailing word of the prefix, some returned suggestions might not make sense. For example, a query such as "songs with he" might get a tail match suggestion like "songs with helpers guides".

Tail match suggestions are only returned if:

1. include_tail_suggestions is set to true in the dataStores.completeQuery request.

2. There are no full prefix match suggestions for the query.

Turn autocomplete on or off for a widget

To turn autocomplete on or off for a widget, follow these steps:

Console

1. In the Google Cloud console, go to the Agent Builder page.

   Agent Builder

2. Click the name of the app that you want to edit.

3. Click Configurations.

4. Click the UI tab.

5. Toggle the Show autocomplete suggestions option to turn autocomplete suggestions for the widget on or off. When you enable autocomplete, expect to wait a day or two before suggestions start. For healthcare search, autocomplete is a Preview feature.

Update autocomplete settings

To configure the autocomplete settings, follow these steps:

Console

1. In the Google Cloud console, go to the Agent Builder page.

   Agent Builder

2. Click the name of the app that you want to edit.

3. Click Configurations.

4. Click the Autocomplete tab.

5. Enter or select new values for the autocomplete settings you want to update:

   • Maximum number of suggestions: The maximum number of autocomplete suggestions that can be offered for a query.
   • Minimum length to trigger: The minimum number of characters that can be typed before autocomplete suggestions are offered.
   • Matching order: The location in a query string that autocomplete can start matching its suggestions from.
   • Autocomplete model: The autocomplete data model used to generate the retrieved suggestions. This can be overridden in the dataStores.completeQuery using the queryModel parameter.

   • Enable autocomplete: By default, autocomplete doesn't start making suggestions until it has sufficient quality data, typically a couple of days. If you want to override this default and start getting some autocomplete suggestions sooner, select Now.

     Even when you select Now, it can take a day for suggestions to be generated and still some autocomplete suggestions will be missing or poor quality until there is sufficient good data.

6. Click Save and publish. Changes take effect within a few minutes for engines where autocomplete has already been turned on.

Update completable field annotations in schema

To turn on autocomplete for fields in structured data schema, follow these steps:

Console

1. In the Google Cloud console, go to the Agent Builder page.

   Agent Builder

2. Click the name of the app that you want to edit. It must use structured data.

3. Click Data.

4. Click the Schema tab.

5. Click Edit to select the schema fields to mark as completable.

6. Click Save to save the updated field configurations. These suggestions take around a day to be generated and returned.

Send autocomplete requests

The following samples show how to send autocomplete requests.

REST

To send an autocomplete request using the API, follow these steps:

1. 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.

2. Call the dataStores.completeQuery method.

   curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/dataStores/DATA_STORE_ID:completeQuery?query=QUERY_STRING"
   

   • PROJECT_ID: The project number or ID of your Google Cloud project.

   • LOCATION: The location of your data store: us, eu or global.

   • DATA_STORE_ID: The ID of the data store that is associated with your app.

   • QUERY_STRING: The typeahead input used to fetch suggestions.

Send an autocomplete request to a different model

To send an autocomplete request with a different autocomplete data model, follow these steps:

1. 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.

2. Call the dataStores.completeQuery method.

   curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/dataStores/DATA_STORE_ID:completeQuery?query=QUERY_STRING&query_model=AUTOCOMPLETE_MODEL"
   

   • PROJECT_ID: The project number or ID of your Google Cloud project.
   • LOCATION: The location of your data store: us, eu or global.
   • DATA_STORE_ID: The unique ID of the data store that is associated with your app.
   • QUERY_STRING: The typeahead input used to fetch suggestions.
   • AUTOCOMPLETE_MODEL: The autocomplete data model to use for the request: document, document-completable, search-history, or user-event. For healthcare data, use healthcare-default.

C#

For more information, see the Vertex AI Agent Builder C# API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

using Google.Cloud.DiscoveryEngine.V1;

public sealed partial class GeneratedCompletionServiceClientSnippets
{
    /// <summary>Snippet for CompleteQuery</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void CompleteQueryRequestObject()
    {
        // Create client
        CompletionServiceClient completionServiceClient = CompletionServiceClient.Create();
        // Initialize request argument(s)
        CompleteQueryRequest request = new CompleteQueryRequest
        {
            DataStoreAsDataStoreName = DataStoreName.FromProjectLocationDataStore("[PROJECT]", "[LOCATION]", "[DATA_STORE]"),
            Query = "",
            QueryModel = "",
            UserPseudoId = "",
            IncludeTailSuggestions = false,
        };
        // Make the request
        CompleteQueryResponse response = completionServiceClient.CompleteQuery(request);
    }
}

Go

For more information, see the Vertex AI Agent Builder Go API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewCompletionClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.CompleteQueryRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb#CompleteQueryRequest.
	}
	resp, err := c.CompleteQuery(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

For more information, see the Vertex AI Agent Builder Java API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.discoveryengine.v1.CompleteQueryRequest;
import com.google.cloud.discoveryengine.v1.CompleteQueryResponse;
import com.google.cloud.discoveryengine.v1.CompletionServiceClient;
import com.google.cloud.discoveryengine.v1.DataStoreName;

public class SyncCompleteQuery {

  public static void main(String[] args) throws Exception {
    syncCompleteQuery();
  }

  public static void syncCompleteQuery() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (CompletionServiceClient completionServiceClient = CompletionServiceClient.create()) {
      CompleteQueryRequest request =
          CompleteQueryRequest.newBuilder()
              .setDataStore(
                  DataStoreName.ofProjectLocationDataStoreName(
                          "[PROJECT]", "[LOCATION]", "[DATA_STORE]")
                      .toString())
              .setQuery("query107944136")
              .setQueryModel("queryModel-184930495")
              .setUserPseudoId("userPseudoId-1155274652")
              .setIncludeTailSuggestions(true)
              .build();
      CompleteQueryResponse response = completionServiceClient.completeQuery(request);
    }
  }
}

Node.js

For more information, see the Vertex AI Agent Builder Node.js API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. The parent data store resource name for which the completion is
 *  performed, such as
 *  `projects/* /locations/global/collections/default_collection/dataStores/default_data_store`.
 */
// const dataStore = 'abc123'
/**
 *  Required. The typeahead input used to fetch suggestions. Maximum length is
 *  128 characters.
 */
// const query = 'abc123'
/**
 *  Specifies the autocomplete data model. This overrides any model specified
 *  in the Configuration > Autocomplete section of the Cloud console. Currently
 *  supported values:
 *  * `document` - Using suggestions generated from user-imported documents.
 *  * `search-history` - Using suggestions generated from the past history of
 *  SearchService.Search google.cloud.discoveryengine.v1.SearchService.Search 
 *  API calls. Do not use it when there is no traffic for Search API.
 *  * `user-event` - Using suggestions generated from user-imported search
 *  events.
 *  * `document-completable` - Using suggestions taken directly from
 *  user-imported document fields marked as completable.
 *  Default values:
 *  * `document` is the default model for regular dataStores.
 *  * `search-history` is the default model for site search dataStores.
 */
// const queryModel = 'abc123'
/**
 *  A unique identifier for tracking visitors. For example, this could be
 *  implemented with an HTTP cookie, which should be able to uniquely identify
 *  a visitor on a single device. This unique identifier should not change if
 *  the visitor logs in or out of the website.
 *  This field should NOT have a fixed value such as `unknown_visitor`.
 *  This should be the same identifier as
 *  UserEvent.user_pseudo_id google.cloud.discoveryengine.v1.UserEvent.user_pseudo_id 
 *  and
 *  SearchRequest.user_pseudo_id google.cloud.discoveryengine.v1.SearchRequest.user_pseudo_id.
 *  The field must be a UTF-8 encoded string with a length limit of 128
 *  characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
 */
// const userPseudoId = 'abc123'
/**
 *  Indicates if tail suggestions should be returned if there are no
 *  suggestions that match the full query. Even if set to true, if there are
 *  suggestions that match the full query, those are returned and no
 *  tail suggestions are returned.
 */
// const includeTailSuggestions = true

// Imports the Discoveryengine library
const {CompletionServiceClient} = require('@google-cloud/discoveryengine').v1;

// Instantiates a client
const discoveryengineClient = new CompletionServiceClient();

async function callCompleteQuery() {
  // Construct request
  const request = {
    dataStore,
    query,
  };

  // Run request
  const response = await discoveryengineClient.completeQuery(request);
  console.log(response);
}

callCompleteQuery();

Python

For more information, see the Vertex AI Agent Builder Python API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import discoveryengine_v1


def sample_complete_query():
    # Create a client
    client = discoveryengine_v1.CompletionServiceClient()

    # Initialize request argument(s)
    request = discoveryengine_v1.CompleteQueryRequest(
        data_store="data_store_value",
        query="query_value",
    )

    # Make the request
    response = client.complete_query(request=request)

    # Handle the response
    print(response)

Ruby

For more information, see the Vertex AI Agent Builder Ruby API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

require "google/cloud/discovery_engine/v1"

##
# Snippet for the complete_query call in the CompletionService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1::CompletionService::Client#complete_query.
#
def complete_query
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1::CompletionService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1::CompleteQueryRequest.new

  # Call the complete_query method.
  result = client.complete_query request

  # The returned object is of type Google::Cloud::DiscoveryEngine::V1::CompleteQueryResponse.
  p result
end

Use an autocomplete denylist

You can use a denylist to prevent specific terms from appearing as autocomplete suggestions.

For example, take a pharmaceutical company. If a medication is no longer FDA-approved but is mentioned in documents in their data store, they might want to prevent that medication from appearing as a suggested query. The company could add the name of that medication to a denylist to prevent it from being suggested.

The following limits apply:

• One denylist per data store
• Uploading a denylist overwrites any existing denylist for that data store
• Up to 1000 terms per denylist
• Terms are case-insensitive
• After importing a denylist, it takes 1-2 days to take effect

Each entry of your denylist consists of a blockPhrase and matchOperator:

• blockPhrase: Enter a string as your denylist term. Terms are case-insensitive.
• matchOperator: Accepts the following values:
  • EXACT_MATCH: Prevents an exact match of the denylist term from appearing as a suggested query.
  • CONTAINS: Prevents any suggestion that contains the denylist term from appearing.

The following is an example of a denylist with four entries:

{
    "entries": [
        {"blockPhrase":"Oranges","matchOperator":"CONTAINS"},
        {"blockPhrase":"bAd apples","matchOperator":"EXACT_MATCH"},
        {"blockPhrase":"Cool as A Cucumber","matchOperator":"EXACT_MATCH"},
        {"blockPhrase":"cherry pick","matchOperator":"CONTAINS"}
    ]
}

Prior to importing a denylist, verify that the necessary access controls are set for Discovery Engine editor access.

Denylists can be imported either from local JSON data or from Cloud Storage. To remove a denylist from a data store, purge the denylist.

Import a denylist from local JSON data

To import a denylist from a local JSON file containing your denylist, do the following:

1. Create your denylist in a local JSON file with the following format. Make sure each denylist entry is in a new line with no line breaks.

   {
       "inlineSource": {
           "entries": [
               { "blockPhrase":"TERM_1","matchOperator":"MATCH_OPERATOR_1" },
               { "blockPhrase":"TERM_2","matchOperator":"MATCH_OPERATOR_2" }
           ]
       }
   }
   

2. Make a POST request to the suggestionDenyListEntries:import method, providing the name of your JSON file.

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       --data @DENYLIST_FILE \
     "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataStores/DATA_STORE_ID/suggestionDenyListEntries:import"
   

   • DENYLIST_FILE: The local path of the JSON file containing the denylist terms.
   • PROJECT_ID: The project number or ID of your Google Cloud project.
   • LOCATION: The location of your data store: us, eu or global.
   • DATA_STORE_ID: The ID of the data store that is associated with your app.

After importing your denylist, it takes 1-2 days to start filtering suggestions.

Import a denylist from Cloud Storage

To import a denylist from a JSON file in Cloud Storage, do the following:

1. Create your denylist in a JSON file with the following format and import to a Cloud Storage bucket. Make sure each denylist entry is in a new line with no line breaks.

   { "blockPhrase":"TERM_1","matchOperator":"MATCH_OPERATOR_1" }
   { "blockPhrase":"TERM_2","matchOperator":"MATCH_OPERATOR_2" }
   

2. Create a local JSON file containing the gcsSource object. Use this to point to your denylist file's location in a Cloud Storage bucket.

   {
       "gcsSource": {
           "inputUris": [ "DENYLIST_STORAGE_LOCATION" ]
       }
   }
   

   • DENYLIST_STORAGE_LOCATION: The location of your denylist in Cloud Storage. You can enter only one URI. The URI must be entered in this format: gs://BUCKET/FILE_PATH.

3. Make a POST request to the suggestionDenyListEntries:import method, including the gcsSource object.

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       --data @GCS_SOURCE_FILE \
      "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataStores/DATA_STORE_ID/suggestionDenyListEntries:import"
   

   • GCS_SOURCE_FILE: The local path of the file containing the gcsSource object that points to your denylist.
   • PROJECT_ID: The project number or ID of your Google Cloud project.
   • LOCATION: The location of your data store: us, eu or global.
   • DATA_STORE_ID: The ID of the data store that is associated with your app.

After importing your denylist, it takes 1-2 days to start filtering suggestions.

Purge a denylist

To purge a denylist from your data store, do the following:

1. Make a POST request to the suggestionDenyListEntries:purge method.

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataStores/DATA_STORE_ID/suggestionDenyListEntries:purge"
   

   • PROJECT_ID: The project number or ID of your Google Cloud project.
   • LOCATION: The location of your data store: us, eu or global.
   • DATA_STORE_ID: The ID of the data store that is associated with your app.

Advanced document data model

Experimental

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Vertex AI Agent Builder provides an advanced data model for autocomplete. Based on the documents you import, this data model generates high-quality autocomplete suggestions by leveraging Google large language models (LLMs).

This feature is experimental. If you're interested in using this feature, contact your Google Cloud account team and ask to be added to the allowlist.

This feature is not available for healthcare search or in the US and EU multi-regions.