Boosting Or Penalizing Records

Dataset

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

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

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',
  'YourAdminAPIKey'
);

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

1
2
3
4
5
6
require 'rubygems'
require 'algoliasearch'

Algolia.init(application_id: 'YourApplicationID',
             api_key:        'YourAdminAPIKey')
index = Algolia::Index.new('your_index_name')

1
2
3
4
5
6
7
8
9
10
11
// const algoliasearch = require('algoliasearch');
// const algoliasearch = require('algoliasearch/reactnative');
// const algoliasearch = require('algoliasearch/lite');
// import algoliasearch from 'algoliasearch';
//
// or just use algoliasearch if you are using a <script> tag
// if you are using AMD module loader, algoliasearch will not be defined in window,
// but in the AMD modules of the page

const client = algoliasearch('YourApplicationID', 'YourAdminAPIKey');
const index = client.initIndex('your_index_name');

1
2
3
4
from algoliasearch.search_client import SearchClient

client = SearchClient.create('YourApplicationID', 'YourAdminAPIKey')
index = client.init_index('your_index_name')

1
2
let client = Client(appID: "YourApplicationID", apiKey: "YourAdminAPIKey")
let index = client.index(withName: "your_index_name")

1
2
Client client = new Client("YourApplicationID", "YourAdminAPIKey");
Index index = client.getIndex("your_index_name");

1
2
SearchClient client = new SearchClient("YourApplicationID", "YourAdminAPIKey");
SearchIndex index = client.InitIndex("your_index_name");

1
2
3
4
SearchClient client = 
DefaultSearchClient.create("YourApplicationID", "YourAdminAPIKey");

SearchIndex index = client.InitIndex("your_index_name");

1
2
3
4
5
6
7
8
package main

import "github.com/algolia/algoliasearch-client-go/algolia/search"

func main() {
  client := search.NewClient("YourApplicationID", "YourAdminAPIKey")
  index := client.InitIndex("your_index_name")
}

1
2
// No initIndex
val client = new AlgoliaClient("YourApplicationID", "YourAdminAPIKey")

1
2
3
4
5
6
7
val client = ClientSearch(
    applicationID = ApplicationID("latency"),
    apiKey = APIKey("YourAdminAPIKey")
)
val indexName = IndexName("your_index_name")

client.initIndex(indexName)

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.

Using the API

1
2
3
4
5
$customRanking = ['desc(boosted)']; // We add our `boosted` attribute

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

1
2
3
4
# We add our `boosted` attribute
custom_ranking = ['desc(boosted)']

index.set_settings(customRanking: custom_ranking)

1
2
3
4
5
6
7
index.setSettings({
  customRanking: ['desc(boosted)']
}, (err, content) => {
  if (err) throw err;

  console.log(content);
});

1
index.set_settings({'customRanking': ['desc(boosted)']})

1
2
3
let customRanking = ["desc(boosted)"]
let settings = ["customRanking": customRanking]
index.setSettings(settings)

1
2
3
index.setSettings(
    new JSONObject().put("customRanking", "desc(boosted)")
);

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

index.SetSettings(settings);

// Asynchronous
await index.SetSettingsAsync(settings);

1
2
3
4
5
index.setSettings(
      new IndexSettings().setCustomRanking(Collections.singletonList(
              "desc(boosted)"
      ))
);

1
2
3
res, err := index.SetSettings(search.Settings{
  CustomRanking: opt.CustomRanking("desc(boosted)"),
})

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

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

index.setSettings(settings)

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 specific a numeric attribute that maps to a boosted “level”.

In this case, our 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
  }
]

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.