🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
Guides / Managing results / Must do / Custom ranking

Boosting or penalizing records

To boost a subset of results, you need an attribute in the record specifying if the record should to be boosted or not: the boosted attribute in the following dataset.

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
  }
]

For more information, see Importing from the dashboard

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

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 lets you define a list of attributes used to rank the results in the case of textual relevance equality.

To boost featured fruits, you need to add the boosted attribute to the custom ranking from the dashboard or the API.

Using the dashboard

On the ranking and sorting tab, add a new custom ranking attribute.

Custom ranking attribute

Using the API

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, the dataset might look like this:

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
  }
]

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

In this example, the 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 preceding the ranking formula. This has the effect of sorting in the classic sense: the attribute sorts the results first before applying any ranking formula.

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 group 1 first, then group 2, then group 3. 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?