Commerce Search v3 extensions
Prerequisites
Custom extensions
- To add custom extensions to RunProductSearch shared search pipelines, add extension pipes for both Elasticsearch v7 and Google Retail Search using the DependencySystemSetting attribute. See the following example for guidance.
- To upgrade from Commerce Search v2 to Commerce Search v3 with existing extensions for Elasticsearch v7, update those custom extension pipes using the DependencySystemSetting attribute and replicate the pipes for both Elasticsearch v7 and Google Retail Search. See the following example for guidance.
- When you extend a shared search pipeline for Elasticsearch v7 or Google Retail Search, review the pipe order and add new custom pipes to fit through this pipeline.
- You should update any Spire Blueprints to the latest release versions for the Product Listing page, search input, and autocomplete.
Example
namespace Extensions.Modules.Search.Shared.DocumentTypes.Product.Query.Pipelines.Pipes.FormProductFilter
{
using Insite.Core.Interfaces.Dependency;
using Insite.Search.GoogleCloudRetailSearch.DocumentTypes.Product;
[DependencySystemSetting("SearchGeneral", "SearchProviderName", "Elasticsearch v7")]
public sealed class FormIsDiscontinuedFilterElasticsearchV7
: IPipe<FormProductFilterParameter, FormProductFilterResult>
{
public int Order => 450;
public FormProductFilterResult Execute(
IUnitOfWork unitOfWork,
FormProductFilterParameter parameter,
FormProductFilterResult result
)
{
var filterProperty = nameof(ElasticSearchProduct.IsDiscontinued)
.ToCamelCase();
var isDiscontinuedFilter = parameter.SearchQueryBuilder.MakeFieldQuery(
filterProperty,
"false"
);
result.AllFilters.Add(isDiscontinuedFilter);
return result;
}
}
}
namespace Extensions.Modules.Search.Shared.DocumentTypes.Product.Query.Pipelines.Pipes.FormProductFilter
{
using Insite.Core.Interfaces.Dependency;
using Insite.Search.GoogleCloudRetailSearch.DocumentTypes.Product;
[DependencySystemSetting("SearchGeneral", "SearchProviderName", "Google Retail Search")]
public sealed class FormIsDiscontinuedFilterGoogleRetailSearch
: IPipe<FormProductFilterParameter, FormProductFilterResult>
{
public int Order => 450;
public FormProductFilterResult Execute(
IUnitOfWork unitOfWork,
FormProductFilterParameter parameter,
FormProductFilterResult result
)
{
var filterProperty = nameof(GoogleCloudRetailSearchProduct.IsDiscontinued)
.ToCamelCase();
var isDiscontinuedFilter = parameter.SearchQueryBuilder.MakeFieldQuery(
filterProperty,
"false"
);
result.AllFilters.Add(isDiscontinuedFilter);
return result;
}
}
}Inline boosting
Inline boosting lets a custom extension promote or demote products in the Google Retail Search ranking for one request. Use it to rank products based on shopper context, such as the shopper's region or persona.
Inline boosting only reorders products that the search already matched. It does not add or remove products. To add or remove products, use a filter.
Inline boosting applies to Google Retail Search only. Elasticsearch v7 ignores boosts, so do not replicate the boosting pipe for Elasticsearch v7. This differs from filter pipes, which require a pipe for each search provider.
To add inline boosts, complete the following steps:
- Add a pipe to the RunProductSearch shared search pipeline with an Order value between 2671 and 2699. This range places the pipe after the pipeline applies the query, filters, and paging, and before it performs the search at 2700.
- Add the DependencySystemSetting attribute so the pipe runs only when Google Retail Search is the search provider.
- Call WithConditionBoosts on result.SearchDescriptor.
WithConditionBoosts appends to any existing boosts, so several pipes each contribute boosts to the same search.
Regional boost example
In the following example, a distributor sells region-specific product lines and tags each product with a Region custom property. The pipe reads the state on the shopper's ship-to customer and promotes products for that region.
namespace Extensions.Modules.Search.Shared.DocumentTypes.Product.Query.Pipelines.Pipes.RunProductSearch
{
using System;
using System.Collections.Generic;
using Insite.Core.Interfaces.Data;
using Insite.Core.Interfaces.Dependency;
using Insite.Core.Plugins.Pipelines;
using Insite.Search.Shared.Boosting;
using Insite.Search.Shared.DocumentTypes.Product.Query.Pipelines.Parameters;
using Insite.Search.Shared.DocumentTypes.Product.Query.Pipelines.Results;
[DependencySystemSetting("SearchGeneral", "SearchProviderName", "Google Retail Search")]
public sealed class ApplyRegionalBoosts
: IPipe<RunProductSearchParameter, RunProductSearchResult>
{
private static readonly Dictionary<string, string> RegionByState = new(
StringComparer.OrdinalIgnoreCase
)
{
{ "WA", "Northwest" },
{ "OR", "Northwest" },
{ "TX", "Southwest" },
{ "AZ", "Southwest" },
};
public int Order => 2680;
public RunProductSearchResult Execute(
IUnitOfWork unitOfWork,
RunProductSearchParameter parameter,
RunProductSearchResult result
)
{
var state = parameter.SiteContext.ShipTo?.State?.Abbreviation;
if (string.IsNullOrEmpty(state) || !RegionByState.TryGetValue(state, out var region))
{
return result;
}
result.SearchDescriptor = result.SearchDescriptor.WithConditionBoosts(
[
new SearchConditionBoost
{
Condition = $"attributes.region: ANY(\"{region}\")",
Boost = 0.4f,
},
]
);
return result;
}
}
}parameter.SiteContext also exposes the signed-in user, bill-to, persona, and website. Build boosts from any of these values.
Conditions and limits
Each SearchConditionBoost has the following properties:
- Condition – A Google Retail Search filter expression that selects the products to boost.
- Boost – The strength of the boost, from -1 to 1. Positive values promote products, and negative values demote them. The platform clamps values outside this range and ignores a value of 0.
Follow these rules when you write a condition:
- Reference system fields, such as brands and categories, by their bare name.
- Reference all other fields as attributes. followed by the camel-cased field name. This rule covers indexed product fields, product attributes, and custom properties. For example, a Region custom property becomes attributes.region.
- Match values with ANY("VALUE").
- Match boolean values as lowercase text, such as ANY("true"), because booleans index as lowercase text.
- Reference only indexable fields.
Adjust boost values in small steps, and test the search results after each change.
Google Retail Search accepts a maximum of 20 boosts per request. The platform drops any additional boosts and logs a warning.
An invalid condition does not cause the search to fail. Google Retail Search ignores the invalid condition and applies the valid ones. The platform logs each rejected condition as a warning. When a boost has no visible effect, check Application Logs for this warning first.
Rate limit handling
The Commerce Search Service enforces a rate limit of 300 requests per minute on the Search API and 1200 requests per minute on the Autocomplete API. When Commerce Search v3 is enabled and the service returns HTTP 429 Too Many Requests:
- The Search API falls back to Elasticsearch until the rate limit resets. Results during the fallback window reflect the Elasticsearch index and may differ from Commerce Search v3 results.
- The Autocomplete API returns an empty result set so shoppers use the search results page.
Commerce Search v3 writes a warning to the log when it triggers the fallback and throttles subsequent warnings to one entry per minute to prevent log flooding. The log entry identifies the API that hit the rate limit.