Auto-completion

Stay organized with collections Save and categorize content based on your preferences.

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.

To enable auto-learning:

Console

  1. Go to the Controls page

  2. Go to the Autocomplete Controls tab.

  3. Click Edit settings.

  4. Turn on Auto learning.

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

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.

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"

Auto-completion options and controls

This section explains what options and controls are available for auto-completion. See a quick overview in the following table and more details below.

Control Details Location
Denylist
  • Manually removes queries from the suggestion data
 API Request: CompletionData:import (also see Import Auto-completion Data )
Allowlist
  • Manually adds queries to the suggestion data
 API Request: CompletionData:import (also see Import Auto-completion Data )
Minimum length to trigger auto-completion
  • Controls # of characters before auto-completion 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 auto-completion
 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 & 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)

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.

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

Changes takes effect in around 2 days.

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.

For data import, you can use Cloud console > Controls > Autocomplete Controls > Deny list or use API CompletionData:import.

Changes takes effect in around 2 days.

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 > 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 auto-completion 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

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.

Advanced features

This section describes the advanced auto-completion features available with Retail Search. For example, you can supplement query auto-completion 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 show advanced functions on their websites.

The FeatureSet appears in the response as a key value map. Currently, 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.

Attribute suggestions (Experimental)

This is an experimental feature. Please contact the Cloud Retail support team if you are interested in becoming an early adopter.

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