Guides / Managing results / Must do / Custom ranking

Boosting or Penalizing Records

On this page

In order to boost a subset of results, we will need an attribute in the record specifying if the record should to be boosted or not.

Dataset

Here’s a sample dataset to help illustrate this concept:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

[
  {
    "name": "Apricot",
    "boosted": false
  },
  {
    "name": "Apple",
    "boosted": false
  },
  {
    "name": "Almonds",
    "boosted": true
  }
]

As you can see we defined a boosted attribute to tell whether the record should or should not be boosted.

The full dataset can be downloaded here. For more information on indexing data, see our importing tutorial

Data types of the boosted attribute

Attributes for boosting need to be either a boolean or numeric value.

Ensure that the numeric value is not inside a string (Example: "32").

Initialize client

Copy 
1
2
3
4
5
6
7
8
9
10
11
12

// composer autoload
require __DIR__ . '/vendor/autoload.php';

// if you are not using composer
// require_once 'path/to/algoliasearch.php';

$client = \Algolia\AlgoliaSearch\SearchClient::create(
  'YourApplicationID',
  'YourWriteAPIKey'
);

$index = $client->initIndex('your_index_name');

Update the custom ranking

The last criterion of Algolia’s ranking formula is customRanking. It allows you to define a list of attributes used to rank the results in the case of textual relevance equality.

In our case we want to boost featured fruits. To accomplish this, we will need to add the boosted attribute to the custom ranking. There are two methods to do this:

Using the dashboard

On the ranking tab of the explorer we can add a new custom ranking attribute.

Custom ranking attribute

Using the API

Copy 
1
2
3
4
5

$customRanking = ['desc(boosted)']; // We add our `boosted` attribute

$index->setSettings([
  'customRanking' => $customRanking
]);

When your boosted attribute is a boolean data type, ensure you have set the order of the custom ranking attribute to descending.

More granular boosts

Now that the customRanking is set, querying a will return “almonds” first, as it matches both textually AND is a featured record.

If more granularity is necessary, a similar method can be used. Instead of a boolean attribute, you will need to specify a numeric attribute that maps to a boosted “level”.

In this case, our dataset might look like this:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

[
  {
    "name": "Apricot",
    "boosted": 0
  },
  {
    "name": "Apple",
    "boosted": 4
  },
  {
    "name": "Almonds",
    "boosted": 1
  }
]

We don’t have to update the customRanking as it’s already set to rank by the boosted attribute in descending order.

In this example, if we query a it will return “apple” first because it has the highest boosted value.

Boosting or Bucketing Groups of Items with Sorting

You can also shift the order of the logic and put an attribute above the ranking formula. This has the effect of sorting in the classic sense: The attribute sorts the results first before applying any ranking formula. We discuss sorting elsewhere, but it’s worth looking at how sorting can be used to boost items.

Sometimes you may want your results to appear in groups, or buckets - say 3 buckets of prices: high-priced, medium-priced, low-priced. To do this, you’ll need to first sort the results into 3 groups, and then apply the ranking strategy for each group individually. You can use an attribute with numbers 1, 2, and 3, which will be used for the 3 groups, and then Algolia will tie-break all 1s first, then 2s, then 3s. To do this, you’ll use the Sort-By feature (not custom ranking), which occurs before, not after, the tie-breaking.

Did you find this page helpful?