API Reference / API Parameters / customRanking
Type: list of strings
Engine default: [] (no custom ranking)
Parameter syntax
'customRanking' => [

Can be used in these methods:

About this parameter

Specifies which attributes to assign 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:

  • Define a ranking of results using metrics that are important to you, 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 being equal. This means that 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.



Sort by increasing value of the attribute.


Sort by decreasing value of the attribute.


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.

  'customRanking' => [
Did you find this page helpful?