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 |
|
"World's best $#*! milk" → "worlds best milk" |
Remove 0-result searches |
|
For grocery retailer, "Gucci handbags" has 0 search results, so it is removed |
Correct typos |
|
"Milc" → "Milk" |
Add allowlist queries |
|
Check More Information section below. |
Remove blocklist queries |
|
Check More Information section below. |
Remove unsafe terms |
|
Porn, racy, vulgar, violence, etc. |
Remove very rare terms |
|
"74x39x9 inches 2 layer twin air mattress with 120V handheld pump" |
Deduplicate Terms |
|
"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 |
|
API Request: ImportCompletionDataRequest (see "Importing Auto-completion Data") |
Allowlist |
|
API Request: ImportCompletionDataRequest (see "Importing Auto-completion Data") |
Minimum length to trigger auto-completion |
|
Cloud console > Controls |
Matching Order |
|
Cloud console > Controls |
Suggestion Count |
|
Cloud console > Controls or API Request: CompleteQueryRequest.maxSuggestions |
Device Type |
|
API Request: CompleteQueryRequest.deviceType |
Suggestion Data Source |
|
API Request: CompleteQueryRequest.dataset |
Language |
|
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"