API Reference / API Parameters / ranking

Jan. 14, 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
}

new JSONObject().put(
  "ranking",
  new JSONArray()
    // the `asc` and `desc` modifiers must be placed at the top
    // if you are configuring an index for sorting purposes only
    .put("asc(attribute1)")
    .put("desc(attribute2)")
    .put("typo")
    .put("geo")
    .put("words")
    .put("filters")
    .put("proximity")
    .put("attribute")
    .put("exact")
    .put("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 setSettingsAsync 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. Each criterion will be applied in sequence by the tie-breaking algorithm in the order they are specified.

Ranking Criteria:

typo: Sort by increasing number of typos.
geo: Sort by decreasing 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. In case of OR filters, only one score is taken in account 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 matched exactly.
custom:
- Sort according to a user-defined formula specified via the customRanking setting.
- Note: If custom is not mentioned then you customRanking will not be taken into account.

Modifiers:

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

Examples

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
index.setSettings(
  new JSONObject().put(
    "ranking",
    new JSONArray()
      .put("typo")
      .put("geo")
      .put("words")
      .put("filters")
      .put("proximity")
      .put("attribute")
      .put("exact")
      .put("custom")
  )
);

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 {
  changeSettings of "myIndex" `with` IndexSettings(
    ranking = Some(Seq(
      Ranking.typo,
      Ranking.geo,
      Ranking.words,
      Ranking.filters,
      Ranking.proximity,
      Ranking.attribute,
      Ranking.exact,
      Ranking.custom
    ))
  )
}

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)

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
index.setSettings(new JSONObject().put("ranking", new JSONArray()
  .put("asc(price)")
  .put("typo")
  .put("geo")
  .put("words")
  .put("filters")
  .put("proximity")
  .put("attribute")
  .put("exact")
  .put("custom"))
);

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 {
  changeSettings 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
    ))
  )
}

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)

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
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
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
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
index.setSettings(new JSONObject().put("ranking", new JSONArray()
  .put("desc(price)")
  .put("typo")
  .put("geo")
  .put("words")
  .put("filters")
  .put("proximity")
  .put("attribute")
  .put("exact")
  .put("custom"))
);

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 {
  changeSettings 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
    ))
  )
}

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)

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

PHP

Ruby

JavaScript

Python

Swift

Kotlin

Android

.NET

Java

Golang

Scala

InstantSearch.js

React InstantSearch

Vue InstantSearch

Angular InstantSearch

InstantSearch iOS

InstantSearch Android

Autocomplete

Crawler Configuration API

Index settings and search parameters

A full reference of API Endpoints

Rails

Symfony

Django

Laravel

Crawler

Magento 2

WordPress

Shopify

Salesforce Commerce Cloud B2C

Netlify

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)

Did you find this page helpful?

On this page