Ranking Search Results
This guide explains how Catalog Search orders results, so you can predict why one product ranks above another and choose the right setting to change it.
How Results Are Ordered
A search orders results in three steps:
- Filter. Filters decide which products can appear. These include search profile filters, exclusions, search rule filters, and the search request's
filter_by. Filters never change the order, only what appears in the results. - Rank. The remaining products are sorted by the profile's Ranking Order.
- Pin and hide. Pinned products are placed at their positions, and hidden products are removed.
Ranking Criteria
A search profile's ranking_order is a list of ranking criteria. Earlier criteria rank first. Each later criterion only orders the products that every earlier criterion leaves tied.
| Criterion | Ranks by |
|---|---|
{ "type": "request_sort" } | The search request's sort_by fields, in the order sent. See Request Sort |
{ "type": "boosts" } | The boost score from profile boosts and search rule boosts. See Boost Scores |
{ "type": "text_relevance" } | How well a product matches the search text. See Text Relevance |
{ "type": "attribute", "field": "...", "order": "desc" } | A sortable product field, asc or desc. See Sortable Fields |
Default Ranking Order
When a profile has no ranking_order, it uses the default order:
[
{ "type": "request_sort" },
{ "type": "boosts" },
{ "type": "text_relevance" }
]
For example, a keyword search on a profile with boosts:
Request sort_by | Results are ordered by |
|---|---|
| None | Boost score. Products with the same boost score are ordered by relevance score |
price.amount:asc | Price. Products with the same price are ordered by boost score, then relevance score |
price.amount:asc,created_at:desc | Price, then creation date. Remaining ties are ordered by boost score. Relevance score is not used |
| Three fields | The three sort_by fields only. Boosts and relevance score are not used |
Without boosts, relevance moves up to take the boost score's place. Without request sort_by and boosts, relevance score drives ranking. The next section explains why later criteria drop out.
How a Search Applies the Ranking Order
A search ranks by at most three sort positions. Each search fills them by walking the Ranking Order from the top:
| Criterion | Skipped when | Positions it takes |
|---|---|---|
| Request sort | The request has no sort_by | One per sort_by field |
| Boosts | No profile boost or search rule boost applies | One |
| Text relevance | The request is a browse request (q=*) | One |
| Attribute | Never | One |
Three rules decide the result:
- The walk stops at three positions. Later criteria are dropped with no error. The cut can fall partway through the request sort, so a two-field
sort_bybelow an attribute keeps only its first field. - A repeated field keeps its first occurrence. When the request sort and an attribute name the same field, the one higher in the Ranking Order is used, with its direction. The later one is dropped and does not take a position.
- Skipped criteria take no position. On a browse request, text relevance is skipped, so the criterion below it moves up.
The same Ranking Order can therefore rank differently from one request to the next. The examples below show this for each order.
Set a Ranking Order
Set ranking_order when you create or update a search profile:
curl -X PUT https://useast.api.elasticpath.com/v2/pcm/catalogs/search-profiles/{profile_id} \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"data": {
"type": "catalog_search_profile",
"attributes": {
"ranking_order": [
{ "type": "attribute", "field": "extensions.products(Details).in_stock_rank", "order": "desc" },
{ "type": "request_sort" },
{ "type": "boosts" },
{ "type": "text_relevance" }
]
}
}
}'
- Reading a profile always returns its effective Ranking Order. A profile that never set one returns the default order.
- On update, omit
ranking_orderto keep the current order. Send"ranking_order": []to reset it to the default. - The new order applies to search requests that use the profile. Autocomplete does not use the Ranking Order.
Examples
The examples use extension fields from a Details template. Replace them with sortable fields from your own catalog. Example products and values are illustrative.
Keep Out-of-Stock Products Last
Goal: Out-of-stock products rank below in-stock ones, whatever sort the shopper picks.
Index a sortable integer field, in_stock_rank, that is 1 for in-stock products and 0 for out-of-stock products. Place it above the request sort:
{
"ranking_order": [
{ "type": "attribute", "field": "extensions.products(Details).in_stock_rank", "order": "desc" },
{ "type": "request_sort" },
{ "type": "boosts" },
{ "type": "text_relevance" }
]
}
A shopper searches trail runner and sorts by price.amount:asc:
| Product | In stock | Price |
|---|---|---|
| Trail Runner Lite | No | 50.00 |
| Trail Runner Racer | Yes | 100.00 |
| Trail Runner Shoe | Yes | 200.00 |
| Ranking Order | Results |
|---|---|
| Default | Trail Runner Lite, Trail Runner Racer, Trail Runner Shoe |
| In-stock rank first | Trail Runner Racer, Trail Runner Shoe, Trail Runner Lite |
The price sort still orders products within each group. How other requests rank on a profile with boosts:
| Request | Ranked by |
|---|---|
Keyword search, no sort_by | In stock, boost score, relevance score |
Keyword search, one sort_by field | In stock, sort_by field, boost score. Relevance is cut |
Keyword search, two sort_by fields | In stock, both sort_by fields. Boosts and relevance are cut |
A bury, a boost with a negative weight, also demotes out-of-stock products. It is part of the boost score, so under the default order it only reorders products the request sort leaves tied, and a product that matches a higher boost is not demoted. Use the Ranking Order when stock must win over the shopper's sort.
Break Relevance Ties by Popularity
Goal: Among products that match the search text equally well, the most popular rank first.
Place the attribute below text relevance:
{
"ranking_order": [
{ "type": "request_sort" },
{ "type": "boosts" },
{ "type": "text_relevance" },
{ "type": "attribute", "field": "extensions.products(Details).popularity", "order": "desc" }
]
}
| Request | Ranked by |
|---|---|
Keyword search, no sort_by, no boosts apply | Relevance score, popularity |
Keyword search, no sort_by, boosts apply | Boost score, relevance score, popularity |
Keyword search, one sort_by field, boosts apply | sort_by field, boost score, relevance score. Popularity is cut |
Browse (q=*), no sort_by, boosts apply | Boost score, popularity |
Popularity only reorders products with an exactly equal relevance score, such as two products whose name is the search text. Products with similar but unequal scores are not reordered. On browse requests, popularity orders every product the boost score leaves tied.
Rank by Popularity Before Relevance
Goal: Popular products rank above less popular ones for every match, not only for ties.
Place the attribute above text relevance:
{
"ranking_order": [
{ "type": "request_sort" },
{ "type": "boosts" },
{ "type": "attribute", "field": "extensions.products(Details).popularity", "order": "desc" },
{ "type": "text_relevance" }
]
}
A shopper searches cordless drill with no sort_by, and no boosts apply:
| Product | Matches | Popularity |
|---|---|---|
| Drill Bit Set | drill only | 900 |
| Cordless Drill | cordless and drill | 300 |
| Ranking Order | Results |
|---|---|
| Popularity below relevance | Cordless Drill, Drill Bit Set |
| Popularity above relevance | Drill Bit Set, Cordless Drill |
Every product the query matches is ordered by popularity first, so a weak match with a high value ranks above an exact match with a low one. Broad queries and many searchable fields widen the set it reorders. Relevance only orders products with equal popularity. Use this order when your popularity signal is more trusted than the text match, and keep searchable fields narrow.
Rank by Relevance Before Merchandising
Goal: Keyword searches rank by relevance. Browse pages rank by boosts and then the shopper's sort.
Place text relevance first:
{
"ranking_order": [
{ "type": "text_relevance" },
{ "type": "boosts" },
{ "type": "request_sort" }
]
}
| Request | Ranked by |
|---|---|
Keyword search, sort_by=price.amount:asc, boosts apply | Relevance score, boost score, price |
Browse (q=*), sort_by=price.amount:asc, boosts apply | Boost score, price |
Browse (q=*), sort_by=price.amount:asc, no boosts apply | Price |
On keyword searches, boosts and the shopper's sort only order products with an equal relevance score. How often scores tie varies by catalog and query, so a storefront price sort can look like it has no effect on some search result pages. Use this order only when your storefront hides sort controls on keyword searches, or when relevance must always win.
Give Browse Pages a Stable Order
Goal: Browse pages without a shopper sort show popular products first, then the newest.
Add two attributes at the end:
{
"ranking_order": [
{ "type": "request_sort" },
{ "type": "boosts" },
{ "type": "text_relevance" },
{ "type": "attribute", "field": "extensions.products(Details).popularity", "order": "desc" },
{ "type": "attribute", "field": "created_at", "order": "desc" }
]
}
| Request | Ranked by |
|---|---|
Browse (q=*), no sort_by, no boosts apply | Popularity, creation date |
Browse (q=*), no sort_by, boosts apply | Boost score, popularity, creation date |
Keyword search, no sort_by, boosts apply | Boost score, relevance score, popularity. Creation date is cut |
Browse (q=*), sort_by=price.amount:asc, boosts apply | Price, boost score, popularity. Creation date is cut |
Text relevance is skipped on browse requests, so both attributes move up. On keyword searches, the attributes only take the positions the earlier criteria leave free.
Override a Shopper Sort on the Same Field
When the request sort names a field that an attribute above it already uses, the attribute wins:
{
"ranking_order": [
{ "type": "attribute", "field": "extensions.products(Details).rating", "order": "desc" },
{ "type": "request_sort" },
{ "type": "boosts" },
{ "type": "text_relevance" }
]
}
A request with sort_by=extensions.products(Details).rating:asc,price.amount:asc is ranked by rating descending, then price, then boost score when boosts apply. The request's rating:asc is dropped and does not take a position, so the boost score fits in the third position.
If the request sort is above the attribute instead, the request's direction is used and the attribute is dropped.
Ranking Order Rules
A save returns 400 when the Ranking Order:
- Leaves out
request_sort,boosts, ortext_relevance, or lists one more than once. Each must appear exactly once. - Has more than three
attributecriteria, or repeats an attribute field, in either direction. - Names an attribute field that is not indexed and sortable. See Sortable Fields. A price field such as
price.amountis valid when the default currency's price field is indexed. - Places a criterion where it can never rank. See Criteria That Can Never Rank.
Changing an indexable field so that a Ranking Order attribute field is no longer sortable returns 409. Update the Ranking Order first.
Criteria That Can Never Rank
Some criteria apply to every search and always take a position:
- Every
attributecriterion. boosts, when the profile has its ownboosts.
A criterion placed after three of these can never rank, so the save is rejected. This Ranking Order is rejected because request_sort follows three attributes:
{
"ranking_order": [
{ "type": "attribute", "field": "extensions.products(Details).in_stock_rank", "order": "desc" },
{ "type": "attribute", "field": "extensions.products(Details).popularity", "order": "desc" },
{ "type": "attribute", "field": "created_at", "order": "desc" },
{ "type": "request_sort" },
{ "type": "boosts" },
{ "type": "text_relevance" }
]
}
data.attributes.ranking_order.3: criterion (request_sort) can never rank. 3 always-active criteria rank above it: attribute criteria, and boosts when the profile has boosts
As a result:
- A profile with three attributes must list them last, after all three built-in criteria.
- A profile with its own boosts can rank by at most two attributes.
- Adding
booststo a profile can make its stored Ranking Order invalid. The update returns400. Remove an attribute, or move it, in the same update.
Search rule boosts are not counted, because they only apply when a rule matches.
Pinned and Hidden Products
Search rules can pin and hide products after ranking, whatever the Ranking Order:
- Pinned products are placed at one-based positions across the whole result set. They do not need to match the query, but must match the active filters.
- Hidden products are removed. A product that is both pinned and hidden is hidden.
Things to Plan For
- The request sort is first only in the default order. Placing an attribute or text relevance above it can make a storefront sort control look ineffective. Check that your storefront's sort options still make sense.
- Three-field
sort_byrequests leave no room. Under the default order, a request with threesort_byfields uses all three positions, and boosts and relevance are not used. Below an attribute, the third field is cut too. - Missing values. Products without a value for a numeric or date attribute rank last in both directions. Products without a value for a text attribute rank last in ascending order and first in descending order.
- Price attributes need a supported currency. A price attribute is resolved in the request's currency and price book, as a
sort_byprice is. When the request's currency is not supported, the search returns400. A price attribute that the walk cuts before reaching it is not checked. - Autocomplete is not affected. Autocomplete does not use the Ranking Order.