Collations

Sample Data for Examples

The examples on this page use a MongoDB collection with the following documents:

{ "_id" : 1, "firstName" : "Klara" }
{ "_id" : 2, "firstName" : "Gunter" }
{ "_id" : 3, "firstName" : "Günter" }
{ "_id" : 4, "firstName" : "Jürgen" }
{ "_id" : 5, "firstName" : "Hannah" }

These documents are represented by the following data class:

data class FirstName(
    @BsonId val id: Int, 
    val firstName: String, 
    val verified: Boolean = false
)

Collection

You can set a default collation when you create a collection. When you create a collection with a specified collation, all supported operations that scan that collection apply the rules of the collation.

You can only assign a default collation to a collection when you create that collection. However, you can specify a collation in a new index on an existing collection. See the Index section of this guide for more information.

The following snippet shows how to specify the "en_US" locale collation when creating a new collection called items:

database.createCollection(
    "names",
    CreateCollectionOptions().collation(
        Collation.builder().locale("en_US").build()
    )
)

To check whether you created the collation successfully, retrieve a list of the indexes on that collection as follows:

val collection = database.getCollection<FirstName>("names")
val indexInformation = collection.listIndexes().first()
println(indexInformation.toJson())

{
  // ...
  "collation": {
     "locale": "en_US",
     // ...
  },
  // ...
}

Index

You can specify a collation when you create a new index on a collection. The index stores an ordered representation of the documents in the collection so your operation does not need to perform the ordering in-memory. To use the index, your operation must meet the following criteria:

• The operation uses the same collation as the one specified in the index.

• The operation is covered by the index that contains the collation.

The following code snippet shows how you can create an index on the "firstName" field with the "en_US" locale collation in ascending order:

val collection = database.getCollection<FirstName>("names")
val idxOptions = IndexOptions().collation(Collation.builder().locale("en_US").build())
collection.createIndex(Indexes.ascending(FirstName::firstName.name), idxOptions)

To check whether you created the collation successfully, retrieve a list of the indexes on that collection as follows:

val collection = database.getCollection<FirstName>("names")
val indexInformation = collection.listIndexes().first()
println(indexInformation.toJson())

{
  // ...
  "collation": {
     "locale": "en_US",
     // ...
  },
  // ...
}

The following code snippet shows an example operation that specifies the same collation and is covered by the index we created in the preceding code snippet:

val resultsFlow = collection.find()
    .collation(Collation.builder().locale("en_US").build())
    .sort(Sorts.ascending(FirstName::firstName.name));

Operation

You can override the default collation on a collection by passing the new collation as a parameter to one of the supported operations. However, since the operation does not use an index, the operation may not perform as well as one that is covered by an index. For more information on the disadvantages of sorting operations not covered by an index, see the server manual page on Use Indexes to Sort Query Results.

The following code snippet shows an example query operation with the following characteristics:

• The referenced collection contains the default collation "en_US" similar to the one specified in the Collection section.

• The query specifies the Icelandic ("is") collation which is not covered by the collection's default collation index.

• Since the specified collation is not covered by an index, the sort operation is performed in-memory.

val findFlow = collection.find()
    .collation(Collation.builder().locale("is").build())
    .sort(Sorts.ascending(FirstName::firstName.name))

Index Types That Do Not Support Collations

While most MongoDB index types support collation, the following types support only binary comparison:

• text

• 2d

• geoHaystack

find() and sort() Example

The following example demonstrates how you can apply a collation when retrieving sorted results from a collection. To perform this operation, call find() on the example collection and chain the collation() and sort() methods to specify the order in which you want to receive the results.

When we perform this operation on our example collection, the output should resemble the following:

val resultsFlow = collection.find()
    .collation(Collation.builder().locale("de@collation=phonebook").build())
    .sort(Sorts.ascending(FirstName::firstName.name))
resultsFlow.collect { println(it) }

FirstName(id=3, firstName=Günter, verified=false)
FirstName(id=2, firstName=Gunter, verified=false)
FirstName(id=5, firstName=Hannah, verified=false)
FirstName(id=4, firstName=Jürgen, verified=false)
FirstName(id=1, firstName=Klara, verified=false)

For more information about the methods and classes mentioned in this section, see the following API Documentation:

• find()

• sort()

• Sorts

findOneAndUpdate() Example

This section demonstrates how you can specify a collation in an operation that updates the first match from your query. To specify the collation for this operation, instantiate a FindOneAndUpdateOptions object, set a collation on it, and pass it as a parameter to your call to the findOneAndUpdate() method.

In this example, we demonstrate the following:

• Retrieve the first document in our example collection that precedes "Gunter" in an ascending order.

• Set options for operation including the "de@collation=phonebook" collation.

• Add a new field "verified" with the value "true".

• Retrieve and print the updated document.

Since "Günter" is lexically before "Gunter" using the de@collation=phonebook collation in ascending order, the following operation returns "Günter" before "Gunter" in the results:

val result = collection.findOneAndUpdate(
    Filters.lt(FirstName::firstName.name, "Gunter"),
    Updates.set("verified", true),
    FindOneAndUpdateOptions()
        .collation(Collation.builder().locale("de@collation=phonebook").build())
        .sort(Sorts.ascending(FirstName::firstName.name))
        .returnDocument(ReturnDocument.AFTER)
)
println(result)

FirstName(id=3, firstName=Günter, verified=true)

For more information about the methods and classes mentioned in this section, see the following API Documentation:

• findOneAndUpdate

• findOneAndUpdateOptions

• Filters

• Updates

• Sorts

findOneAndDelete() Example

This section demonstrates how you can specify a numerical ordering of strings in a collation in an operation that deletes the first match from your query. To specify the collation for this operation, instantiate a FindOneAndDeleteOptions object, set a numeric ordering collation on it, and pass it as a parameter to your call to the findOneAndDelete() method.

This example calls the findOneAndDelete() operation on a collection that contains the following documents:

{ "_id" : 1, "a" : "16 apples" }
{ "_id" : 2, "a" : "84 oranges" }
{ "_id" : 3, "a" : "179 bananas" }

These documents are represented by the following data class:

data class CollationExample(@BsonId val id: Int, val a: String)

In the collation, we set the locale option to "en" and the numericOrdering option to "true" in order to sort strings based on their numerical order.

val result = collection.findOneAndDelete(
    Filters.gt(CollationExample::a.name, "100"),
    FindOneAndDeleteOptions()
        .collation(Collation.builder().locale("en").numericOrdering(true).build())
        .sort(Sorts.ascending(CollationExample::a.name))
)
println(result)

CollationExample(id=3, a=179 bananas)

The numeric value of the string "179" is greater than the number 100, so the preceding document is the only match.

If we perform the same operation without the numerical ordering collation on the original collection of three documents, the filter matches all of our documents since "100" comes before "16", "84", and "179" when ordering by binary collation.

For more information about the methods and classes mentioned in this section, see the following API Documentation:

• findOneAndDelete

• FindOneAndDeleteOptions

• Filters

• Sorts

Aggregation Example

This section demonstrates how you can specify a collation in an aggregation operation. In an aggregation operation, you can specify a series of aggregation stages which is collectively called the aggregation pipeline. To perform an aggregation, call the aggregate() method on a MongoCollection object.

To specify a collation for an aggregation operation, call the collation() method on the AggregateFlow returned by the aggregation operation. Make sure to specify a sort aggregation stage on which to apply the collation in your aggregation pipeline.

The following example shows how we can construct an aggregation pipeline on the example collection and apply a collation by specifying the following:

• A group aggregation stage using the Aggregates.group() helper to identify each document by the firstName field and use that value as the _id of the result.

• An accumulator in the group aggregation stage to sum the number of instances of matching values in the firstName field.

• Apply an ascending sort to the _id field of the output documents of the prior aggregation stage.

• Construct a collation object, specifying the German locale and a collation strength that ignores accents and umlauts.

data class Result(@BsonId val id: String, val nameCount: Int)
val groupStage = Aggregates.group(
    "\$${FirstName::firstName.name}",
    Accumulators.sum("nameCount", 1)
)
val sortStage = Aggregates.sort(Sorts.ascending("_id"))
val resultsFlow = collection.aggregate<Result>(listOf(groupStage, sortStage))
    .collation(
        Collation.builder().locale("de")
            .collationStrength(CollationStrength.PRIMARY)
            .build()
    )
resultsFlow.collect { println(it) }

Result(id=Gunter, nameCount=2)
Result(id=Hannah, nameCount=1)
Result(id=Jürgen, nameCount=1)
Result(id=Klara, nameCount=1)

For more information about the methods and classes mentioned in this section, see the following API Documentation:

• aggregate()

• AggregateFlow

• CollationStrength

• Accumulators

• Aggregates

• Sorts