Retail is being renamed to Vertex AI Search for retail. We are in the process of updating content to reflect the new branding.

Autocomplete for search

This page introduces the autocomplete feature and how to use it. Search provides autocomplete for powering retailers' search box type-ahead suggestions.

Autocomplete is a feature for predicting the rest of a query a user is entering, which can improve the user search experience and accelerate the shopping process before checkout. It can also improve the search response quality and thus create higher revenue by providing well-formatted queries.

Overview

When an end user begins typing a search term on your site, search can provide a list of suggestions that the user may want. For example, "shoes" and "shirts" might be suggested when the user types "sh".

Data source

You can choose one of the following data sources for your suggestion predictions:

A BigQuery dataset that you upload.
A dataset that is generated from user events and other metadata using machine learning.

Uploaded dataset

A BigQuery suggestion table you upload as a dataset, which is used to suggest queries. For how to upload a dataset, see Importing autocomplete data.

Auto-learning dataset

A machine learning-powered suggestion dataset generated by search based on users' search events.

To enable auto-learning:

Console

Go to the Controls page
Go to the Autocomplete Controls tab.
Click Edit settings.
Turn on Auto learning.
Click Save settings.

Auto-learning can take 1-2 days to update.

cURL

curl -X PATCH -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/completionConfig?update_mask.paths=auto_learning"  --data "{auto_learning: true}"

Auto-learning dataset prerequisite

Auto-learning generates suggestions from search type user events (eventType = "search"). The generation uses the past 180 days of user events. It requires a good quality and quantity of imported user events.

Auto-learning filters out rare suggestions, so if the search type user event quantity is too small (less than 20,000), many suggestion candidates may be filtered out. In this scenario, you may want to first test autocomplete function with a more frequent search query.

Auto-learning dataset release schedule

The auto-learning dataset is generated daily, then pushed to indexing and release. The full cycle takes around two days.

Auto-learning features

Search applies machine learning techniques to clean up and format queries and suggestion data for auto-learning dataset only.

Feature	Description	Example
Remove 0-result searches	Remove queries that have zero search results	For grocery retailer, "Gucci handbags" has 0 search results, so it is removed
Correct typos	Correct word spellings that are typos Also clean real-time input queries before matching	"Milc" → "Milk"
Add allowlist queries	Queries you explicitly allow are added	Check More Information section below.
Remove blocklist queries	Queries you explicitly block are removed	Check More Information section below.
Remove unsafe terms	Powered by Google Safe Search Remove inappropriate queries	Porn, racy, vulgar, violence, etc.
Remove very rare terms	AI system adjusts cutoff depending on query statistics If terms are unusually rare, they are removed	"74x39x9 inches 2 layer twin air mattress with 120V handheld pump"
Deduplicate Terms	Powered by AI-driven Semantic Understanding For near-identical terms, either term will match, but only the more popular one will be suggested	"Shoes for Women", "Womens Shoes", and "Womans Shoes" are deduplicated, so only one will be suggested.

Get completion suggestions

Use the completeQuery API to fetch the suggestions. Example:

cURL

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog:completeQuery?query=sho&dataset=user-data&deviceType=DESKTOP&maxSuggestions=5"

Autocomplete options and controls

This section explains what options and controls are available for autocomplete. See an overview in the following table and more details below.

Control	Details	Location
Denylist	Manually removes queries from the suggestion data	API Request: CompletionData:import. For more information, see Import autocomplete data.
Allowlist	Manually adds queries to the suggestion data	API Request: CompletionData:import (also see Import Autocomplete Data )
Minimum length to trigger autocomplete	Controls # of characters before autocomplete is triggered	Cloud console > Controls
Matching Order	Matching order determines how user query and suggestions are matched.	Cloud console > Controls
Suggestion Count	This is the number of suggestions that will be returned from autocomplete	Cloud console > Controls or API Request: completeQuery.maxSuggestions
Device Type	When device types are specified, the suggestions are generated based on the popularity of the given device types Not specifying this returns suggestions based on combined popularity from all device types	API Request: completeQuery.deviceType
Suggestion Data Source	If you have both auto-generated and uploaded data sources, you can choose which one to use at query time	API Request: completeQuery.dataset
Language	You can specify which language(s) you want suggestions to be in	API Request: completeQuery.languageCodes[]

Allowlist (Do Not Remove List)

Search does post processing, such as spell correction, on autocomplete suggestion data. You can create an allowlist of terms that search skips when post processing.

Allowlisted terms are never filtered out from suggestions. The allowlist works for both uploaded datasets and auto-learning dataset.

Examples: there are some intentionally misspelled brand names, such as "froot loops" instead of "fruit" or "foot". See detailed upload instruction in import completion data.

For data import, you can use Cloud console > Controls > Autocomplete Controls > Do Not Remove list or use CompletionData:import in the API.

Changes takes effect in around 2 days.

Denylist

The denylist only works for auto-learning datasets. The denylist does not work for uploaded datasets.

The terms in a denylist never appear in suggestions.

To import a denylist, you can use Cloud console > Controls > Autocomplete Controls > Deny list or use API CompletionData:import. For detailed instructions on how to import a denylist, see import completion data.

Changes takes effect in around 2 days.

Minimum length to trigger

You can set the number of characters required before autocomplete queries will return results. The setting can be found on Cloud console > Controls > Autocomplete Controls > Minimum length to trigger.

Changes take effect immediately.

Matching order

This determines how to match suggestions with user input terms.

When set to Suggestion starts with the term, auto-complete matches the user input term as an exact prefix to suggestions. For example, the user input "sh" matches the suggestions "shoes" and "shirts", but not the suggestion "red shoes".

When set to Suggestion can start from anywhere in the term, auto-complete tokenizes the user input term into words and matches it to the words in suggestions, regardless of word order. For example, the user input term "red sh" matches the suggestions "shirts red", "red shoes", and "kid red shoes". However, the input term "hoes" is not matched with these suggestions, because none of words in the suggestions begin with "hoes".

The setting can be found on Cloud console > Controls > Autocomplete Controls > Matching order.

Changes take effect immediately.

Suggestion Count

This is the number of suggestions that will be returned from autocomplete queries and it cannot exceed 20. The setting can be found on Cloud console > Controls > Autocomplete Controls > Suggestion Count or can be set in completeQuery.

Changes take effect immediately.

Device type

Search autocomplete supports different device types, such as mobile and desktop. You can upload or get different suggestions based on device types. If deviceType is not specified in completeQuery, the suggestion will be across all device types.

For an auto-learning dataset based on search user events, set user_agent in UserEvent.user_info to support different device types. See user agent in wiki.

Advanced features

This section describes the advanced autocomplete features available with search. For example, you can supplement query autocomplete suggestions with other suggestions, such as brands and categories.

These advanced features are available only for auto-learning datasets.

Suggestion FeatureSet

We provide an additional FeatureSet for each query suggestion term to allow customers to show advanced functions on their websites.

The FeatureSet appears in the response as a key value map. Currently, Vertex AI Search for retail returns up to five popular categories and brands related to each query suggestion in the completeQuery.completionResults.attributes API response. FeatureSet suggestions do not have to match the query strings input by the end user.

You can use the FeatureSet in the response to enrich search suggestions. For example:

Aggregate and create Popular Brands and Popular Categories sections that appear below the search suggestion list.
Display the most popular brand or category next to search suggestion terms.

After making changes to the catalog, such as changing categories for products, expect to wait two weeks to 30 days until the FeatureSet suggestions reflect the product catalog changes. This wait time is because auto-learning trains on the past 30 days of search event data.

Attribute suggestions

Search provides attribute suggestions that match user input strings. Supported attribute suggestions types are brands and categories.

Attribute suggestions differ from a suggestion FeatureSet. Attribute suggestions are lists of suggested product attributes (like brands and categories), similar to how query suggestions are lists of suggested queries. Attribute suggestions can be used independently from query suggestions. A suggestion FeatureSet is metadata for a query suggestion, and so is dependent on query suggestions.

Attribute suggestions can be used to auto-complete brands or categories that an end user is typing, in separate sections below the search suggestion list.

Suggestion facet with product counts (Experimental)

This is an experimental feature for limited customers. To use it, contact the support team.

When the suggestion facet with product count feature is enabled, the returned completeQuery.completionResults gives a list of autocomplete suggestions as normal but also product counts for each suggestion with the total count and product count by facet (like color, category).

For example, if the search query is "shoe", the returned Autocomplete suggestions might be:

womens shoes
mens shoes

Furthermore, if the facet key of interest is color, a product count and product count by color is also returned with each Autocomplete suggestion:

womens shoes (32)
- black (10)
- taupe (16)
- white (10)
mens shoes (43)
- black (10)
- brown (5)
- green (17)

As a retailer, you don't need to present the product count to the shopper, but you might decide to order the list of suggestions based on product count instead of the order returned in completeQuery.completionResults. For example, you might want to encourage shoppers to look at green shoes for men by having green shoes appear at the top of the suggestion box even though they are not the most popular item.

For example:

{
  "completion_results": [{ 
    "suggestion": "womens shoes"
    "facets": [ 
      {
        "key": "color"
        "values": [ 
          {
            "value": "black"
            "count": 10
          }
          {
            "value": "taupe"
            "count": 16
          }
          {
            "value": "white"
            "count": 10
          }
        ]
      }
    ]
    "total_product_count": 32
  },
  (...)
  ],
}

The facet count information appears as a list of Facets in completeQuery.completionResults.facets for each suggested search query. Each facet has a FacetValues list that contains the product count per facet value. The total product count for each suggested search query is returned in completeQuery.completionResults.totalProductCount.

To turn on and use suggestion facets with product counts, follow these steps:

Contact the support team and ask them to turn on the feature, Suggestion facet with product counts. Specify which FacetKeys you want product counts for. Only textual_fields facets are allowed.
For at least 7 days, make sure that when using the search API, include the facet key in FacetSpecs include the facet key in search.searchRequest.facetSpecs.

This wait time is because facet information is calculated using the past week of search histories data.
After the feature has been turned on for you, the returned suggestions of the completeQuery API contain the product counts by facet and by suggestion.

Suggestion filtered by entity

Entities allow you to filter autocomplete search suggestions. An entity might be a website for a different brand or region. You want autocomplete to best reflect the behavior of the users shopping that particular brand or regional website. For more information about entities, see Entities.

To include entities in autocomplete suggestions:

Include the entity field in your search user events (eventType = "search"). For information, see the complete object example for the Search user event.
Set the entity field in your CompleteQuery API request to get suggestions for only that entity.

The entity string in the user events and the API requests must be an exact match. Otherwise, autocomplete returns empty suggestions.

Typically, it takes 30-90 days of user event data before the entity feature can return optimal autocomplete suggestions.