21 Nov 2018

Custom Ranking

Why Custom Ranking - A 6-Minute Video

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 and null or 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 precision 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.

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).

Boosting Records

In some cases, you may want to boost, or promote, featured items to the top of your search results.

One simple way to accomplish this is to create a boolean attribute that you add to your custom ranking. Let’s call the attribute ‘justReleased’. By placing the ‘justReleased’ 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. See our boosting tutorial.

A more generalized approach is to use the Query Rules Hit Promotion functionality, which involves setting up a rule that promotes records based on different search terms. See how to promote hits using Query Rules.

© Algolia - Privacy Policy