Create Custom Ranking Attributes

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[
  {
    "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. https://go.algolia.com/gsa-migration",
    "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.

1
2
3
4
5
6
$index->setSettings([
  'customRanking' => [
    'desc(retweets)',
    'desc(likes)'
  ]
]);

1
2
3
4
5
6
index.set_settings({
  customRanking: [
    'desc(retweets)',
    'desc(likes)'
  ]
})

1
2
3
4
5
6
7
8
index.setSettings({
  customRanking: [
    'desc(retweets)',
    'desc(likes)'
  ]
}).then(() => {
  // done
});

1
2
3
4
5
6
index.set_settings({
    'customRanking': [
        'desc(retweets)',
        'desc(likes)'
    ]
})

1
2
3
4
5
6
index.setSettings([
  "customRanking": [
    "desc(retweets)",
    "desc(likes)"
  ]
])

1
2
3
4
5
6
7
8
index.setSettings(
  new JSONObject().put(
    "customRanking",
    new JSONArray()
      .put("desc(retweets)")
      .put("desc(likes)")
  )
);

1
2
3
4
5
6
7
8
9
10
11
12
13
IndexSettings settings = new IndexSettings
{
    CustomRanking = new List<string>
    {
      "desc(retweets)",
      "desc(likes)",
    }
};

index.SetSettings(settings);

// Asynchronous
await index.SetSettingsAsync(settings);

1
2
3
4
5
6
index.setSettings(
  new IndexSettings().setCustomRanking(Arrays.asList(
    "desc(retweets)",
    "desc(likes)"
  ))
);

1
2
3
4
5
6
res, err := index.SetSettings(search.Settings{
  CustomRanking: opt.CustomRanking(
    "desc(retweets)",
    "desc(likes)",
  ),
})

1
2
3
4
5
6
7
8
client.execute {
  changeSettings of "myIndex" `with` IndexSettings(
    customRanking = Some(Seq(
      CustomRanking.desc("retweets"),
      CustomRanking.desc("likes")
    ))
  )
}

1
2
3
4
5
6
7
8
val settings = settings {
    customRanking {
        +Desc("retweets")
        +Desc("likes")
    }
}

index.setSettings(settings)

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.

• Go to your dashboard and 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.