Skip to main content

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:

  1. 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.
  2. Rank. The remaining products are sorted by the profile's Ranking Order.
  3. 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.

CriterionRanks 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_byResults are ordered by
NoneBoost score. Products with the same boost score are ordered by relevance score
price.amount:ascPrice. Products with the same price are ordered by boost score, then relevance score
price.amount:asc,created_at:descPrice, then creation date. Remaining ties are ordered by boost score. Relevance score is not used
Three fieldsThe 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:

CriterionSkipped whenPositions it takes
Request sortThe request has no sort_byOne per sort_by field
BoostsNo profile boost or search rule boost appliesOne
Text relevanceThe request is a browse request (q=*)One
AttributeNeverOne

Three rules decide the result:

  1. 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_by below an attribute keeps only its first field.
  2. 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.
  3. 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_order to 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:

ProductIn stockPrice
Trail Runner LiteNo50.00
Trail Runner RacerYes100.00
Trail Runner ShoeYes200.00
Ranking OrderResults
DefaultTrail Runner Lite, Trail Runner Racer, Trail Runner Shoe
In-stock rank firstTrail 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:

RequestRanked by
Keyword search, no sort_byIn stock, boost score, relevance score
Keyword search, one sort_by fieldIn stock, sort_by field, boost score. Relevance is cut
Keyword search, two sort_by fieldsIn stock, both sort_by fields. Boosts and relevance are cut
tip

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" }
]
}
RequestRanked by
Keyword search, no sort_by, no boosts applyRelevance score, popularity
Keyword search, no sort_by, boosts applyBoost score, relevance score, popularity
Keyword search, one sort_by field, boosts applysort_by field, boost score, relevance score. Popularity is cut
Browse (q=*), no sort_by, boosts applyBoost 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:

ProductMatchesPopularity
Drill Bit Setdrill only900
Cordless Drillcordless and drill300
Ranking OrderResults
Popularity below relevanceCordless Drill, Drill Bit Set
Popularity above relevanceDrill 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" }
]
}
RequestRanked by
Keyword search, sort_by=price.amount:asc, boosts applyRelevance score, boost score, price
Browse (q=*), sort_by=price.amount:asc, boosts applyBoost score, price
Browse (q=*), sort_by=price.amount:asc, no boosts applyPrice

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" }
]
}
RequestRanked by
Browse (q=*), no sort_by, no boosts applyPopularity, creation date
Browse (q=*), no sort_by, boosts applyBoost score, popularity, creation date
Keyword search, no sort_by, boosts applyBoost score, relevance score, popularity. Creation date is cut
Browse (q=*), sort_by=price.amount:asc, boosts applyPrice, 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, or text_relevance, or lists one more than once. Each must appear exactly once.
  • Has more than three attribute criteria, 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.amount is 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 attribute criterion.
  • boosts, when the profile has its own boosts.

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 boosts to a profile can make its stored Ranking Order invalid. The update returns 400. 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_by requests leave no room. Under the default order, a request with three sort_by fields 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_by price is. When the request's currency is not supported, the search returns 400. A price attribute that the walk cuts before reaching it is not checked.
  • Autocomplete is not affected. Autocomplete does not use the Ranking Order.
Ask External AI