This page describes basic querying and using pagination with Retail Search.
Never cache personalized results from an end user, and never return personalized results to a different end user.
Querying tutorial
This tutorial shows you how to send a simple search query to the Retail service and analyze the response.
For step-by-step guidance on this task directly in Cloud Shell Editor, click Guide me:
The following sections take you through the same steps as clicking Guide me.
Pagination tutorial
This tutorial shows you how to control pagination in your search request.
For step-by-step guidance on this task directly in Cloud Shell Editor, click Guide me:
The following sections take you through the same steps as clicking Guide me.
Evaluate search results
Before you update your website code to request search results, you can preview search results to confirm that your serving config is working as you expect.
For more information about serving configs, see Serving configurations.
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 search results returned by your serving configuration:
Go to the Retail Evaluate page in the Google Cloud console.
Go to the Evaluate pageClick the Search tab.
Select the serving configuration you want to preview.
Select the [catalog branch][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 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 search query to preview search results for that query.
Click Search preview or press enter in any input field to see the search 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 anAND
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 search results 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.
Query
A minimal version of a search request requires placement
and query
.
Java
Python
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
.
Paginate
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
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
Python
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 }