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

# Custom ranking

> Learn how to use custom ranking attributes to order records by popularity, rating, release date, or other metrics.

export const Records = () => <Tooltip tip="A record is a searchable object in an Algolia index. Each record consists of named attributes." cta="Algolia records" href="/doc/guides/sending-and-managing-data/prepare-your-data#algolia-records">
    records
  </Tooltip>;

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 <Records /> are still tied after the earlier criteria.

For a full explanation of the ranking order, see [The eight ranking criteria](/doc/guides/managing-results/relevance-overview/in-depth/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 JSON icon=braces theme={"system"}
[
  {
    "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](/doc/guides/managing-results/must-do/custom-ranking/how-to/controlling-custom-ranking-metrics-precision).

## See also

* [Create custom ranking attributes](/doc/guides/managing-results/must-do/custom-ranking/how-to/configure-custom-ranking)
* [Precision of custom ranking metrics](/doc/guides/managing-results/must-do/custom-ranking/how-to/controlling-custom-ranking-metrics-precision)
* [Boost or penalize records](/doc/guides/managing-results/must-do/custom-ranking/how-to/boost-or-penalize-some-records)
* [12 ways to improve your search index (blog)](https://www.algolia.com/blog/engineering/12-ways-to-improve-your-search-index/)
* [Building a query suggestion UX like Google's (blog)](https://www.algolia.com/blog/algolia/query-suggestion-ux-like-googles/)