Auto-completion

This page introduces the auto-completion feature and how to use it. Retail Search provides auto-completion for powering retailers' search box typeahead suggestions.

Auto-completion is a feature for predicting the rest of a query a user is typing, 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, Retail 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 auto-completion data.

Auto-learning dataset

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

The following APIs are used for v2alpha and v2beta only. To use this feature in v2, contact the Cloud Retail support team.

To enable auto-learning, update the completionConfig:

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}"

To get completionConfig:

cURL

curl -X GET -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/completionConfig"

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

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

Feature	Description	Example
Remove special characters	Remove non-standard characters from both suggestion data and typed queries	"World's best $#*! milk" → "worlds best milk"
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.

Auto-completion options and controls

This section explains what options and controls are available for auto-completion.

Control	Details	Location
Denylist	Manually removes queries from the suggestion data	API Request: ImportCompletionDataRequest (see "Importing Auto-completion Data")
Allowlist	Manually adds queries to the suggestion data	API Request: ImportCompletionDataRequest (see "Importing Auto-completion Data")
Minimum length to trigger auto-completion	Controls # of characters before auto-completion is triggered	Cloud console > Controls
Matching Order	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".	Cloud console > Controls
Suggestion Count	This is the number of suggestions that will be returned from auto-completion	Cloud console > Controls or API Request: CompleteQueryRequest.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: CompleteQueryRequest.deviceType
Suggestion Data Source	If you have both auto-generated & uploaded data sources, you can choose which one to use at query time	API Request: CompleteQueryRequest.dataset
Language	You can specify which language(s) you want suggestions to be in	API Request: CompleteQueryRequest.languageCodes[]

More Information

The following sections provide more details about auto-complete settings.

Allowlist

Retail Search does post processing, such as spell correction, on auto-completion suggestion data. You can create an allowlist of terms that Retail 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.

Denylist

The terms in a denylist will never appear in suggestions. The denylist works for both uploaded datasets and auto-learning dataset. See detailed upload instruction in import completion data.

Minimum length to trigger

You can set the number of characters required before auto-completion queries will return results. The setting can be found on Cloud console > Controls > Site-wide Controls > Minimum length to trigger.

Changes take effect immediately.

Matching order

This determines how to match suggestions with user input terms. The setting can be found on Cloud console > Controls > Site-wide Controls > Matching order.

Changes take effect immediately.

Suggestion Count

This is the number of suggestions that will be returned from auto-completion queries and it cannot exceed 20. The setting can be found on Cloud console > Controls > Site-wide Controls > Suggestion Count or can be set in CompleteQuery.

Changes take effect immediately.

Device type

Retail Search auto-completion 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.

Get completion

Follow 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"