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
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
.
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:
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:
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
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 }
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
Go to the Retail Evaluate page in the Google Cloud console.
Go to the Evaluate pageClick the Search tab.
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 anAND
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 Retail Evaluate page in the Google Cloud console.
Go to the Evaluate pageClick 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 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 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.