Skip to main content
Search has two crucial steps: returning accurate results and ranking them. Custom ranking lets you influence the order of search results. After Algolia applies its default relevance criteria, custom ranking breaks ties using attributes you define, such as popularity, rating, or release date. This helps surface your most important content.

​
How custom ranking fits into Algolia’s ranking criteria

Algolia ranks results with a tie-breaking algorithm. It first applies the default ranking criteria, such as Typo, Geo, Words, Filters, Proximity, Attribute, and Exact. Custom ranking is the final default criterion and is only used when are still tied after the earlier criteria. For a full explanation of the ranking order, see The eight ranking criteria.

​
Use custom ranking attributes

Algolia’s default ranking criteria determine how well records match a query. When multiple records are equally relevant, custom ranking breaks ties using attributes you define, instead of falling back to arbitrary ordering such as objectID. This lets you use metrics like popularity, rating, or sales to order records that are otherwise equally relevant. Typical custom ranking attributes include number of sales, views, likes, ratings, and release date. Any boolean or numeric attribute works with custom ranking. You can also use custom ranking attributes to boost or penalize specific records. For example, you might add a boolean attribute such as promoted or discontinued and use it to rank promoted records higher or discontinued records lower. Custom ranking attributes help align relevance with the metrics that matter for your search experience. The following dataset illustrates a common use case with custom ranking on the popularity attribute in descending order:
JSON
[
  {
    "name": "Graphic t-shirt",
    "popularity": 80
  },
  {
    "name": "Limited edition t-shirt",
    "popularity": 20
  },
  {
    "name": "Basic t-shirt",
    "popularity": 200
  }
]
If you use popularity as a custom ranking attribute in descending order, a search for t-shirt ranks the most popular matching records first:
  1. Basic t-shirt
  2. Graphic t-shirt
  3. Limited edition t-shirt
You can decide whether you want the order to be descending (greater values first) or ascending (smaller values first).

​
Custom ranking precision

If a custom ranking attribute is too precise, it can prevent other attributes from influencing the ranking. When records aren’t tied, later attributes never come into play. Consider a movie index that uses rating and views (in that order) as custom ranking attributes. With precise ratings such as 4.321321, records are unlikely to share the same value. As a result, views rarely affects the ranking. This can produce less useful results. For example, a movie with slightly lower rating but significantly more views may rank lower than expected. To address this, reduce the precision of the first attribute. For example, create a truncated_rating rounded to one decimal place (4.321321 → 4.3). With more shared values, records can tie on truncated_rating, allowing views to act as a secondary ranking factor. That’s why reducing precision is critical to effective tie-breaking.

​
See also

Last modified on May 7, 2026