Create Custom Ranking Attributes

Algolia offers good relevance out-of-the-box. Yet, what makes search great is fine-tuning it according to business relevance. For example, imagine you’re developing an app based on Twitter feeds. When searching, you want to rank results by relevance and the custom attributes likes and retweets.

You can do this by using Algolia’s custom ranking feature to specify what attributes to rank on. You can configure these attributes at indexing time with the customRanking parameter or through Algolia’s dashboard.

Dataset example

In this example, you’re developing an app based on Twitter feeds and want to rank tweets by the 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, and 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. You can set custom ranking criteria to be in ascending or descending order.

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

Custom ranking criteria are applied in order (in this example, first retweets and then likes).

Using the dashboard

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

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

Custom ranking on different attributes

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, say you want to add Facebook posts to your dataset, and they have attributes likes and comments. Because retweets are a custom ranking attribute, and Facebook posts don’t have a retweets attribute, they’re unlikely to win the tie-break against a tweet.

You could solve this by creating a computed attribute. For example, you could compute a single popularity attribute instead of having likes and retweets on one side and likes and comments on the other.

Computed attributes

You might want to create a custom ranking attribute based on the calculated value of other attributes. In other words, a computed attribute. For example:

• A Bayesian average of product ratings
• A simple, combined score of other attributes (such as popularity being the sum of likes and retweets).
• A boolean value set to true or false based on whether another attribute is null.

To implement a computed attribute, you must create it as an attribute in your records. To populate the record with values for the computed attribute:

1. Retrieve every record in the index, using the browse method.
2. For each record, calculate the computed attribute value.
3. Update each record’s computed attribute in the index with the calculated value, using the partialUpdateObjects method.

The regularity of these updates depends on your use case: it might be once a month, every week, daily, or even more frequently.

Metric types

The custom ranking field accepts any 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. Publish date (as a timestamp), page views, and likes are often used in media applications.

Check that the numeric attributes used in customRanking aren’t formatted as a string, as this would cause the records to be ranked alphabetically.

Using boolean values

When using a boolean value attribute within the custom ranking, the ascending and descending setting uses the alphabetical value of the true or false text.

For instance, if you need the true values ranked higher, set it to be descending. If you need the false values ranked higher, set it to be ascending.

String and null or absent values

If a custom ranking attribute is missing from a record or has a null value, that record is always ordered last, regardless of its ascending or descending setting. Records with null or missing values are considered equal.

Strings are sorted after numbers and before null or absent values. Strings are also compared by lexicographical order.