Skip to main content

Text Relevance

The relevance score measures how well a product matches the search text. The text_relevance criterion in the Ranking Order ranks products by it. Browse requests (q=*) have no relevance score, so the criterion is skipped on them.

Relevance Score​

The relevance score is built from signals in a fixed priority order. A lower signal only breaks ties on the signals above it, however large its difference. For example, with max_score or max_weight, a product matching both words of cordless drill always ranks above one matching only drill, even if that one is an exact match in a heavier field. Under max_weight, the exception is a match only in weight 0 fields (see Field Weights).

With the default text_match_type of max_score, the order is:

PrioritySignalRanks higher whenSetting
1Query words matchedMore query words are found across all query fields, including typo-corrected and partially typed words—
2Words in the fieldMore query words, including typo-corrected and partially typed words, appear within 10 words of each other. Ties go to the field containing more query words overall—
3Typos and partial wordsFewer corrections were needed. A typo costs more than completing a partially typed wordtypo_tolerance, prefix
4ProximityFewer other words sit between the matched words—
5Exact matchThe field contains only the query wordsprioritize_exact_match
6Word positionThe matched word is nearer the start of the field. A word that appears more than once is judged by its last occurrenceprioritize_token_position
7Synonym matchThe product matched directly, not through a synonymdemote_synonym_match
8Field weightThe match is in a heavier fieldfields[].weight
9Fields matchedThe query matches in more fields—

Signals 2–7 form a field score, computed for each query field. Different query words can match in different fields. Word order is not a signal: shoe red and red shoe score the same for either query.

Typo correction, compound words, and word dropping also decide which products are found at all. By default each runs only when a stricter search finds nothing. So if one product matches shoez as typed, products named shoes are not returned. See Handling Typos.

Field Weights​

fields[].weight on a search profile sets how much a match in each field counts. See Create a Search Profile for how to set it.

  • With the default text_match_type of max_score, a product with laptop in the name (weight 10) ranks higher than one with laptop only in description (weight 5) when both match equally well. A better description match, such as an exact one, still ranks first.
  • Under max_score and max_weight, only the order of the weights matters, so 15:1 ranks the same as 10:9. Under sum_score, their proportions matter.
  • Under max_weight and sum_score, a product matching only in weight 0 fields gets the lowest relevance score and ranks below every product that matches a weighted field. Once any field has a weight, fields without one count as weight 0. Give every field that should affect ranking a weight above 0.
  • When no field has a weight, field order sets precedence: fields listed earlier rank higher.

Text Match Types​

text_match_type on a search profile changes where field weight sits. The default suits most catalogs.

text_match_typeEffect
max_score (default)The best field score is used. Weight only breaks ties between equally good matches. Suits general product search
max_weightThe highest-weighted matched field is used, and weight moves above signal 2. A match in a heavier field wins even when a lighter field matches better. Use when field importance matters more than match quality
sum_scoreSignals 1–8 are replaced by the sum of each matched field's score multiplied by its weight, rewarding matches in several fields. Query words matched is not ranked, so a product matching one query word in several fields can rank above a product matching every query word

Example. A profile queries name (weight 10) and description (weight 5). A search for drill finds product A named Drill Bit Set and product B whose description is exactly drill. B has the better field score because it is an exact match.

  • max_score: B ranks first.
  • max_weight: A ranks first.

Ranking Settings​

ranking_settings on a search profile controls signals 5 and 6:

{
"ranking_settings": {
"prioritize_exact_match": true,
"prioritize_token_position": true
}
}

Both are optional. On update, the object is replaced as a whole. Send "ranking_settings": null to restore the defaults. Ranking settings do not apply to autocomplete.

prioritize_exact_match​

Default true. A field is an exact match when it contains only the query words, in any order, ignoring case. For cordless drill, Cordless Drill ranks above Cordless Drill Kit. With false, the two tie on this signal.

A single-word query is exact only when matched as typed, without typo correction or partial word completion. Turn this off only when an exact field match carries no more intent than a partial one.

prioritize_token_position​

Default false. When true, a match nearer the start of a field ranks higher. For bosch, Bosch Cordless Drill ranks above Drill Bit Set for Bosch.

Turn it on when field values lead with the most significant words, such as names that start with the brand. Leave it off for descriptive text.

Where Relevance Ranks​

The relevance score takes one of the three sort positions. In the default Ranking Order it ranks last, after the request sort and boosts, so it only orders products those leave tied. When they fill all three positions, relevance is not used.

An attribute criterion placed below text relevance only reorders products with an exactly equal relevance score. How often scores tie varies by catalog and query, so check text_match_info on your own queries before relying on it. See the Ranking Order examples.

Inspecting Relevance​

Each keyword-search hit includes text_match_info with the signals behind its score, such as tokens_matched, best_field_weight, and typo_prefix_score. Pinned products, and hits with no relevance score, do not include it. Use it to debug ranking. Under sum_score, only score and fields_matched are meaningful. The score is only comparable within one search and is not a match percentage, so do not show it to shoppers or filter on it.

Ask External AI