Configure advanced autocomplete

This page describes Vertex AI Search's advanced autocomplete feature.

In the same way as basic autocomplete, advanced autocomplete generates query suggestions based on the first few characters entered for the query.

Before reading this page, become familiar with Vertex AI Search's basic autocomplete. See Configure autocomplete.

Key features of advanced autocomplete

The key features of advanced autocomplete that distinguish it from the basic autocomplete are as follows:

Blended search: Advanced autocomplete can be used with blended search apps, those are generic search apps that are connected to more than one data store.
Access control: Advanced autocomplete respects access controls. (Access controls are also referred to ACLs, access control lists.) Advanced autocomplete only suggest searches that are related to documents that the searcher has access to. For information about access control, see Use data source access control.
Language boost: Advanced autocomplete can be set to boost suggestions in one or more languages. For example, if the browser language is Dutch, autocomplete suggestions in that language could be boosted. For more information, see Send an autocomplete request with a language boost.
Different types of suggestions: With advanced autocomplete, instead of regular autocomplete query suggestions, you can specify that you want different types of suggestions:
- Rich suggestions: As autocomplete suggestions, users get information about documents where the titles prefix-match the letters that they type. For more information, see Send an autocomplete request and return rich suggestions.
- Recent queries: As autocomplete suggestions, users get their recent queries that prefix-match the letters that they type. For more information, see Send an autocomplete request and return recent queries.

Before you begin

Review and optionally edit the autocomplete settings for your app. See Update autocomplete settings.

Particularly when testing, for smaller data stores, we recommend setting Enable autocomplete to Now. This is because small data stores might not contain sufficient data to provide accurate suggestions.

Send autocomplete requests

The following shows how to send advanced autocomplete requests using the completionConfig.completeQuery method.

REST

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

Find your app ID. If you already have your app ID, skip to the next step.
1. In the Google Cloud console, go to the Agent Builder page.
  
  Go to Apps
2. On the Apps page, find the name of your app and get the app's ID from the ID column.

Call the completionConfig.completeQuery method.

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/completionConfig:completeQuery" \
-d '{
      "query":"QUERY_STRING"
    }'

PROJECT_ID: the ID of your Google Cloud project.
APP_ID: the ID of the Vertex AI Search app.
QUERY_STRING: the typeahead input used to fetch suggestions.

Send an autocomplete request with a language boost

You can boost bury autocomplete suggestions according to language code, for example, make autocomplete suggestions in some languages more or less likely to appear.

The boost value must be between -1 and 1. Setting a negative number "buries" autocomplete suggestions in that language and a positive number boosts the language.

Use two-letter language tags defined by BCP 47—for example, en, fr, hi, and zh.

REST

To send an autocomplete request that includes a language boost value, follow these steps:

Find your app ID. If you already have your app ID, skip to the next step.
1. In the Google Cloud console, go to the Agent Builder page.
  
  Go to Apps
2. On the Apps page, find the name of your app and get the app's ID from the ID column.

Call the completionConfig.completeQuery method.

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/completionConfig:completeQuery" \
-d '{
      "query":"QUERY_STRING",
      "boostSpec": {
         "conditionBoostSpecs": [{
           "condition": "(langCode: ANY(LANG_CODE))",
           "boost": BOOST_VALUE
         }]
      }
    }'

PROJECT_ID: the ID of your Google Cloud project.
APP_ID: the ID of the Vertex AI Search app.
QUERY_STRING: the typeahead input used to fetch suggestions.
LANG_CODE: the two-letter code for one or more languages, in escaped quotes. For example, \"fr\", \"es\" to apply the boost value to Spanish and French.
BOOST_VALUE: a floating point number between -1 and 1. When the value is negative, autosuggestions in the language are demoted (they appear lower down in the list of suggestions). When the value is positive, suggestions are promoted (they appear higher up in the list).

Example command

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/completionConfig:completeQuery" \
-d '{
     "query": { "text": "Co"}
     "boostSpec": {
        "conditionBoostSpecs": [{
          "condition": "(langCode: ANY(\"es\", \"fr\"))",
          "boost": 0.75 }, {
          "condition": "(langCode: ANY(\"en\"))",
          "boost": -1
        }]
      }
    }'

In this example, the autocomplete suggestions for the query Co are boosted (placed higher in the autosuggestion list) if they are in French or Spanish and buried (placed lower in the autosuggestion list) if they are in English.

Send an autocomplete request and return rich suggestions

Rich autocomplete returns content (documents) where the titles contain words that start with the query.

In addition to the title for the document, the autocomplete request returns the source_type and entity_type, and, if available, the key properties: uri, create_time, and update_time. You can view and edit key property mappings on the Schema tab on the data store page.

As with all advanced autocomplete suggestions, ACLs are respected for any documents suggested.

Example

An employee is querying their company intranet site looking for technical information about access permissions.

The employee begins typing tec, and the following documents might be returned: Data technicians handbook, Access technology guide, and Techniques for troubleshooting access issues.

With rich suggestions, for each of these suggested documents, you can display all the following information about the document: the document title (title), a link to the document (uri), when it was last updated (update_time), and the source (source_type), for example, whether the document was found in Confluence Cloud or Slack. Knowing how recently a document was updated and the source for the document helps the employee choose which document to look at first.

Limitations

Rich autocomplete only applies to third-party connectors and only to certain entity data stores for those third-party connectors. The following table shows which entities are supported for which connectors.

Third-party connector	Entities supported
Box	File
Confluence Cloud	Page	Space
Dropbox	File
Jira Cloud	Issue	Space
OneDrive	File
Salesforce	Account	Lead	Opportunity
ServiceNow	Incident	Knowledge
Sharepoint Online	Attachment	Event	File	Page
Slack	Message

Procedure

To send an autocomplete request that returns a rich suggestion, follow these steps:

REST

Find your app ID. If you already have your app ID, skip to the next step.
1. In the Google Cloud console, go to the Agent Builder page.
  
  Go to Apps
2. On the Apps page, find the name of your app and get the app's ID from the ID column.

Call the completionConfig.completeQuery method.


curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/completionConfig:completeQuery" \
-d '{
      "query":"QUERY_STRING",
      "suggestionTypes": ["CONTENT"]
    }'

PROJECT_ID: the ID of your Google Cloud project.
APP_ID: the ID of the Vertex AI Search app.
QUERY_STRING: the typeahead input used to fetch suggestions.

Example command and result

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/completionConfig:completeQuery" \
- d {
      "query": "C",
      "suggestionTypes": ["CONTENT"]
    }'

{
  "contentSuggestions": [{
    "suggestion": "critical crash in payment module",
    "document": {
      "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/10000",
      "derivedStructData": {
        "title": "Critical Crash in Payment Module",
        "uri": "https://cymballabs.atlassian.net/browse/CPT-1",
        "source_type": "jira",
        "entity_type": "issue"
      }
    },
    "dataStore": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store"
  }]
}

Send an autocomplete request and return recent queries

Returns as suggestions a list of the user's most recent queries that prefix-match the query on the request.

The matching query suggestions are listed from the most recent to the oldest. To use recent search, the user pseudo ID must be provided.

Example

An employee is querying their company intranet site to get information about taking vacations. The employee has performed the following queries, listed from most recent to oldest:

PTO, Vacation blackout periods, How much vacation time do I have?, Time off, Vacation policy, covering a vacant position during absences, and Can I take unpaid time off?.

Now, in response to the employee typing vac in the search box, the autocomplete suggestions would be as follows:

Vacation blackout periods
How much vacation time do I have?
Vacation policy
Covering a vacant position during absences

Procedure

To send an autocomplete request that returns the user's most recent queries, follow these steps:

REST

Find your app ID. If you already have your app ID, skip to the next step.
1. In the Google Cloud console, go to the Agent Builder page.
  
  Go to Apps
2. On the Apps page, find the name of your app and get the app's ID from the ID column.

Call the completionConfig.completeQuery method.


curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/completionConfig:completeQuery" \
-d '{
      "query":"QUERY_STRING",
      "suggestionTypes": ["RECENT_SEARCH"],
      "userPseudoId": "USER_PSEUDO_ID"
    }'

PROJECT_ID: the ID of your Google Cloud project.
APP_ID: the ID of the Vertex AI Search app.
QUERY_STRING: the typeahead input used to fetch suggestions.
USER_PSEUDO_ID: a pseudonymized identifier of the user. You can use an HTTP cookie for this field, which uniquely identifies a visitor on a single device. Don't set this field to the same identifier for multiple users. This would combine their query histories. Don't include personally identifiable information (PII) in this field.

Example command and result

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/completionConfig:completeQuery" \
-d '{
      "query": "hol",
      "suggestionTypes": ["RECENT_SEARCH"],
      "userPseudoId": "test_user"
    }'

{
  "recentSearchSuggestions": [
    {
      "suggestion": "holiday readiness",
      "recentSearchTime": "2024-11-19T18:27:07.261698Z"
    },
    {
      "suggestion": "holiday freeze",
      "recentSearchTime": "2024-11-19T18:25:45.744021Z"
    },
    {
      "suggestion": "holiday",
      "recentSearchTime": "2024-11-19T18:20:08.916884Z"
    }
  ]
}

Use an autocomplete denylist

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

Although advanced autocomplete is at the app-level, denylists are at the data-store-level. This is significant if your app is a blended search app. Create a denylist for each data store connected to the app.

For information about creating and using denylists, see Use an autocomplete denylist.