Collations

Collection

You can only set a default collation to a collection during creation. However, you can specify a collation in a new index on an existing collection. All supported operations that scan the collection then apply the default collation. See the Index section of this guide for more information.

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

Mono.from(database.createCollection(
                "items",
                new CreateCollectionOptions().collation(
                        Collation.builder().locale("en_US").build())))
        .block();

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

List<Document> indexes = Flux.from(itemsCollection.listIndexes())
        .collectList().block();
if (indexes != null) {
    indexes.forEach(idx -> System.out.println(idx.toJson()));
}

The output of the preceding code should contain the following:

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

Index

You can specify a collation when you create a new index on a collection. The index stores documents in the specified order, eliminating the need for in-memory sorting during queries. To use the index, the operation must use the same collation as specified in the index and be covered by that index.

The following example shows how to create an index on the "name" field with the "en_US" locale collation in ascending order:

IndexOptions idxOptions = new IndexOptions();
idxOptions.collation(Collation.builder().locale("en_US").build());
Mono.from(itemsCollection.createIndex(
        Indexes.ascending("name"), idxOptions)).block();

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

List<Document> indexes = Flux.from(itemsCollection.listIndexes())
        .collectList().block();
if (indexes != null) {
    indexes.forEach(idx -> System.out.println(idx.toJson()));
}

The output of the preceding code should contain the following:

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

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

FindPublisher<Document> indexPublisher = itemsCollection.find()
        .collation(Collation.builder().locale("en_US").build())
        .sort(Sorts.ascending("name"));
Flux.from(indexPublisher)
        .doOnNext(doc -> System.out.println(doc.toJson()))
        .blockLast();

Operation

You can override the default collation by passing a new collation to a supported operation. However, without an index, your query performs in-memory sorting, which is slower than using an indexed collation. For more information about the disadvantages of sorting operations not covered by an index, see Use Indexes to Sort Query Results in the MongoDB Server manual.

The following example shows a query operation with the following characteristics:

• The referenced collection has a default "en_US" collation index, similar to the one specified in the Collection section.

• The query specifies the Icelandic ("is") collation. Because this differs from the index collation, the query does not use the index and performs an in-memory sort instead.

FindPublisher<Document> customPublisher = itemsCollection.find()
        .collation(Collation.builder().locale("is").build())
        .sort(Sorts.ascending("name"));
Flux.from(customPublisher)
        .doOnNext(doc -> System.out.println(doc.toJson()))
        .blockLast();

Index Types That Do Not Support Collations

Most MongoDB index types support collation. However, the following types support only binary comparison and do not support collation:

• text

• 2d

find() and sort() Example

The following example shows how to 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.

FindPublisher<Document> findPublisher = phonebookCollection.find()
        .collation(Collation.builder()
                .locale("de@collation=phonebook").build())
        .sort(Sorts.ascending("first_name"));
Flux.from(findPublisher)
        .doOnNext(doc -> System.out.println(doc.toJson()))
        .blockLast();

When you perform this operation on the example collection, the output resembles the following:

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

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

• find()

• sort()

• Sorts

findOneAndUpdate() Example

The following example specifies a collation in a findOneAndUpdate() operation by instantiating a FindOneAndUpdateOptions object and passing it as a parameter. The example performs the following operations:

• Retrieves the first document in the example collection that precedes "Gunter" in ascending order.

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

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

• Retrieves and prints the updated document.

Document updatedDoc = Mono.from(
                phonebookCollection.findOneAndUpdate(
                        Filters.lt("first_name", "Gunter"),
                        Updates.set("verified", true),
                        new FindOneAndUpdateOptions()
                                .collation(Collation.builder()
                                        .locale("de@collation=phonebook")
                                        .build())
                                .sort(Sorts.ascending("first_name"))
                                .returnDocument(ReturnDocument.AFTER)))
        .block();
if (updatedDoc != null) {
    System.out.println("Updated document: " + updatedDoc.toJson());
}

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

Updated document: {"_id": 3, "first_name": "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

The following example specifies a numeric ordering collation in a findOneAndDelete() operation by instantiating a FindOneAndDeleteOptions object and passing it as a parameter. The collection contains the following documents:

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

The collation sets the locale option to "en" and the numericOrdering option to "true" to sort strings based on their numerical value.

Document deletedDoc = Mono.from(
                numericalCollection.findOneAndDelete(
                        Filters.gt("a", "100"),
                        new FindOneAndDeleteOptions()
                                .collation(Collation.builder()
                                        .locale("en")
                                        .numericOrdering(true)
                                        .build())
                                .sort(Sorts.ascending("a"))))
        .block();
if (deletedDoc != null) {
    System.out.println("Deleted document: " + deletedDoc.toJson());
}

After you run the preceding operation, your output resembles the following:

Deleted document: {"_id": 3, "a": "179 bananas"}

The numeric value of the string "179" is greater than 100, so the preceding document is the only match. Without numerical ordering, binary collation sorts "100" before "16", "84", and "179", so the filter matches all documents.

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

• findOneAndDelete()

• FindOneAndDeleteOptions

• Filters

• Sorts

Aggregation Example

The following example shows how to specify a collation in an aggregation operation. 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 AggregatePublisher returned by the aggregation operation. Specify a sort aggregation stage in your pipeline to apply the collation.

The following example constructs an aggregation pipeline on the example collection and applies a collation by specifying the following:

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

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

• An ascending sort on the _id field of the output documents.

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

Bson groupStage = Aggregates.group(
        "$first_name", Accumulators.sum("nameCount", 1));
Bson sortStage = Aggregates.sort(Sorts.ascending("_id"));
AggregatePublisher<Document> aggregatePublisher =
        phonebookCollection
                .aggregate(Arrays.asList(groupStage, sortStage))
                .collation(Collation.builder()
                        .locale("de")
                        .collationStrength(CollationStrength.PRIMARY)
                        .build());
Flux.from(aggregatePublisher)
        .doOnNext(doc -> System.out.println(doc.toJson()))
        .blockLast();

The preceding code outputs the following documents:

{"_id": "Gunter", "nameCount": 2}
{"_id": "Hannah", "nameCount": 1}
{"_id": "Jürgen", "nameCount": 1}
{"_id": "Klara", "nameCount": 1}

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

• aggregate()

• AggregatePublisher

• CollationStrength

• Accumulators

• Aggregates

• Sorts