Boost or penalize records

How to boost or penalize a subset of records in the search results.

To boost or penalize records, you need to add a boost attribute that tells Algolia how to rank them.

Algolia doesn’t create this attribute for you: it only uses the value you send.

Boosted attributes can be boolean or numeric:

• Boolean values create simple boosts.
• Numeric values allow finer control over boosting.

The following examples use the featured attribute for boosting:

Boolean

JSON

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

Numeric

JSON

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

Avoid using quoted numbers, such as "32", which are treated as strings.

For finer control, use numeric values. In the example dataset:

• With the boolean featured value, a query for a returns “Apple” first.
• With the numeric featured value, a query for a returns “Apricot” first because it has the highest featured value.

Defining the attribute isn’t enough on its own: you must tell Algolia to use it in the ranking formula (in custom ranking).

Add the boost attribute to custom ranking

Custom ranking is the last criterion in Algolia’s ranking formula. Add boost attributes here to affect the order of records with the same textual relevance. It doesn’t override Algolia’s default ranking criteria.

To boost records, add the attribute you’re boosting to the custom ranking from the dashboard or the API.

If your boosted attribute is a boolean, ensure you set the order of the custom ranking attribute to descending.

With the dashboard

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

From the API

C#

var response = await client.SetSettingsAsync(
  "ALGOLIA_INDEX_NAME",
  new IndexSettings { CustomRanking = new List<string> { "desc(boosted)" } }
);

Use sorting to group items before ranking them

You can sort records by an attribute before applying the ranking formula.

For example, you might want results to appear in price-based groups (such as high-, medium-, and low-priced items).

To do this, assign numeric values (for example, 1, 2, and 3) to a defined grouping attribute. Algolia will sort group 1 first, then group 2, and so on.

Use a separate attribute for grouping. Don’t reuse your boost attribute. This method uses sorting, which applies before custom ranking and determines the overall group order.