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:
| Priority | Signal | Ranks higher when | Setting |
|---|---|---|---|
| 1 | Query words matched | More query words are found across all query fields, including typo-corrected and partially typed words | — |
| 2 | Words in the field | More 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 | — |
| 3 | Typos and partial words | Fewer corrections were needed. A typo costs more than completing a partially typed word | typo_tolerance, prefix |
| 4 | Proximity | Fewer other words sit between the matched words | — |
| 5 | Exact match | The field contains only the query words | prioritize_exact_match |
| 6 | Word position | The matched word is nearer the start of the field. A word that appears more than once is judged by its last occurrence | prioritize_token_position |
| 7 | Synonym match | The product matched directly, not through a synonym | demote_synonym_match |
| 8 | Field weight | The match is in a heavier field | fields[].weight |
| 9 | Fields matched | The 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_typeofmax_score, a product withlaptopin thename(weight 10) ranks higher than one withlaptoponly indescription(weight 5) when both match equally well. A better description match, such as an exact one, still ranks first. - Under
max_scoreandmax_weight, only the order of the weights matters, so15:1ranks the same as10:9. Undersum_score, their proportions matter. - Under
max_weightandsum_score, a product matching only in weight0fields 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 weight0. Give every field that should affect ranking a weight above0. - 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_type | Effect |
|---|---|
max_score (default) | The best field score is used. Weight only breaks ties between equally good matches. Suits general product search |
max_weight | The 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_score | Signals 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.