customRanking

About this parameter

Specifies which attributes should be assigned to Algolia’s custom ranking criterion.

Specify your custom ranking attributes as a list of strings. Use the syntax asc(<ATTRIBUTE>) or desc(<ATTRIBUTE>) to determine the ascending or descending sort order. The tie-breaking algorithm applies all custom ranking attributes in the specified sequence. Attribute names are case-sensitive.

Use custom ranking to:

• Rank results based on your key metrics such as popularity and date.
• Only show the most relevant results rather than all results: this is called relevant sorting.

Before adding a custom ranking, test the impact in the dashboard. You should also consider planning and implementing A/B testing to ensure it will improve your results.

Usage notes

Non-existing attributes or null values

Algolia’s sorting treats all records with missing or null values as equal. When sorting records on a custom ranking attribute, any record without this attribute, or where the attribute is null, will be placed at the end of the list. This happens regardless of whether the sorting is in ascending or descending order.

Boolean attributes

Boolean attributes are sorted based on their alphabetical order:

• In ascending order, false comes before true
• In descending order, true comes before false.

Indexing time versus query time sorting

Custom ranking is an index setting that can’t be changed at query time. To let users choose alternative ranking strategies, for example, sorted by a price from high to low or low to high, set up replica indices with different ranking strategies. Let users select between these ranking strategies in your user interface, for example, with a sortBy widget.

Modifiers

Examples

Set a custom ranking

This example uses the setSettings method to apply a custom ranking. It sorts by the decreasing value of the popularity attribute, then if popularity is equal, by the increasing value of the price attribute.

1
2
3
4
5
6
$index->setSettings([
  'customRanking' => [
    'desc(popularity)',
    'asc(price)'
  ]
]);

1
2
3
4
5
6
index.set_settings({
  customRanking: [
    'desc(popularity)',
    'asc(price)'
  ]
})

1
2
3
4
5
6
7
8
index.setSettings({
  customRanking: [
    'desc(popularity)',
    'asc(price)'
  ]
}).then(() => {
  // done
});

1
2
3
4
5
6
index.set_settings({
    'customRanking': [
        'desc(popularity)',
        'asc(price)'
    ]
})

1
2
3
4
5
6
7
8
9
10
11
let settings = Settings()
  .set(\.customRanking, to: [
    .desc("popularity"),
    .asc("price")
  ])

index.setSettings(settings) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
val settings = settings {
    customRanking {
        +Desc("popularity")
        +Asc("price")
    }
}

index.setSettings(settings)

1
2
3
4
5
6
7
8
9
IndexSettings settings = new IndexSettings();

settings.CustomRanking = new List<string>
{
    "desc(popularity)",
    "asc(price)"
};

index.SetSettings(settings);

1
2
3
4
5
6
index.setSettings(
  new IndexSettings().setCustomRanking(Arrays.asList(
    "desc(popularity)",
    "asc(price)"
  ))
);

1
2
3
4
5
6
res, err := index.SetSettings(search.Settings{
  CustomRanking: opt.CustomRanking(
    "desc(popularity)",
    "asc(price)",
  ),
})

1
2
3
4
5
6
7
8
client.execute {
  setSettings of "myIndex" `with` IndexSettings(
    customRanking = Some(Seq(
      CustomRanking.desc("popularity"),
      CustomRanking.asc("price")
    ))
  )
}