Collations
On this page
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 instanceSet 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.
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 "é".
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.
Note
Instantiating Structs
The Rust driver implements the Builder design pattern for the
creation of some struct 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) | 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 toCollationAlternate::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 |
Example
The following example specifies a Collation
instance and sets the collation locale to "en_US"
:
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()
.
Create Collection with a Collation Example
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 result = my_db.create_collection("books") .collation(collation) .await?;
Collation Ordering Demonstration
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).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.
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.
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.
Example
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).await?; println!("Created index: {}", result.index_name);
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.
Example
This example performs the following actions:
Sets the
numeric_ordering
collation option totrue
, which ensures that values are sorted in numerical order rather than alphabetical orderUses the
find()
method to return documents in which the value of thelength
field is greater than"1000"
Specifies a collation by chaining the
collation()
method to thefind()
method, which overrides the collection's collation
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); };
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.
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:
API Documentation
To learn more about any of the methods or types mentioned in this guide, see the following API documentation: