This is the documentation for Recommendations AI, Retail Search, and the new Retail console.

Adjust result size

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

This page provides an overview of query expansion.

Query expansion tutorial

This tutorial shows you how to enable the query expansion feature. When a shopper uses an ambiguous or a multi-word search phrase, they can get an empty response. After turning on query expansion, Retail Search analyzes the request and returns the expanded list of products based on the parsed search query.

For step-by-step guidance for this task directly in the Cloud Shell Editor, click Guide me:

Guide me

The following sections take you through the same steps as clicking Guide me.

Example dataset

This page uses the following dataset as an example. Only the fields necessary for explanation are included.

Query expansion

Query expansion increases the recall for query terms with few results, especially long tail queries.


public static SearchResponse searchProductsWithQueryExpansion(String query, int pageSize,
    Condition condition) throws IOException, InterruptedException {
  SearchServiceClient searchClient = getSearchServiceClient();

  QueryExpansionSpec queryExpansionSpec = QueryExpansionSpec.newBuilder()

  SearchRequest searchRequest = SearchRequest.newBuilder()

  SearchResponse response =;

  searchClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;

For example, if you search "Google Pixel 5" without query expansion, you might only get "google_pixel_5" in the result. With query expansion, you might get "google_pixel_4a_with_5g", "google_pixel_4a" and "google_pixel_5_case" as well.