Retail is being renamed to Vertex AI Search for retail. We are in the process of updating content to reflect the new branding.

Get search results

This page describes basic querying with 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 search

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. 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. 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, search sorts potential search results based on relevance, popularity, buyability, and personalization.

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 search as search user events. If the event has a non-empty userEvent.searchQuery field and an empty userEvent.pageCategories field, 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. Search leverages AI to optimize how browse results are sorted by considering popularity, buyability, and personalization.

When the servingConfigs.search method sends a request, 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 search as search user events. 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);
  }
}

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 Vertex AI Search for 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);
  }
}

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
}

Search performance tiers

Search offers several search performance tiers that increasingly improve your results. For example, for text query search use cases, results might be based solely on relevance. As you unlock more advanced performance tiers, search can return results that are based on relevance, popularity, revenue optimization, and personalization.

Search automatically unlocks higher performance tiers when you upload catalog and user event data that meets the minimum requirements of each tier.

The Data quality page on the Search for Retail console provides an assessment of which requirements you have met for each tier. For more information about using this page to view data quality and search performance tiers, see Unlock search performance tiers.

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

Go to the Evaluate page in the Search for Retail console.

Go to the Evaluate page
Click the Search tab.

Note: The Search tab is available only if you have search turned on. For instructions to turn it on, go to Before you begin.
Select the serving config that you want to preview.
Select the catalog branch that contains the catalog you want to preview.
Optional: Enter a visitor ID to preview search results for that user.
Optional: Enter a user ID to preview search results for that user.
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.
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.
Enter a text-based search query to preview search results for that query.
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.
Optional: Click the Grid icon or the List icon to switch how your search results are displayed in preview.
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

Go to the Evaluate page in the Search for Retail console.

Go to the Evaluate page
Click the Browse tab.

Select the serving configuration that you want to preview.
Select the catalog branch that contains the catalog you want to preview.
Optional: Enter a visitor ID to preview results for that user.
Optional: Enter a user ID to preview results for that user.
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.
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.
Enter the page category that you are testing browse results for.
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.
Click Browse preview or press enter in any input field to see the results.

Results are displayed with their available thumbnail images.
Optional: Click the Grid icon or the List icon to switch how your results are displayed in preview.
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.