Docs Menu
Docs Home
/ / /
Rust Driver
/

Collations

On this page

  • Overview
  • MongoDB Collations
  • Specify a Collation
  • Example
  • Set a Collation on a Collection
  • Create Collection with a Collation Example
  • Collation Ordering Demonstration
  • Set a Collation on an Index
  • Example
  • Set a Collation on an Operation
  • Example
  • Additional Information
  • API Documentation

In this guide, you can learn how to use collations to order your find or aggregation operation results by string values. A collation is a set of character ordering conventions that correspond to a specific language and locale.

This guide includes the following sections:

  • MongoDB Collations describes how MongoDB sorts string values according to the default collation and custom collations

  • Specify a Collation describes how to create a Collation struct instance

  • Set a Collation on a Collection describes how to set the collation for a new collection

  • Set a Collation on an Index describes how to set the collation for an index

  • Set a Collation on an Operation describes how to apply a collation to certain CRUD operations

  • Additional Information provides links to resources and API documentation for types and methods mentioned in this guide

MongoDB sorts strings using binary collation by default. This collation method uses the ASCII standard character values to compare and order strings. Certain languages and locales have specific character ordering conventions that differ from the ASCII standard.

Tip

To learn more about the ASCII standard, see the ASCII Wikipedia page.

For example, in Canadian French, the right-most accented character determines the ordering for strings when the other characters are the same. Consider the following Canadian French words:

  • cote

  • coté

  • côte

  • côté

When using the default binary collation, MongoDB sorts the words in the following order:

cote
coté
côte
côté

In this sort order, "coté" is placed before "côte" because the ASCII standard positions the character "o" before the character "ô".

When using the Canadian French collation, MongoDB sorts the words in the following order:

cote
côte
coté
côté

In this sort order, "coté" is placed after "côte" because Canadian French collation rules position the character "e" before the character "é".

You can define a collation by specifying a collation locale and other options in a Collation struct instance. To begin building a Collation instance, call the Collation::builder() method.

Note

Instantiating Options

The Rust driver implements the Builder design pattern for the creation of many different types, including Collation. You can use the builder() method to construct an instance of each type by chaining option builder methods.

The following table describes the builder methods that you can use to set fields of a Collation instance. You must use the locale() method to build a valid Collation struct, but all other builder methods are optional:

Method
Possible Values
Description
locale() (Required)
For a full list of supported locales, see
in the Server manual.
Specifies the ICU locale
strength()
CollationStrength::Primary, CollationStrength::Secondary, CollationStrength::Tertiary, CollationStrength::Quaternary, CollationStrength::Identical
Specifies the level of comparison to perform
case_level()
true, false
Specifies whether the driver performs case comparison
case_first()
CollationCaseFirst::Upper, CollationCaseFirst::Lower, CollationCaseFirst::Off
Specifies the sort order of case differences during tertiary level comparisons
numeric_ordering()
true, false
Specifies whether the driver compares numeric strings as numbers
alternate()
CollationAlternate::NonIgnorable, CollationAlternate::Shifted
Specifies whether the driver considers whitespace and punctuation as base characters during string comparison
max_variable()
CollationMaxVariable::Punct,
CollationMaxVariable::Space
Specifies which characters the driver ignores when alternate is set to
CollationAlternate::Shifted
normalization()
true, false
Specifies whether the driver performs text normalization for string values
backwards()
true, false
Specifies whether the driver sorts strings containing diacritics in reverse character order

The following example specifies a Collation instance and sets the collation locale to "en_US":

let collation = Collation::builder()
.locale("en_US")
.build();

When you create a new collection, you can define the collation for future operations called on that collection. Set the collation by using the collation() function when creating a CreateCollectionOptions instance. Then, call the create_collection() method with your options instance as a parameter.

This example specifies a collation according to the "fr", or French, locale conventions and applies the collation to a new collection called books. The strength field is set to CollationStrength::Primary to ignore differences in diacritics.

let collation = Collation::builder()
.locale("fr")
.strength(CollationStrength::Primary)
.build();
let opts = CreateCollectionOptions::builder()
.collation(collation)
.build();
let result = my_db.create_collection("books", opts).await?;

If you run an operation that supports collations on the books collection, the operation uses the collation specified in the preceding Create Collection with a Collation Example.

Assume the books collection contains the following documents:

{ "name" : "Emma", "length" : "474" }
{ "name" : "Les Misérables", "length": "1462" }
{ "name" : "Infinite Jest", "length" : "1104" }
{ "name" : "Cryptonomicon", "length" : "918" }
{ "name" : "Ça", "length" : "1138" }

Tip

To learn how to insert documents into a collection, see the Insert Documents guide.

The following example uses the find() method to return all documents in which the value of the name field alphabetically precedes "Infinite Jest":

let query = doc! { "name": doc! { "$lt": "Infinite Jest" } };
let mut cursor = my_coll.find(query, None).await?;
while let Some(doc) = cursor.try_next().await? {
println!("{}", doc);
}

If you don't specify a collation for the books collection, the find() method follows default binary collation rules to determine the name values that precede "Infinite Jest". These rules place words beginning with "Ç" after those beginning with "I". So, when the preceding find operation follows binary collation rules, the document in which the name value is "Ça" does not match the filter criteria.

When you create a new index on a collection, you can define the collation for operations that are covered by the index. To run an operation that uses the index and its collation, your operation and index must specify the same collation.

Tip

To learn more about indexes and covered queries, see the Indexes guide.

Set the index collation by using the collation() function to build an IndexOptions instance. Then, pass your IndexOptions as an argument to an IndexModel builder function, and pass your IndexModel as an argument to the create_index() method.

The following example uses the create_index() method to create an ascending index on the name field and specifies a new collation corresponding to the "en_US" locale:

let collation = Collation::builder()
.locale("en_US")
.build();
let index_opts = IndexOptions::builder()
.collation(collation)
.build();
let index = IndexModel::builder()
.keys(doc! { "name": 1 })
.options(index_opts)
.build();
let result = my_coll.create_index(index, None).await?;
println!("Created index: {}", result.index_name);

Operations that read, update, and delete documents from a collection can use collations. Applying a collation to an operation overrides any collation previously defined for a collection or index.

If you apply a collation to an operation that differs from an index's collation, you cannot use that index. As a result, the operation might not perform as efficiently as one that is covered by an index. For more information on the disadvantages of sorting operations not covered by an index, see Using Indexes to Sort Query Results in the Server manual.

This example performs the following actions:

  • Sets the numeric_ordering collation option to true, which ensures that values are sorted in numerical order rather than alphabetical order

  • Specifies a collation in a FindOptions instance, which overrides the collection's collation

  • Uses the find() method to return documents in which the value of the length field is greater than "1000"

let collation = Collation::builder()
.locale("en_US")
.numeric_ordering(true)
.build();
let opts = FindOptions::builder()
.collation(collation)
.build();
let filter = doc! { "length": doc! { "$gt": "1000" } };
let mut cursor = my_coll.find(filter, opts).await?;
while let Some(result) = cursor.try_next().await? {
println!("{}", result);
};

If you run the preceding find operation without setting the numeric_ordering option to true, the driver compares length values as strings and orders the string value "1000" before the values "474" and "918". In this case, the preceding find operation returns all documents in the books collection.

To learn more about the find() method, see the Retrieve Data guide.

To learn more about collations, see the following Server manual pages:

To learn more about any of the methods or types mentioned in this guide, see the following API documentation:

← Connection Pool Monitoring