> ## Documentation Index
> Fetch the complete documentation index at: https://www.meilisearch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom ranking rules

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

There are two types of ranking rules in Meilisearch: [built-in ranking rules](/capabilities/full_text_search/relevancy/ranking_rules) and custom ranking rules. This article describes the main aspects of using and configuring custom ranking rules.

## Ascending and descending sorting rules

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.

<Warning>
  If some documents do not contain the attribute defined in a custom ranking rule, the application of the ranking rule is undefined and the search results might not be sorted as you expected. Make sure that any attribute used in a custom ranking rule is present in all of your documents.
</Warning>

You can add this rule to the existing list of ranking rules using the [update settings endpoint](/reference/api/settings/update-all-settings) or [update ranking rules endpoint](/reference/api/settings/update-rankingrules).

## How to use custom ranking rules

Custom ranking rules sort results in lexicographical order. For example, `Elena` will rank higher than `Ryu` and lower than `11` in a descending sort.

Since this operation does not take into consideration document relevancy, in the majority of cases you should place custom ranking rules after the built-in ranking rules. This ensures that results are first sorted by relevancy, and the lexicographical sorting takes place only when two or more documents share the same ranking score.

Setting a custom ranking rule at a high position may result in a degraded search experience, since users will see documents in alphanumerical order instead of sorted by relevance.

## Example

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.

<CodeGroup>
  ```
  release_date:asc
  ```
</CodeGroup>

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.

<CodeGroup>
  ```
  movie_ranking:desc
  ```
</CodeGroup>

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

<CodeGroup>
  ```json theme={null}
  [
    "words",
    "typo",
    "proximity",
    "attributeRank",
    "sort",
    "wordPosition",
    "exactness",
    "release_date:asc",
    "movie_ranking:desc"
  ]
  ```
</CodeGroup>

## Sorting at search time and custom ranking rules

Meilisearch allows users to define [sorting order at query time](/capabilities/filtering_sorting_faceting/how_to/sort_results) by using the [`sort` search parameter](/reference/api/search/search-with-post#body-sort). 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.

<Tip>
  Meilisearch does not offer native support for promoting, pinning, and boosting specific documents so they are displayed more prominently than other search results. Consult these Meilisearch blog articles for workarounds on [implementing promoted search results with React InstantSearch](https://blog.meilisearch.com/promoted-search-results-with-react-instantsearch) and [document boosting](https://blog.meilisearch.com/document-boosting).
</Tip>