Search Settings API Overview

Kibo eCommerce includes a default search relevancy model out of the box; however, using the Kibo eCommerce API you can adjust some search settings to better suit your needs.

Note:  To make your search settings effective you must set the customWeightInStorefrontSearch property to true. For more information, refer to the commerce/catalog/admin/attributedefinition/attributes resource guide.

Use the GetSettings operation of the commerce/catalog/admin/search resource to retrieve your site's current search settings.

Kibo eCommerce's Search Settings

Kibo eCommerce has the following search settings:

{
	"siteSearchSettings": [
		{
			"settingsName": "string",
			"isDefault": boolean,
			"customFields": [],
			"customBoosts": [],
			"siteKeywordRelevancy": {
				"productCodeWeight": int,
				"productCodeLooseWeight": int,
				"nameWeight": int,
				"descriptionWeight": int,
				"keywordsWeight": int,
				"attributesWeight": int,
				"upcWeight": int,
				"mpnWeight": int,
				"categoryNamesWeight": int
			},
			"sitePhraseRelevancy": {
				"nameWeight": int,
				"descriptionWeight": int,
				"attributeWeight": int
			},
			"minimumMatchPercent": int
		}
	],
	"searchSynonymSettings": {
		"mainPartBoost": int,
		"synonymPartBoost": int,
		"expandSynonyms": boolean
	}
}

You can use the UpdateSettings operation of the commerce/catalog/admin/search resource to update these settings.

Adjustable Search Settings

You can adjust the following search settings:

Search Setting Description
siteKeywordRelevancy The keyword relevancy settings that you want Kibo eCommerce to use.

Refer to the Keyword Relevancy section below for more information about the various keyword relevancy settings you can configure.
customFields The custom attribute fields that you want Kibo eCommerce to search on.

You can use this field to effectively boost the weight of particular attributes. Refer to the Custom Fields section below for more information.
customBoosts The custom boost functions that you want Kibo eCommerce to use.
minimumMatchPercent The minimum match (MM) percent is a percentage of the number of search terms that must match or can be missing. Kibo eCommerce's default MM percent is 75%.

Refer to the Minimum Match Percent section below for more information.
sitePhraseRelevancy The phrase relevancy settings that you want Kibo eCommerce to use.

Phrases are collections of strings enclosed in quotation marks. These settings are similar to the keyword relevancy settings, except they apply to phrases. Refer to the Keyword Relevancy section below for more information about the similar keyword relevancy settings.
searchSynonymSettings The search synonym settings that you want Kibo eCommerce to use.

Search synonyms are synonyms to user search queries that you want Kibo eCommerce to match on. For example, if a user searches for blouse, you want Kibo eCommerce to show all search results that would appear if a user searched for shirt as well. In this example, blouse and shirt are search synonyms. Refer to the Search Synonyms section below for more information about search synonym settings.

Keyword Relevancy

You can configure the relative weights of several product keywords that Kibo eCommerce uses to calculate the rank of each product in the search results.

You can set each keyword relevancy setting to a positive integer value between 1-10. A higher value adds more weight to the setting, resulting in matches being ranked higher in search results.

Refer to the following table for more information about the keyword relevancy settings you can configure:

Keyword Field Description
productCodeWeight Matches strictly on the entire value of the product code.
productCodeLooseWeight Matches loosely on the product code, splitting it up for symbols, punctuation, as well as the boundaries between letters and numbers.
nameWeight Matches on the product name.
descriptionWeight Matches on the product full description.
keywordsWeight Matches on the product SEO keywords.

This field is not displayed on the product details page on the storefront. You can use this field to add words that are important for products to be matched on.

If a keyword is in the product name, description and keywords then the product will be ranked higher than if the keyword was just in the product name and description.
attributesWeight Matches against the combined values of the product attributes (properties, options, and extras).

There are two API-only attribute settings for each attribute that determines whether or not the attribute is matched:
  • SearchSettings.SearchableInStorefront
    Indicates whether the attribute's value should be matched against on product searches. This defaults to true.
  • SeachSettings.SearchDisplayValue
    Indicates whether the display value or canonical value is used for matching on product searches. The default is false, which means that the canonical value will be used. This is only applicable for attributes with a data type of string.
upcWeight Matches against the entire UPC code if a value has been populated for the product.
mpnWeight Matches against the entire MPN if a value has been populated for the product.
categoryNamesWeight Matches against the names of the categories that the product belongs to.

Custom Fields

You can add additional attributes that you want Kibo eCommerce to match on for keyword searches, along with a separate weight value for each attribute.

Note:  This field does not support other first-class product fields such as productShortDescription.

To use this field, specify the attribute's fully qualified name (FQN) and an integer weight relative to the siteKeywordRelevancy weights.

The format of this field is as follows:

"customFields": [
	{
		"fieldName": "tenant~color",
		"fieldWeight": 5
	}
]

Minimum Match Percent

The minimum match (MM) percent indicates the percentage of terms in a search query that must be contained in the search results. In order to calculate how many terms are matched, Kibo eCommerce multiplies the MM value by the number of terms in the search query and either rounds down or up depending on the MM value. The default value is 75%.

You can specify a minimum match percent using the minimumMatchPercent field.

Note:  If you have search synonyms that match on a user's search query, Kibo eCommerce ignores the minimumMatchPercent value and uses a minimum match of 100% instead. Refer to Minimum Match and Synonyms for more information.

Valid values for the MM percent are integers between 0-100, including negative integers. A positive integer indicates how many terms are required to match, rounded down. A negative integer indicates how many terms can be missing, rounded up.

The higher the MM percent the more narrow the product results Kibo eCommerce returns.

Refer to the following table for some example outcomes of different MM percents:

MM Percent Number of Search Terms Outcome
75% 5 3 terms must match

(5 * 0.75 = 3.75, rounded down to 3)
50% 5 2 terms must match

(5 * 0.5 = 2.5, rounded down to 2)
25% 5 1 term must match

(5 * 0.25 = 1.25, rounded down to 1)
-25% 5 4 terms must match
(1 term can be missing)

(5 * 0.75 = 3.75, rounded up to 4)
-50% 5 3 terms must match
(2 terms can be missing)

(5 * 0.5 = 2.5, rounded up to 3)

Search Synonyms

You can add search synonyms to Kibo eCommerce's search settings to expand Kibo eCommerce's search capabilities. Search synonyms are synonyms to user search queries to which Kibo eCommerce expands the search results. For example, a user may search for boots, but you want the search results to also include results for shoes, slippers, and pumps. You can use search synonyms to accomplish this.

Enable Search Synonym Settings

To enable the search synonyms settings, in the search settings set expandSynonyms to True.

Synonym Definitions

Synonym definitions are individual definitions of synonyms. Synonym definitions are scoped to a particular tenant, site, and locale code.

A synonym definition can include either a key and a list of synonyms, or just a list of synonyms. Refer to Synonym Expansion Types for more information about using a key.

Multiple synonym definitions for a site are placed in a site's synonym definition collection. Kibo eCommerce automatically adds any synonym definitions you create to the applicable synonym definition collection. Refer to Synonym Definition Collections for more information.

Synonym Definition Operations

You can perform the following operations on synonym definitions:

Synonym Definition Body

A synonym definition has the following body:

{
	"key": "string",
	"synonymId": "int",
	"synonyms": "string"
}

Synonym Definition Collections

Synonym definition collections are collections of multiple synonym definitions. Each site can have one synonym definition collection. Kibo eCommerce automatically adds any synonym definitions you create to the applicable synonym definition collection.

Synonym Definition Collection Operations

You can perform the following operations on synonym definitions:

Synonym Definition Collection Body

A synonym definition collection has the following body:

{
	"localeCode": "string",
	"siteId": "int",
	"synonymDefinitions": [
		{
			"key": "string",
			"synonymId": "int",
			"synonyms": "string"
		}
	],
	"tenantId": "int"
}

Synonym Expansion Types

There are two search synonym expansion types: one way and two way.

One Way

The one way expansion type includes a key and a set of synonyms to which Kibo eCommerce expands the search results. This is a one way expansion; Kibo eCommerce does not expand the search results to the key or any other listed synonyms.

Note:  You are not required to provide a key. Do not provide a key for two way expansion.

For example, you specify the following:

{
	"localeCode": "en-us",
	"siteId": "22327",
	"synonymDefinitions": [
		{
			"key": "blouse",
			"synonymId": "1",
			"synonyms": [		
				"shirt", "top", "T-shirt"		
			]
		}
	],
	"tenantId": "18263"
}

In the above example, if a user searches for blouse, then Kibo eCommerce expands the search results to include the results for shirt, top, and T-shirt. However, if a user searches for top, Kibo eCommerce does not expand the search results to include the results for blouse, shirt, or T-shirt.

Two Way

The Two Way expansion type does not include a key, but instead only contains a list of synonyms to which Kibo eCommerce expands. This is a two way expansion; for any listed synonym, Kibo eCommerce expands the search results to all other listed synonyms.

For example, you specify the following:

{
	"localeCode": "en-us",
	"siteId": "22327",
	"synonymDefinitions": [
		{	
			"synonymId": "1",		
			"synonyms": [		
				"shirt", "top", "T-shirt", "sweater", "blouse", "pullover"		
			]
		}
	],
	"tenantId": "18263"
}

In the above example, if a user searches for top, then Kibo eCommerce expands the search results to include the results for shirt, T-shirt, sweater, blouse, and pullover.

Note:  Kibo eCommerce only matches multi-word search terms if they are contained within quotes in the search query. If a multi-word search term is not contained within quotes in the search query, Kibo eCommerce uses each word in the search to find synonyms. For example, if a shopper searches for blue shoes without quotes, Kibo eCommerce expands both blue and shoes to any applicable synonyms.

Boosting

Kibo eCommerce also allows you to set boost values for synonyms using the searchSynonymSettings. Boost values are separated into the following two different parts:

If you set the mainPartBoost higher than the synonymPartBoost, then Kibo eCommerce displays the search results that match on a user's search terms higher in the search results. If you set the synonymPartBoost higher, then Kibo eCommerce displays the search results that match on an expanded synonym higher in the search results.

For example, you specify the following:

"searchSynonymSettings": {
	"mainPartBoost": 1.2,
	"synonymPartBoost": 1.1
}

In the above example, any results that match the user's search query terms appear higher in the search results list than any results that match an expanded synonym.

The following are typical boost values:

Another multiplier of mainPartBoost and synonymPartBoost that can be applied is phraseBoost. PhraseBoost can further raise the relevancy of results in which the phrase is found with both words next to each other, and is set to a default of 1.0 that will still score those results higher. The phraseBoost value can be changed when needed, allowing more tuning if the search results are not as expected based on the data distribution.

Match On Any Term

The setting matchOnAnyTerm can be set to allow for a looser query. As detailed below, minimum match percents do not work with synonym expansion which means that every term must exist in a document for it to be displayed as a search result. However, matchOnAnyTerm can reduce this requirement when synonyms are in use. With matchOnAnyTerm, a document can be returned by the search as long as at least one term exists within it.

For example:

If matchOnAnyTerm is not enabled, then only documents that contain both ("bbq" and "grill") or ("propane" and "grill") are returned. When matchOnAnyTerm is enabled, then any document that contains ("bbq" or "grill" or "propane") will also be returned. Relevancy is still taken into account, so the documents that contain more of the terms or the full phrase will be ranked higher.

Minimum Match and Synonyms

When you use both a minimum match percent and a synonym definition list, Kibo eCommerce uses a minimum match of 100% for the search query and its synonyms.

Refer to the following table for some examples of this behavior:

Search Query Synonym Definition List Expanded Search
Gucci shoes
"synonymDefinitions": [
	{
		"key": "shoes",
		"synonymId": "1",
		"synonyms": [		
			"boots", "booties", "pumps", "heels", "sandals", 
"sneakers", "flats", "loafers", "oxfords" ] } ]
Gucci shoes, Gucci boots, Gucci booties, Gucci pumps,
Gucci heels, Gucci sandals, Gucci sneakers, Gucci flats,
Gucci loafers, Gucci oxfords
Red Shoes
"synonymDefinitions": [
	{
		"key": "shoes",
		"synonymId": "1",
		"synonyms": [		
			"boots", "booties", "pumps"
		]
	},
	{
		"key": "red",
		"synonymId": "2",
		"synonyms": [		
			"magenta", "ruby", "pink"
		]						
	}
]
Red shoes, red boots, red booties, red pumps,
magenta shoes, magenta boots, magenta booties, magenta pumps,
ruby shoes, ruby boots, ruby booties, ruby pumps,
pink shoes, pink boots, pink booties, pink pumps

If you do not have search synonyms that match on a user's search query, Kibo eCommerce uses the minimumMatchPercent value. Refer to Minimum Match Percent for more information.

Search Tuning Rules

Kibo eCommerce's search settings also include search tuning rules that allow you to promote products to the top of search results and category pages, as well as block products from appearing in search results and category pages.

Refer to Search Tuning Rules for more information about creating and modifying search tuning rules.

Default Relevancy Weights

Kibo eCommerce's search settings include the following default relevancy weights:

"siteKeywordRelevancy": {
	"productCodeWeight": 10,				
	"nameWeight": 8,
	"descriptionWeight": 4,
	"keywordsWeight": 4,
	"attributesWeight": 1,
	"upcWeight": 2,
	"mpnWeight": 2,
	"categoryNamesWeight": 2
},
"sitePhraseRelevancy": {
	"nameWeight": 5,
	"descriptionWeight": 3,
	"attributeWeight": 1
}

Deep Paging

When you're paging through thousands or more of products using the Kibo eCommerce API, Kibo eCommerce recommends using deep paging, which optimizes your retrieve requests. Traditional paged requests require Kibo eCommerce to create an internal queue of paged product results using a combination of pageSize and startIndex, which requires a large amount of memory and subsequently degrades Kibo eCommerce's performance.

With deep paging, on your first request you do not specify a startIndex, and instead only specify a pageSize and initialize the cursorMark parameter using an asterisk (*). Kibo eCommerce then returns the first set of product results, and provides an encoded nextCursorMark value, which you can then use for the cursorMark in the next request. This allows Kibo eCommerce to optimally page through products without using the same amount of memory as traditional paged requests.

You can use deep paging in the storefront Search and GetProducts operations.

Deep Paging Examples

For example, you want to page through 5,000 thousand products 50 at a time in a search request for black and sorted by product name. To optimize this request, you perform the following initial request:

Get
api/commerce/catalog/storefront/productsearch/search/?sortBy=productName+asc&pageSize=50&query=black&cursorMark=*

The above request returns the following response:


{
	"facets": [],
	"nextCursorMark": "AoI%2fGXZlcnRpY2FsIGNvbnZlcnQgMi4wIGludGVyY2hhbmd",
	"startIndex": 0,
	"pageSize": 50,
	"pageCount": 20,
	"totalCount": 5000,
	"items": [
		{
			"productCode": "119Cfg002",
			"productSequence": 1109,
			"productUsage": "Configurable",
			"fulfillmentTypesSupported": [
				"DirectShip"
			],
			"goodsType": "Physical",
			"content": {
				"productName": "1 Gallon Black paint",
				"productFullDescription": "New",
				"productShortDescription": "TEST text",
				"metaTagTitle": "1 Gallon Black paint",
				"seoFriendlyUrl": "1-gallon-black-paint",
				"productImages": []
			},
			"purchasableState": {
			"isPurchasable": false,
			"messages": [
			{
				"severity": "Info",
				"source": "ConfigurableProduct",
				"message": "Not done configuring",
				"validationType": "IncompleteProductConfiguration"
			}
		]
	},
	......
}

In the above response, Kibo eCommerce returns an encoded value for nextCursorMark. In the next request, set cursorMark to the same value you received for nextCursorMark:

Get
api/commerce/catalog/storefront/productsearch/search/?sortBy=productName+asc&pageSize=50&query=black&cursorMark=AoI%2fGXZlcnRpY2FsIGNvbnZlcnQgMi4wIGludGVyY2hhbmd

You can repeat this process of setting cursorMark to the same value you receive for nextCursorMark to page through all your product search results. When nextCursorMark is null, you've reached the end of the paged results.