Get search results

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

Unique user session identifiers

The required visitor_id string field is used to uniquely identify a user on a single device. It acts as a persistent session identifier that allows AI Commerce Search to track a specific user's behavior across their shopping journey.

AI Commerce Search uses the history associated with a specific visitor_id to train models and serve personalized search results. The system generates results dynamically based on the specific visitor_id provided in the request. For example, if a visitor frequently views green dresses, the model uses visitor_id to recognize them later and prioritize similar items in their search results. For this reason, the visitor ID must be formatted identically across both user event ingestion (tracking) and search or recommendations requests (serving).

Relevance is different from matching. Matching is finding candidate products in the index that correspond to the user's search query. Relevance, on the other hand, is a degree of matching. It involves ranking those products in a way that best satisfies the user's intent and needs. AI Commerce Search uses techniques to improve matching and relevance for a better overall search experience for users that meets retailers' needs.

Search defaults to relevance. However, some non-relevant products can appear at the bottom of default searches or in explicit product discovery requests. This only becomes noticeable when you set orderBy, because it reduces the size of search results in general. The recall size decreases because the less relevant products, which were previously being returned at the bottom of the default search, are filtered out to some degree. Read the next section to find out how to customize search.

AI Commerce Search defaults to relevance in search. However, search is tuned to also surface marginally relevant items higher up in the search results to provide retailers more targeted search results to increase the conversion potential of user events.

These added search features optimize the default relevance algorithm, providing non-default features tuned to each retailer's utilization profile, including:

  • Options to sort results such as by price, top-rated, or best-selling items. Non-default search is customized to return specific search results with the correct product variants. For example, to show the cheapest or most expensive variant when sorting by price.

  • Auto-application of a tighter relevance filter for non-default user events.

  • Enabling adjustable strength boost/bury controls to fine-tune search results.

Text search and browse 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.

How to process text queries and parameters

Standard queries undergo linguistic analysis, which strips standard punctuation. Filter strings are strictly case-sensitive. Understanding how to process text queries and parameters is critical for constructing API requests in AI Commerce Search properly.

  • Query tokenization and punctuation: Natural language text is passed into the query field undergoes automatic linguistic analysis and spell correction. During this process, standard punctuation (like commas, periods, +, or -) is often stripped or ignored to optimize for natural language understanding.
  • Strict case sensitivity in parameters: While standard text queries are generally case-insensitive, programmatic parameters are strictly case-sensitive.
    • Filters: Filter expressions and their literal string values are completely case-sensitive.
    • Sorting: The orderBy expression is case-sensitive. If you sort by a field like products.title, the engine will sort Apple before banana before artichoke. A workaround is to upload product titles in all caps to a separate custom attribute (such as attributes.title_upper) and sort on that attribute to achieve case-insensitive sorting.
  • Reserved special characters:
    • The > character is strictly reserved as the delimiter for category hierarchies (such as Categories > Shoes). If > naturally occurs in your category name, you must replace it with another character before ingestion and querying.
    • The / character is not supported in textual values within recommendation filter expressions.

Browse searches

Browse uses site navigation to produce search results of equal relevance sorted by best-selling items. Search leverages AI to optimize how browse results are sorted by considering popularity, buyability, and personalization.

To get the correct browse search results, consider the following:

  • The pageCategories and filter values in your search requests must exactly match the pageCategories and filter values in your uploaded user events. If the parameters in the requests don't match parameters in the events, the click-based reranking model learned from the events won't perform very well for this specific query and will negatively impact result quality.

  • AI Commerce Search categorizes a search user event as a browse-based event if it has an empty userEvent.searchQuery field and a non-empty userEvent.pageCategories field. This is why you need to make sure you send browse events generated by AI Commerce Search as search user events when uploading them.

  • A browse filter must be valid and indicate for each browse query which products belong to the product category the user is browsing in. To achieve this setup, the category ID needs to be defined in both the filter and the page_category fields. Take, for example, if you want the search results to be targeted to Home & Garden. First off, having only one filter value of "in-stock" does not refine the search enough to provide optimal browse results. To provide search results restricted to Home & Garden, you not only need to set "Home \& Garden" in the page category, but also in the filter with categories: ANY("Home & Garden"). If you neglect to define the category in the filter part, browse results could likely be too broad and include many non-Home & Garden items.

Serving requests and events with an empty query field and filled page_categories fields are considered browse requests and user events. The page_categories field specifies the browse page itself. 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 and, if available, more optimization and personalization.

You can set the category in both as in this example:

JSON

page_category: "Home & Garden"
filter: "(availability: ANY("