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' => [
  // Place the `asc` and `desc` modifiers at the top
  // if you're configuring an index just for sorting
  'asc(attribute1)',
  'desc(attribute2)',
  'typo',
  'geo',
  'words',
  'filters',
  'proximity',
  'attribute',
  'exact',
  'custom'
]

ranking: [
  # Place the `asc` and `desc` modifiers at the top
  # if you're configuring an index just for sorting
  'asc(attribute1)',
  'desc(attribute2)',
  'typo',
  'geo',
  'words',
  'filters',
  'proximity',
  'attribute',
  'exact',
  'custom'
]

ranking: [
  // Place the `asc` and `desc` modifiers at the top
  // if you're configuring an index just for sorting
  'asc(attribute1)',
  'desc(attribute2)',
  'typo',
  'geo',
  'words',
  'filters',
  'proximity',
  'attribute',
  'exact',
  'custom'
]

'ranking': [
  # Place the `asc` and `desc` modifiers at the top
  # if you're configuring an index just for sorting
  'asc(attribute1)',
  'desc(attribute2)',
  'typo',
  'geo',
  'words',
  'filters',
  'proximity',
  'attribute',
  'exact',
  'custom'
]

ranking = [
  // Place the `asc` and `desc` modifiers at the top
  // if you're configuring an index just for sorting
  .asc("attribute1"),
  .desc("attribute2"),
  .typo,
  .geo,
  .words,
  .filters,
  .proximity,
  .attribute,
  .exact,
  .custom
]

ranking {
  // Place the `asc` and `desc` modifiers at the top
  // if you're configuring an index just for sorting
  +Asc("attribute1")
  +Desc("attribute2")
  +Typo
  +Geo
  +Words
  +Filters
  +Proximity
  +Attribute
  +Exact
  +Custom
}

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

.setRanking(Arrays.asList(
  // Place the `asc` and `desc` modifiers at the top
  // if you're configuring an index just for sorting
  "asc(attribute1)",
  "desc(attribute2)",
  "typo",
  "geo",
  "words",
  "filters",
  "proximity",
  "attribute",
  "exact",
  "custom",
))

opt.Ranking(
  // Place the `asc` and `desc` modifiers at the top
  // if you're configuring an index just for sorting
  "asc(attribute1)",
  "desc(attribute2)",
  "typo",
  "geo",
  "words",
  "filters",
  "proximity",
  "attribute",
  "exact",
  "custom",
)

ranking = Some(Seq(
  // Place the `asc` and `desc` modifiers at the top
  // if you're configuring an index just for sorting
  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 sorts your results.

The tie-breaking algorithm sequentially applies ranking criteria in the order specified.

You can change the order of the default criteria but you shouldn’t. The out-of-the-box ranking order works for most uses.

However, if you do decide to change ranking, apply it with the setSettings method (attribute names are case-sensitive) or the Algolia dashboard.

How you declare your searchable attributes can also affect ranking. For more information, see searchableAttributes

Before changing ranking, consider running an A/B test to ensure your changes will positively affect results.

Ranking criteria

`typo`	Sort results by the fewest spelling mistakes.
`geo`	Sort results by increasing distance. This option only applies when carrying out a geographical search.
`words`	Sort results by the number of matching query words, starting with the most matches. This option only applies if you’re using `optionalWords`.
`filters`	Sort results by filter score. This option is essential if you want to use `optionalFilters`.
`proximity`	Sort results by how close the query words are to each other.
`attribute`	Sort results based on the order of attributes you set in `searchableAttributes`.
`exact`	For a single-word query, sorting depends on the `exactOnSingleWordQuery` parameter For multiple words, sort results by the number of query words that match exactly.
`custom`	Sort according to the `customRanking` parameter. If `custom` isn’t defined, `customRanking` is ignored.

Modifiers

`asc`	Sort in ascending order (lowest to highest).
`desc`	Sort in descending order (highest to lowest).

Examples

Set ranking

This example sets the ranking criteria for an index. It’s slightly different from Algolia’s default ranking since it swaps the order of attribute and proximity.

Copy

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
index.set_settings({
    'ranking': [
        'typo',
        'geo',
        'words',
        'filters',
        'attribute',
        'proximity',
        '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,
    .attribute,
    .proximity,
    .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
        +Attribute
        +Proximity
        +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",
    "attribute",
    "proximity",
    "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",
    "attribute",
    "proximity",
    "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",
    "attribute",
    "proximity",
    "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.attribute,
      Ranking.proximity,
      Ranking.exact,
      Ranking.custom
    ))
  )
}

Sort index by an attribute in ascending price order

This example modifies the default ranking criteria to first sort records from low to high price. To do this, it:

Makes the price custom ranking attribute the first criterion
Applies an asc sort on price

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 price order

Override the default ranking criteria to sort records from high to low price:

It’s similar to the previous example but uses a desc sort on price.

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 ranking

Sort index by an attribute in ascending price order

Sort index by an attribute in descending price order

On this page