Guides / Managing results / Must do / Custom ranking

Create Custom Ranking Attributes

Algolia offers relevance out of the box. Yet, what makes search great is fine tuning it according to business relevance. For example, imagine we’re developing an app based on Twitter feeds. When making searches, we want to rank results not only by relevance, but also based on custom attributes: likes and retweets.

You can do this by using Algolia’s custom ranking feature by specifying what attributes to rank on.

The attributes used for custom ranking can be configured at indexing time with the customRanking parameter, or through Algolia’s dashboard.

Dataset Example

Let’s go back to our example. We’re developing an app based on Twitter feeds and we want to rank tweets by number of likes and retweets. Here’s what the dataset would look like:

    "tweet": "🎈 We’re introducing Create InstantSearch App today: a CLI to bootstrap InstantSearch apps from the terminal. Read more in this blog post by @FrancoisChlfr!",
    "retweets": 13,
    "likes": 27
    "tweet": "Designers from all horizons, don’t forget to register for next #ParisDesignMeetup, taking place on Sept 25th!",
    "retweets": 9,
    "likes": 13
    "tweet": "Are you ready for GSA to be a thing of the past? Register now for our webinar where we’ll help you with migration options, tips & tricks to make your move as painless as possible.",
    "retweets": 4,
    "likes": 6

Using the API

To rank on retweets and likes, you first need to set customRanking during indexing time. Custom ranking criteria can be set for ascending or descending ranking.

  'customRanking' => [

Note that custom ranking criteria apply in order (here, first retweets then likes).

Using the Dashboard

You can also set your custom ranking in your Algolia dashboard.

  • Select the Search product icon on your dashboard.
  • In the Index page, select your index.
  • Click the Ranking tab.
  • In the Ranking Formula & Custom Ranking section, go and select attributes “retweets” then “likes” in the Add a Custom Ranking Attribute dropdown.
  • Don’t forget to save your changes.

Custom ranking on different attributes

It’s important to note that custom ranking applies at the index level. This means records that don’t have an attribute that’s in the customRanking list are pushed to the bottom. For example, let’s say we want to add Facebook posts to our dataset, and they have attributes likes and comments. Because we have set retweets as a custom ranking attribute, and Facebook posts don’t have a retweets attribute, they will likely never win the tie-break against a tweet.

You could solve this by mixing the attributes together. Instead of having likes and retweets on one side, and likes and comments on the other, you would compute them as a single popularity attribute and use it as the custom ranking attribute.

Metric Types

The custom ranking field accepts 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.

What you set as your customRanking depends on your use case and what data you have available. Some retail metrics commonly used in customRanking include sales rank, stock levels, free shipping (boolean), on sale (boolean), and rating. In media, publish date (as a timestamp), page views, and likes are frequently used.

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 is always 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.

Did you find this page helpful?