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.

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.

* : 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:

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:

Update autocomplete settings

To configure the autocomplete settings, follow these steps:

Update completable field annotations in schema

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

Send autocomplete requests

The following samples show how to send autocomplete requests.

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);
    }
}

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
}

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);
    }
  }
}

/**
 * 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();

# 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)

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/global/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.
   • 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/global/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.
   • 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/global/dataStores/DATA_STORE_ID/suggestionDenyListEntries:purge"
   

   • PROJECT_ID: The project number or ID of your Google Cloud project.
   • DATA_STORE_ID: The ID of the data store that is associated with your app.

Advanced document data model

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.