Custom ranking rules

There are two types of ranking rules in Meilisearch: built-in ranking rules and custom ranking rules. This article describes the main aspects of using and configuring custom ranking rules.

Custom ranking rules promote certain documents over other search results that are otherwise equally relevant.

Meilisearch supports two types of custom rules: one for ascending sort and one for descending sort.

To add a custom ranking rule, you have to communicate the attribute name followed by a colon (:) and either asc for ascending order or desc for descending order.

• To apply an ascending sort (results sorted by increasing value of the attribute): attribute_name:asc

• To apply a descending sort (results sorted by decreasing value of the attribute): attribute_name:desc

The attribute must have either a numeric or a string value in all of the documents contained in that index.

You can add this rule to the existing list of ranking rules using the update settings endpoint or update ranking rules endpoint.

Suppose you have a movie dataset. The documents contain the fields release_date with a timestamp as value, and movie_ranking, an integer that represents its ranking.

The following example creates a rule that makes older movies more relevant than recent ones. A movie released in 1999 will appear before a movie released in 2020.

release_date:asc

The following example will create a rule that makes movies with a good rank more relevant than movies with a lower rank. Movies with a higher ranking will appear first.

movie_ranking:desc

The following array includes all built-in ranking rules and places the custom rules at the bottom of the processing order:

[
  "words",
  "typo",
  "proximity",
  "attribute",
  "sort",
  "exactness",
  "release_date:asc",
  "movie_ranking:desc"
]

Meilisearch allows users to define sorting order at query time by using the sort search parameter. There is some overlap between sorting and custom ranking rules, but the two do have different uses.

In general, sort will be most useful when you want to allow users to define what type of results they want to see first. A good use-case for sort is creating a webshop interface where customers can sort products by descending or ascending product price.

Custom ranking rules, instead, are always active once configured and are useful when you want to promote certain types of results. A good use-case for custom ranking rules is ensuring discounted products in a webshop always feature among the top results.