API Reference / API Parameters / ranking

Nov. 25, 2021

ranking

Type: list of strings

Engine default: ["typo", "geo", "words", "filters", "proximity", "attribute", "exact", "custom"]

Parameter syntax

'ranking' => [
  // the `asc` and `desc` modifiers must be placed at the top
  // if you are configuring an index for sorting purposes only
  'asc(attribute1)',
  'desc(attribute2)',
  'typo',
  'geo',
  'words',
  'filters',
  'proximity',
  'attribute',
  'exact',
  'custom'
]

ranking: [
  # the `asc` and `desc` modifiers must be placed at the top
  # if you are configuring an index for sorting purposes only
  'asc(attribute1)',
  'desc(attribute2)',
  'typo',
  'geo',
  'words',
  'filters',
  'proximity',
  'attribute',
  'exact',
  'custom'
]

ranking: [
  // the `asc` and `desc` modifiers must be placed at the top
  // if you are configuring an index for sorting purposes only
  'asc(attribute1)',
  'desc(attribute2)',
  'typo',
  'geo',
  'words',
  'filters',
  'proximity',
  'attribute',
  'exact',
  'custom'
]

'ranking': [
  # the `asc` and `desc` modifiers must be placed at the top
  # if you are configuring an index for sorting purposes only
  'asc(attribute1)',
  'desc(attribute2)',
  'typo',
  'geo',
  'words',
  'filters',
  'proximity',
  'attribute',
  'exact',
  'custom'
]

ranking = [
  // the `asc` and `desc` modifiers must be placed at the top
  // if you are configuring an index for sorting purposes only
  .asc("attribute1"),
  .desc("attribute2"),
  .typo,
  .geo,
  .words,
  .filters,
  .proximity,
  .attribute,
  .exact,
  .custom
]

ranking {
    // the `asc` and `desc` modifiers must be placed at the top
    // if you are configuring an index for sorting purposes only
    +Asc("attribute1")
    +Desc("attribute2")
    +Typo
    +Geo
    +Words
    +Filters
    +Proximity
    +Attribute
    +Exact
    +Custom
}

IndexSettings settings = new IndexSettings();
settings.Ranking = new List<string>
{
  // the `asc` and `desc` modifiers must be placed at the top
  // if you are configuring an index for sorting purposes only
  "asc(attribute1)",
  "desc(attribute2)",
  "typo",
  "geo",
  "words",
  "filters",
  "proximity",
  "attribute",
  "exact",
  "custom",
};

.setRanking(Arrays.asList(
  // the `asc` and `desc` modifiers must be placed at the top
  // if you are configuring an index for sorting purposes only
  "asc(attribute1)",
  "desc(attribute2)",
  "typo",
  "geo",
  "words",
  "filters",
  "proximity",
  "attribute",
  "exact",
  "custom",
))

opt.Ranking(
  // the `asc` and `desc` modifiers must be placed at the top
  // if you are configuring an index for sorting purposes only
  "asc(attribute1)",
  "desc(attribute2)",
  "typo",
  "geo",
  "words",
  "filters",
  "proximity",
  "attribute",
  "exact",
  "custom",
)

ranking = Some(Seq(
  // the `asc` and `desc` modifiers must be placed at the top
  // if you are configuring an index for sorting purposes only
  Ranking.asc("price"),
  Ranking.desc("price"),
  Ranking.typo,
  Ranking.geo,
  Ranking.words,
  Ranking.filters,
  Ranking.proximity,
  Ranking.attribute,
  Ranking.exact,
  Ranking.custom
))

Can be used in these methods:
setSettings set_settings setSettings set_settings setSettings setSettings SetSettings setSettings SetSettings setSettings

See code examples

About this parameter

Controls how Algolia should sort your results.

You must specify a list of ranking criteria for sorting. The tie-breaking algorithm applies each criterion sequentially in the order they’re specified.

Before changing any aspect of these relevance settings, test them in the dashboard. You should also consider planning and implementing A/B testing to ensure that any changes positively affect your results.

Ranking criteria

`typo`	Sort by increasing number of typos.
`geo`	Sort by increasing geo distance when performing a geo search. This criterion is ignored when not performing a geo search.
`words`	Sort by decreasing number of matched query words. This parameter is useful when you use the `optionalWords` query parameter to rank hits with the most matched words first.
`filters`	The filter criteria is the sum of scores for filters matched by one hit. Only one score is considered for OR filters, even if the two filters match. This parameter must be present in the ranking if you want to use `optionalFilters`.
`proximity`	Sort by increasing proximity of query words in hits.
`attribute`	Sort according to the order of attributes defined by `searchableAttributes`.
`exact`	If the query contains only one word: The behavior depends on the value of `exactOnSingleWordQuery`. If the query contains multiple words: Sort by decreasing number of words that exactly match.
`custom`	Sort according to a user-defined formula specified via the `customRanking` setting. If `custom` isn’t mentioned, your `customRanking` won’t be considered.

Modifiers

`asc`	Sort by increasing value of the attribute.
`desc`	Sort by decreasing value of the attribute.

Examples

You can either set ranking from the API with the setSettings method or from the dashboard.

The second and third examples show how to use the API to override Algolia’s default ranking criteria. You can do the same on the dashboard by visiting your index’s Configuration tab, clicking Ranking and Sorting, selecting Expand for the textual ranking criteria, and then dragging the custom ranking to the appropriate location. In the example, that means dragging price to the top.

You shouldn’t need to change the default criteria since the out-of-the-box ranking works for most use cases.

Set the default ranking

Copy

1
2
3
4
5
6
7
8
9
10
11
12
$index->setSettings([
  'ranking' => [
    'typo',
    'geo',
    'words',
    'filters',
    'proximity',
    'attribute',
    'exact',
    'custom'
  ]
]);

1
2
3
4
5
6
7
8
9
10
11
12
index.set_settings({
  ranking: [
    'typo',
    'geo',
    'words',
    'filters',
    'proximity',
    'attribute',
    'exact',
    'custom'
  ]
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
index.setSettings({
  ranking: [
    'typo',
    'geo',
    'words',
    'filters',
    'proximity',
    'attribute',
    'exact',
    'custom'
  ]
}).then(() => {
  // done
});

1
2
3
4
5
6
7
8
9
10
11
12
index.set_settings({
    'ranking': [
        'typo',
        'geo',
        'words',
        'filters',
        'proximity',
        'attribute',
        'exact',
        'custom'
    ]
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
let settings = Settings()
  .set(\.ranking, to: [
    .typo,
    .geo,
    .words,
    .filters,
    .proximity,
    .attribute,
    .exact,
    .custom
  ])

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
val settings = settings {
    ranking {
        +Typo
        +Geo
        +Words
        +Filters
        +Proximity
        +Attribute
        +Exact
        +Custom
    }
}

index.setSettings(settings)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
IndexSettings settings = new IndexSettings();
settings.Ranking = new List<string>
{
    "typo",
    "geo",
    "words",
    "filters",
    "proximity",
    "attribute",
    "exact",
    "custom"
};

index.SetSettings(settings);

1
2
3
4
5
6
7
8
9
10
11
12
index.setSettings(
  new IndexSettings().setRanking(Arrays.asList(
    "typo",
    "geo",
    "words",
    "filters",
    "proximity",
    "attribute",
    "exact",
    "custom"
  ))
);

1
2
3
4
5
6
7
8
9
10
11
12
res, err := index.SetSettings(search.Settings{
  Ranking: opt.Ranking(
    "typo",
    "geo",
    "words",
    "filters",
    "proximity",
    "attribute",
    "exact",
    "custom",
  ),
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
client.execute {
  setSettings of "myIndex" `with` IndexSettings(
    ranking = Some(Seq(
      Ranking.typo,
      Ranking.geo,
      Ranking.words,
      Ranking.filters,
      Ranking.proximity,
      Ranking.attribute,
      Ranking.exact,
      Ranking.custom
    ))
  )
}

Sort index by an attribute in ascending order (Sort by price in this example)

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
$index->setSettings([
  'ranking' => [
    'asc(price)',
    'typo',
    'geo',
    'words',
    'filters',
    'proximity',
    'attribute',
    'exact',
    'custom'
  ]
]);

1
2
3
4
5
6
7
8
9
10
11
12
13
index.set_settings({
  ranking: [
    'asc(price)',
    'typo',
    'geo',
    'words',
    'filters',
    'proximity',
    'attribute',
    'exact',
    'custom'
  ]
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
index.setSettings({
  ranking: [
    "asc(price)",
    "typo",
    "geo",
    "words",
    "filters",
    "proximity",
    "attribute",
    "exact",
    "custom"
  ]
}).then(() => {
  // done
});

1
2
3
4
5
6
7
8
9
10
11
12
13
index.set_settings({
    'ranking': [
        'asc(price)',
        'typo',
        'geo',
        'words',
        'filters',
        'proximity',
        'attribute',
        'exact',
        'custom'
    ]
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
let settings = Settings()
  .set(\.ranking, to: [
    .asc("price"),
    .typo,
    .geo,
    .words,
    .filters,
    .proximity,
    .attribute,
    .exact,
    .custom
  ])

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
val settings = settings {
    ranking {
        +Asc("price")
        +Typo
        +Geo
        +Words
        +Filters
        +Proximity
        +Attribute
        +Exact
        +Custom
    }
}

index.setSettings(settings)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
IndexSettings settings = new IndexSettings
settings.Ranking = new List<string>
{
    "asc(price)",
    "typo",
    "geo",
    "words",
    "filters",
    "proximity",
    "attribute",
    "exact",
    "custom"
};

index.SetSettings(settings);

1
2
3
4
5
6
7
8
9
10
11
12
13
index.setSettings(
  new IndexSettings().setRanking(Arrays.asList(
    "asc(price)",
    "typo",
    "geo",
    "words",
    "filters",
    "proximity",
    "attribute",
    "exact",
    "custom"
  ))
);

1
2
3
4
5
6
7
8
9
10
11
12
13
res, err := index.SetSettings(search.Settings{
  Ranking: opt.Ranking(
    "asc(price)",
    "typo",
    "geo",
    "words",
    "filters",
    "proximity",
    "attribute",
    "exact",
    "custom",
  ),
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
client.execute {
  setSettings of "myIndex" `with` IndexSettings(
    ranking = Some(Seq(
      Ranking.asc("price"),
      Ranking.typo,
      Ranking.geo,
      Ranking.words,
      Ranking.filters,
      Ranking.proximity,
      Ranking.attribute,
      Ranking.exact,
      Ranking.custom
    ))
  )
}

Sort index by an attribute in descending order (Sort by price in this example)

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
$index->setSettings([
  'ranking' => [
    "desc(price)",
    "typo",
    "geo",
    "words",
    "filters",
    "proximity",
    "attribute",
    "exact",
    "custom"
  ]
});

1
2
3
4
5
6
7
8
9
10
11
12
13
index.set_settings({
  ranking: [
    'desc(price)',
    'typo',
    'geo',
    'words',
    'filters',
    'proximity',
    'attribute',
    'exact',
    'custom'
  ]
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
index.setSettings({
  ranking: [
    "desc(price)",
    "typo",
    "geo",
    "words",
    "filters",
    "proximity",
    "attribute",
    "exact",
    "custom"
  ]
}).then(() => {
  // done
});

1
2
3
4
5
6
7
8
9
10
11
12
13
index.set_settings({
    'ranking': [
        'desc(price)',
        'typo'
        'geo',
        'words',
        'filters',
        'proximity',
        'attribute',
        'exact',
        'custom'
    ]
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
let settings = Settings()
  .set(\.ranking, to: [
    .desc("price"),
    .typo,
    .geo,
    .words,
    .filters,
    .proximity,
    .attribute,
    .exact,
    .custom
  ])

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
val settings = settings {
    ranking {
        +Desc("price")
        +Typo
        +Geo
        +Words
        +Filters
        +Proximity
        +Attribute
        +Exact
        +Custom
    }
}

index.setSettings(settings)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
IndexSettings settings = new IndexSettings();
settings.Ranking = new List<string>
{
  "desc(price)",
  "typo",
  "geo",
  "words",
  "filters",
  "proximity",
  "attribute",
  "exact",
  "custom"
};

index.SetSettings(settings);

1
2
3
4
5
6
7
8
9
10
11
12
13
index.setSettings(
  new IndexSettings().setRanking(Arrays.asList(
    "desc(price)",
    "typo",
    "geo",
    "words",
    "filters",
    "proximity",
    "attribute",
    "exact",
    "custom"
  ))
);

1
2
3
4
5
6
7
8
9
10
11
12
13
res, err := index.SetSettings(search.Settings{
  Ranking: opt.Ranking(
    "desc(price)",
    "typo",
    "geo",
    "words",
    "filters",
    "proximity",
    "attribute",
    "exact",
    "custom",
  ),
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
client.execute {
  setSettings of "myIndex" `with` IndexSettings(
    ranking = Some(Seq(
      Ranking.desc("price"),
      Ranking.typo,
      Ranking.geo,
      Ranking.words,
      Ranking.filters,
      Ranking.proximity,
      Ranking.attribute,
      Ranking.exact,
      Ranking.custom
    ))
  )
}

Did you find this page helpful?

ranking

About this parameter

Ranking criteria

Modifiers

Examples

Set the default ranking

Sort index by an attribute in ascending order (Sort by price in this example)

Sort index by an attribute in descending order (Sort by price in this example)

On this page