Collations

Overview

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 Collations

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.

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 "é".

Specify a Collation

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.

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:

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

Set a Collation on a Collection

When you create a new collection, you can define the collation for future operations called on that collection. Set the collation by chaining the collation() function to the create_collection() method, passing your Collation instance as a parameter to collation().

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

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

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

{ "name": "Emma", "length": 474 }
{ "name": "Cryptonomicon", "length": 918 }
{ "name" : "Ça", "length" : "1138" }

Set a Collation on an Index

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.

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.

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).await?;
println!("Created index: {}", result.index_name);

 Created index: name_1

Set a Collation on an Operation

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.

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

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

Additional Information

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

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

• Collation

• Collation Locales and Default Parameters