Boost results

Vertex AI Search for commerce offers a feature that lets you specify records that should be elevated in searches. You can control the result ranking by applying a boosting rule to prioritize or deprioritize returned search items.

Boosting rules

Boosting rules can only be applied when there's a base relevance score, such as in relevance-ordered searches or browse results with pre-sort scores. Boosting is a multiplier function applied to these search and browse results.

Note: Filtering rules always take precedence over boost rules. For more information about filtering and ordering search results, see Filter and order results.

Boost or bury

One product can be conditioned by multiple boost or bury rules, which are set in the boostspec class of the search service API.

• A positive number indicates a boost rule, a promotion.
• A negative number indicates a bury rule, which is a demotion instead of promotion.

Configuration options

• Sum of boost effect: If there's a demotion plus a promotion, Vertex AI Search for commerce adds up these values. The resulting sum is either a lowered boost or net bury effect.
• Max boost rule (default): Vertex AI Search for commerce checks whichever is the maximum value and ignores the other rules.

Multiple boost or bury rules set to one product

Multiple boost or bury rules can affect a product, with either a sum or max of the boost values determining the final score.

When several boosting rules are applied to the same product, always check if another product's score has ousted the product from the top spot. Max mode is set to default so that this problem is less likely to occur.

Assume one product gets boosts of 2, 3, and 0.5, and another product gets one boost of 0.5. Although the product only received a 0.5 boost score, when it's boosted repeatedly, it outranks the other product. Carefully check the boosting spec to make sure it's not overlapping, or it's overlapping as intended.

Overriding filters

Two types of filters that take precedence on top of boosting rules:

1. User-specified: These can be things like price or brand, and appear to the end user as tiles or facets on the website.

2. Topicality (relevance): These filters only exist for search queries (not browsing). They exclude less relevant products from the search results. For example, the search refrigerator doesn't return microwaves or accessories, such as refrigerator handles. The filter recognizes not to boost a microwave for a refrigerator search.

Filters available in search and browse

• Search: Topicality filter plus any other user-applied filters such as on-site facets.
• Browse: Since there is no text-query, only the user-applied filters are applied. Filters are also applied to check that the product (let's say, suits) belongs to the correct product category (not sweaters, for example).

Debugging and troubleshooting

Every product is eligible for unlimited boosting, but user-applied filters eliminate products from the search response. To troubleshoot why a boosted product might not appear in search and browse results, check for:

• Multiple boost rules (including bury demotions): Check boost mode configuration (sum or max) and determine the final score.
• Relevance: A product must be relevant for the query and pass the relevance filters. If a search query is for Nike shoes and the product title is Air Jordans, the words don't match, but their close semantic relationship results in a high relevance score. A product title such as yellow jacket has a low relevance score with a Nike search query. Similarly, if the product title is a cryptic model number that has no relationship to any word whatsoever, the relevance score will be low for any query.
• Filters: Filtering rules override any boost rule, and prevent boosted products from appearing in results. The filter is always applied atop the boost. If a product has user-applied filters, or if a product category filters for browsing, the boost won't work at all.

Boosting tutorial

This tutorial shows you some examples of product boosting.

---

To follow step-by-step guidance for this task directly in the Cloud Shell Editor, click Guide me:

Guide me

---

Configure boost

This page uses the following dataset as an example. Only the fields necessary for explanation are included.

Example dataset

Example product dataset

id	title	brands	categories	price_info.price
"nest_mini_2nd_gen"	"Nest Mini (2nd gen)"	["Google", "Nest"]	["Nest > speakers and displays"]	49.00
"nest_audio"	"Nest Audio"	["Google", "Nest"]	["Nest > speakers and displays"]	99.99
"nest_hub_max"	"Nest Hub Max"	["Google", "Nest"]	["Nest > speakers and displays"]	229.00
"nest_hub"	"Nest Hub"	["Google", "Nest"]	["Nest > speakers and displays"]	88.99
"google_home_max"	"Google Home Max"	["Google", "Nest"]	["Nest > speakers and displays"]	299.00
"google_home_mini"	"Google Home Mini"	["Google", "Nest"]	["Nest > speakers and displays"]	49.00
"google_pixel_5"	"Google Pixel 5"	["Google", "Pixel"]	["Pixel > phones"]	699.00
"google_pixel_4a_with_5g"	"Google Pixel 4a with 5G"	["Google", "Pixel"]	["Pixel > phones"]	499.00
"google_pixel_4a"	"Google Pixel 4a Phones"	["Google", "Pixel"]	["Pixel > phones"]	349.00
"google_pixel_stand"	"Google Pixel Stand"	["Google", "Pixel"]	["Pixel > featured accessories"]	79.00
"google_pixel_buds"	"Google Pixel Buds"	["Google", "Pixel"]	["Pixel > featured accessories"]	179.00
"google_pixel_5_case"	"Google Pixel 5 Case"	["Google", "Pixel"]	["Pixel > featured accessories"]	40.00
"google_pixel_4a_5g_case"	"Google Pixel 4a (5G) Case"	["Google", "Pixel"]	["Pixel > featured accessories"]	40.00
"google_pixel_4a_case"	"Google Pixel 4a Case"	["Google", "Pixel"]	["Pixel > featured accessories"]	40.00

Example search request and response

For example, if you search for "Google speaker", then you would get "nest_mini_2nd_gen", "nest_audio", "nest_hub_max", "nest_hub", "google_home_max" and "google_home_mini" in no specific order.

Example search request and response

Java

import com.google.cloud.retail.v2.SearchRequest;
import com.google.cloud.retail.v2.SearchRequest.BoostSpec;
import com.google.cloud.retail.v2.SearchRequest.BoostSpec.ConditionBoostSpec;
import com.google.cloud.retail.v2.SearchResponse;
import com.google.cloud.retail.v2.SearchServiceClient;

public static void searchProductsWithBoostSpec(String query, int pageSize,
    String condition, float boostStrength) throws IOException, InterruptedException {
  BoostSpec boostSpec = BoostSpec.newBuilder()
      .addConditionBoostSpecs(ConditionBoostSpec.newBuilder()
          .setCondition(condition)
          .setBoost(boostStrength)
          .build())
      .build();

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

  try (SearchServiceClient searchClient = SearchServiceClient.create()) {
    SearchResponse response = searchClient.search(searchRequest).getPage().getResponse();
    System.out.println("Search response: " + searchResponse);
  }
}

Example boost spec

Suppose that you want to prioritize the cheaper products (less than 95 dollars) and deprioritize the expensive ones (higher than 95 dollars). You can apply a boost spec as:

JSON

{
  condition_boost_specs {
    condition: "price: IN(*, 95.0e)"
    boost: 0.5
  }
  condition_boost_specs {
    condition: "price: IN(95.0e, *)"
    boost: -0.5
  }
}

In the result, "nest_mini_2nd_gen", "google_home_mini" and "nest_hub" might be the first three, while "nest_audio", "nest_hub_max" and "google_home_max" might be last three. However, no specific order is predetermined, in contrast to ordering by price, as discussed in Filter and order results.