Icon ranking white

Custom Ranking

Last updated 07 February 2018

Custom Ranking Overview

Textual relevance is only part of what makes a compelling search experience. While Algolia’s default ranking formula works well to handle textual relevance of structured data, sorting on textual properties alone undermines the value of thoughtfully ordering results based on custom metrics within each record. Custom ranking - leveraging business metrics to effectively rank search results - is crucial for any successful search configuration.

To return great results, custom ranking attributes are applied after records sorted by textual relevance. Said another way, if two matched records have the same match textually, we resort to custom ranking to tie-break.

How to Add Custom Ranking Attributes

To communicate your business metrics to the engine, you can set them in the setting called customRanking, or at the bottom of the Ranking Formula in the Ranking tab of the dashboard. Here’s a quick example:

  customRanking: [

Metric Types

The custom ranking field will accept any type of numerical or boolean value that represents the relative relevance of your records.

The attribute type can be a raw value like the number of sales, views or likes. The field can also be a computed value such as a popularity score that you calculated before adding the record to Algolia.

Check that the numeric attributes used in CustomRanking are not formatted as a string, as this would cause the objects to be ranked alphabetically.

String, null and absent values

When an attribute from the custom ranking is missing from an object, or has a null value, that object will always be ordered last, no matter whether the attribute is defined as ascending or descending in the ranking. All objects with null or missing values are considered equal.

Strings are sorted after the numbers and before the null or absent values. Furthermore, strings are compared by lexicographical order.

Custom ranking metrics precision

Tie-breaking only works if there are records that are tied to begin with. If a particular custom ranking metric is too precise, then the next custom metric will essentially be ignored. For this reason, we stress the importance of ‘reducing precision’ to allow tie-breaking to be effectively leveraged.

Imagine a custom ranking configuration that sets both ‘rating’ and ‘count’ as custom ranking attributes:

  customRanking: [

If the rating for a record is too precise - say ‘“rating”: 4.321321’ - then the count will likely not be used to tie-break.

To fix the situation, we recommend creating another attribute, say ‘truncated_rating’, where we will only take values to the nearest tenth. In this example, 4.321321 becomes 4.3. By reducing the precison of the ‘rating’ attribute, we allow a higher probability that there will be several records that also have a ‘truncated_rating’ of 4.3; thus, we allow the possibility for tie-breaking on the ‘count’ attribute. Other means of reducing precision involve taking the floor of the logarithm of a given attribute value. If we were to do this instead, buckets can scale by orders of magnitude rather than linearly.

Boosting Records

In some cases, you may want to boost featured items to the top of your search results. This is accomplished by creating a boolean attribute that you would add to your custom ranking. Let’s call the attribute ‘isFeatured’. By placing the ‘isFeatured’ attribute in your custom ranking configuration, records with a value of true for this attribute will be placed above those with a value of false.

An Example

Let’s take a look at a simple use case:

    "name": "iPhone 5",
    "popularity": 20
    "name": "iPhone 6",
    "popularity": 10
    "name": "iPhone 7",
    "popularity": 200

Let’s add the popularity attribute in our Custom Ranking and set it to “descending”. With this configuration, if an end user were to type the query “iPhone”, he/she would get the following results: Iphone 7 will be first, followed by iPhone 5 and iPhone 6.

You can decide whether you want the sort to be descending (bigger values appear first in the results) or ascending (smaller values appear first in the results).

What’s Next

Continue building your Algolia knowledge with these concepts:

© Algolia - Privacy Policy