Get search results

This page describes basic querying with Retail Search, including text query searches, browse searches, pagination, optimization, and personalized results.

Never cache personalized results from an end user, and never return personalized results to a different end user.

About text search and browse search with Retail Search

Retail Search provides both text query search and browse search capabilities.

In the text query search use case, a shopper might enter a text-based query on your site. Retail Search returns a search response containing products that fit within the parameters of controls you have set up, sorted by relevance and revenue maximization.

In the browse use case, a shopper might go to your site menu and navigate to a specific product category. Retail Search automatically chooses the most revenue-maximizing sort order by learning from user behavior and trends. Browse results can be further refined by the controls you have set up.

Both text search and browse search requests use the servingConfigs.search method.

Text query searches

When a user enters a text query to search on your site, Retail Search sorts potential search results based on relevance, popularity, buyability, and personalization.

Retail Search considers a servingConfigs.search request as a text-based search request if it has a non-empty query field.

When uploading user event, send text query search events generated by Retail Search as search user events. If the event has a non-empty userEvent.searchQuery field and an empty userEvent.pageCategories field, Retail Search considers it a text-based search event.

Browse searches

Typically, browsing products using site navigation produces results that are all of equal relevance, or sorted by best-selling items. Retail Search leverages AI to optimize how browse results are sorted by considering popularity, buyability, and personalization.

When the servingConfigs.search method sends a request, Retail Search considers it a browse search request if the query field is empty. When that is the case, the results are based on the filter and pageCategories fields, as well as further optimization and personalization if available.

When uploading user event, make sure that you send browse search events generated by Retail Search as search user events. Retail Search considers a search user event as a browse-based event if it has an empty userEvent.searchQuery field and a non-empty userEvent.pageCategories field.

In order to get correct browse search results, 'pageCategories' and 'filter' values in your search requests must exactly match the 'pageCategories' and 'filter' values in your uploaded user events. If they do not match exactly, the data in the search requests might not be recognized, which can negatively impact result quality.

Search

Use search requests to get results for both text searches and browse searches. To make a search request, use the servingConfigs.search method.

All search requests require placement, which identifies the full resource name of the serving config that will be used. The serving config determines which settings and associated controls affect the search results.

Text query search requests require a non-empty query field.

Browse search requests require a non-empty pageCategories field.

Java

import com.google.cloud.retail.v2.SearchRequest;
import com.google.cloud.retail.v2.SearchResponse;
import com.google.cloud.retail.v2.SearchServiceClient;

public static void searchProducts(String query) throws IOException, InterruptedException {
  SearchRequest searchRequest = SearchRequest.newBuilder()
      .setPlacement(DEFAULT_SEARCH_PLACEMENT_NAME)
      .setBranch(DEFAULT_BRANCH_NAME)
      .setVisitorId(VISITOR_ID)
      .setQuery(query)
      .build();

  try (SearchServiceClient searchClient = SearchServiceClient.create()) {
    SearchResponse response = searchClient.search(searchRequest).getPage().getResponse();
    System.out.println("Search response: " + searchResponse);
  }
}

Python

def search_products(query: str):
    search_request = SearchRequest()
    search_request.placement = default_search_placement
    search_request.branch = default_catalog
    search_request.query = query
    search_request.filter = build_isolation_filter(test_id)
    search_request.visitor_id = visitor_id

    print(search_request)

    return get_search_service_client().search(search_request)

By default, a reasonable number of results ordered by relevance is returned.

To get product attributes returned with the search response, make sure to provide attribute values when you import your catalog data. Product has predefined system attributes such as brand, color, and size that you can provide values for. You can also include custom attributes that you define with Product.attributes.

Querying tutorial

This tutorial shows you how to send a text-based search query to the Retail service and analyze the response.

---

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

Guide me

---

Pagination

Use pagination to decrease lookup time and the size of responses being sent.

Pagination tutorial

This tutorial shows how to control pagination in a text-based search request. When a shopper looks for products in a shop, they can improve their navigation through the search results. For example, they can limit the number of items in the search response by using the page size feature or jump to their preferred page by using the offset feature.

---

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

Guide me

---

Paginate

To jump from one page to another, use either page_token or offset, according to your use case.

To jump to the next page, you could use page_token. For example, suppose you send the following SearchRequest.

JSON

{
  placement: 'projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/placements/default_search'
  visitor_id: 'VISITOR_ID'
  query: 'shoes'
  page_size: 5
}

From SearchResponse, you can get the resulting products with top 5 relevance, along with a next_page_token.

JSON

{
  results: [
    products{...}, products{...}, products{...}, products{...}, products{...}
  ]
  next_page_token: "wY4ETNkBDOlVjZ0YWLzUmM40SMhVjMtADMwATL5UGN5MGZlVDJaIQ5LaYsQUw9fC6lIwgE1EgC"
  total_size: 100
  search_token: "NtQKDAiXt4_3BRDCg_jnARABGiQ1ZWRjOTRlOC0wMDAwLTI1YTEtODJlMy1mNGY1ZTgwZDUxOGM"
}

To get the result products with the next 5 relevance (6th to 10th), you would set page_token using the same placement, visitor_id, and query as next_page_token from the previous SearchResponse.

Java

import com.google.cloud.retail.v2.SearchRequest;
import com.google.cloud.retail.v2.SearchResponse;
import com.google.cloud.retail.v2.SearchServiceClient;

public static void searchProducts_withNextPageToken(String query, int pageSize)
    throws IOException, InterruptedException {
  try (SearchServiceClient searchClient = SearchServiceClient.create()) {
    SearchRequest firstRequest = SearchRequest.newBuilder()
        .setPlacement(DEFAULT_SEARCH_PLACEMENT_NAME)
        .setBranch(DEFAULT_BRANCH_NAME)
        .setVisitorId(VISITOR_ID)
        .setQuery(query)
        .setPageSize(pageSize)
        .build();

    SearchResponse firstResponse = searchClient.search(firstRequest).getPage()
        .getResponse();
    System.out.println("First search response: " + firstResponse);

    SearchRequest secondRequest = SearchRequest.newBuilder()
        .setPlacement(DEFAULT_SEARCH_PLACEMENT_NAME)
        .setBranch(DEFAULT_BRANCH_NAME)
        .setVisitorId(VISITOR_ID)
        .setQuery(query)
        .setPageSize(pageSize)
        .setPageToken(firstResponse.getNextPageToken())
        .build();

    SearchResponse secondResponse = searchClient.search(secondRequest).getPage()
        .getResponse();
    System.out.println("Second search response: " + secondResponse);
  }
}

In this example, SearchRequest looks like this:

JSON

{
  placement: 'projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/placements/default_search'
  visitor_id: 'VISITOR_ID'
  query: 'shoes'
  page_size: 5
  page_token: "wY4ETNkBDOlVjZ0YWLzUmM40SMhVjMtADMwATL5UGN5MGZlVDJaIQ5LaYsQUw9fC6lIwgE1EgC"
}

In some other cases, instead of navigating from page to page or getting results with top relevance, you could directly jump to a particular position with offset.

Java

import com.google.cloud.retail.v2.SearchRequest;
import com.google.cloud.retail.v2.SearchResponse;
import com.google.cloud.retail.v2.SearchServiceClient;

public static void searchProducts_withOffset(String query, int pageSize,
    int offset) throws IOException, InterruptedException {
  SearchRequest searchRequest = SearchRequest.newBuilder()
      .setPlacement(DEFAULT_SEARCH_PLACEMENT_NAME)
      .setBranch(DEFAULT_BRANCH_NAME)
      .setVisitorId(VISITOR_ID)
      .setQuery(query)
      .setPageSize(pageSize)
      .setOffset(offset)
      .build();

  try (SearchServiceClient searchClient = SearchServiceClient.create()) {
    SearchResponse response = searchClient.search(searchRequest).getPage().getResponse();
    System.out.println("Search response: " + searchResponse);
  }
}

Python

def search_products_with_offset(query: str, _offset: int, page_size=10):
    search_request = SearchRequest()
    search_request.placement = default_search_placement
    search_request.branch = default_catalog
    search_request.query = query
    search_request.filter = build_isolation_filter(test_id)
    search_request.page_size = page_size
    search_request.offset = _offset
    search_request.visitor_id = visitor_id

    print(search_request)

    return get_search_service_client().search(search_request)

For example, if you want the tenth page of the results when the page size is 5, then you could set the offset to be 45, which is calculated by (10 - 1) * 5.

JSON

{
  placement: 'projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/placements/default_search'
  visitor_id: 'VISITOR_ID'
  query: 'shoes'
  page_size: 5
  offset: 45
}

Advanced optimization

Retail Search automatically optimizes text search and browse search based on overall user data. Retail Search learns from trends in user data and uses it to increase user engagement and maximize revenue.

After meeting the minimum data requirements for Retail Search to generate results, make sure to meet the data requirements for advanced optimization.

Advanced optimization turns on automatically after you meet its data requirements.

For more information about these requirements, see Search optimization requirements.

The Retail console Data page's Data Quality panel provides an assessment of which requirements you have met.

Personalization

Personalization helps deliver results that are more relevant to an end user's past interactions with your website.

Personalization is automatically turned on when you meet the following criteria:

• You meet event quality requirements for revenue optimization.
• You don't cache the search responses from Retail Search.
• The visitor ID in search requests matches the visitor ID in corresponding user events.

For more information about these requirements, see Search personalization requirements.

The Retail console Data page's Data Quality panel provides an assessment of which requirements you have met. Click the Events tab to view the Personalized Search Metrics and Personalized Browse Metrics sections.

To get the best quality improvements from personalization:

• In search requests and in user events, provide user IDs in addition to visitor IDs for logged-in users. This allows Retail Search to personalize results for the user based on users' signed-in events across devices.
• Send user events in real-time instead of in batch uploads with a delay. This helps Retail Search personalize using a user's most recent activity on your site.
• Upload all user events. For example, do not submit only events that are attributable to searches.

To turn off personalization, set ServingConfig.personalizationSpec to mode.DISABLED.

Evaluate text search and browse results

Before you update your website code to request text search or browse search results, you can preview the results to confirm that your serving config is working as you expect.

For more information about serving configs, see About serving configs.

You can preview serving config results either from the Evaluate page, or by going to a serving config's Details page in the console and clicking its Evaluate tab. The following steps show you how to preview from the Evaluate page.

To preview the results returned by your serving configuration:

Text search

1. Go to the Retail Evaluate page in the Google Cloud console.
   
   Go to the Evaluate page

2. Click the Search tab.

Note: The Search tab is available only if you have Retail Search turned on. For instructions to turn it on, go to Before you begin.

1. Select the serving config that you want to preview.

2. Select the catalog branch that contains the catalog you want to preview.

3. Optional: Enter a visitor ID to preview search results for that user.

4. Optional: Enter a user ID to preview search results for that user.

5. Optional: Enter a search time to preview search results that would appear at the specified time.

   For example, if you have promoted certain products for Black Friday, you can see results as they would appear on that day.

6. Optional: Select facets to display alongside the search results and click OK to apply them.

   The facets you select are used to generate a list of facet filters that appear under Add facets after you perform the initial search. These facet filters can include facets other than those you select in this step, such as dynamic facets.

7. Enter a text-based search query to preview search results for that query.

8. Click Search preview or press enter in any input field to see the results.

   Search results are displayed with their available thumbnail images.

   If your search triggers a redirect control, a notice appears that displays the redirect URI.

9. Optional: Click the Grid icon or the List icon to switch how your search results are displayed in preview.

10. Optional: If you selected facets to appear alongside your results, select one or more facet values from the facets list to filter results by those values. The results are automatically updated upon selection.

    When you select multiple values of the same facet, they are applied as an OR operator would be, and values across different facets are applied as an AND operator would be. For example, after selecting the facets "color" and values "blue" and "gold", and the material values "cotton" and "polyester". Your search results results must have either "blue" or "gold" as an attribute, and must also have either "cotton" or "polyester" as an attribute.

Browse

1. Go to the Retail Evaluate page in the Google Cloud console.
   
   Go to the Evaluate page

2. Click the Browse tab.

Note: The Browse tab is available only if you have Retail Search turned on. For instructions to turn it on, go to Before you begin.

1. Select the serving configuration that you want to preview.

2. Select the catalog branch that contains the catalog you want to preview.

3. Optional: Enter a visitor ID to preview results for that user.

4. Optional: Enter a user ID to preview results for that user.

5. Optional: To preview how results would look with a specific filter added, enter a filter string. Use the filter expression syntax specified in the Filter documentation.

6. Optional: Enter a browse time to preview results that would appear at the specified time.

   For example, if you have promoted certain products for Black Friday, you can see results as they would appear on that day.

7. Enter the page category that you are testing browse results for.

8. Optional: Select facets to display alongside the results and click OK to apply them.

   The facets you select are used to generate a list of facet filters that appear under Add facets after you perform the initial search. These facet filters can include facets other than those you select in this step, such as dynamic facets.

9. Click Browse preview or press enter in any input field to see the results.

   Results are displayed with their available thumbnail images.

10. Optional: Click the Grid icon or the List icon to switch how your results are displayed in preview.

11. Optional: If you selected facets to appear alongside your results, select one or more facet values from the facets list to filter results by those values. The results are automatically updated upon selection.

    When you select multiple values of the same facet, they are applied as an OR operator would be, and values across different facets are applied as an AND operator would be. For example, after selecting the facets "color" and "material", you might then filter your search results by selecting the color values "blue" and "gold", and the material values "cotton" and "polyester". Your results must have either "blue" or "gold" as an attribute, and must also have either "cotton" or "polyester" as an attribute.

To see the Details page for the serving config you're previewing, click View serving config under the Select serving config field.