Querying and pagination

Preview

This product is covered by the Pre-GA Offerings Terms of the Google Cloud Terms of Service. Pre-GA products might have limited support, and changes to pre-GA products might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

This page describes basic querying and using pagination with Retail Search.

Search preview

Before you update your website code to request search results, you can use search preview to confirm that your model is working as you expect.

Make sure you have first created a serving configuration for Retail Search.

To preview search results returned by your serving configuration:

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

2. Select the serving configuration you want to preview.

3. Enter a search query and a visitor ID to preview search results for that query.

4. Click Search preview to see the search results.

Querying

A minimal version of a search request requires placement and query.

Java

public static SearchResponse searchProducts(String query) throws IOException, InterruptedException {
  SearchServiceClient searchClient = getSearchServiceClient();

  SearchRequest searchRequest = SearchRequest.newBuilder()
      .setPlacement(DEFAULT_SEARCH_PLACEMENT_NAME)
      .setBranch(DEFAULT_BRANCH_NAME)
      .setVisitorId(VISITOR_ID)
      .setQuery(query)
      .build();

  SearchResponse response = searchClient.search(searchRequest).getPage().getResponse();

  searchClient.shutdownNow();
  searchClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

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.

Pagination

We recommend using pagination to decrease the lookup time and the size of the responses being sent over the wire.

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

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

  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();

  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 response = searchClient.search(secondRequest).getPage().getResponse();

  searchClient.shutdownNow();
  searchClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

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

public static SearchResponse searchProducts_withOffset(String query, int pageSize,
    int offset) throws IOException, InterruptedException {
  SearchServiceClient searchClient = getSearchServiceClient();

  SearchRequest searchRequest = SearchRequest.newBuilder()
      .setPlacement(DEFAULT_SEARCH_PLACEMENT_NAME)
      .setBranch(DEFAULT_BRANCH_NAME)
      .setVisitorId(VISITOR_ID)
      .setQuery(query)
      .setPageSize(pageSize)
      .setOffset(offset)
      .build();

  SearchResponse response = searchClient.search(searchRequest).getPage().getResponse();

  searchClient.shutdownNow();
  searchClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

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
}