Collations

Since version 3.4, MongoDB supports collations for collection and index creation and various query operations. Collations define string comparison rules based on the ICU collations. A collation document consists of various properties that are encapsulated in Collation, as the following listing shows:

Collation collation = Collation.of("fr")         (1)

  .strength(ComparisonLevel.secondary()          (2)
    .includeCase())

  .numericOrderingEnabled()                      (3)

  .alternate(Alternate.shifted().punct())        (4)

  .forwardDiacriticSort()                        (5)

  .normalizationEnabled();                       (6)

1	`Collation` requires a locale for creation. This can be either a string representation of the locale, a `Locale` (considering language, country, and variant) or a `CollationLocale`. The locale is mandatory for creation.
2	Collation strength defines comparison levels that denote differences between characters. You can configure various options (case-sensitivity, case-ordering, and others), depending on the selected strength.
3	Specify whether to compare numeric strings as numbers or as strings.
4	Specify whether the collation should consider whitespace and punctuation as base characters for purposes of comparison.
5	Specify whether strings with diacritics sort from back of the string, such as with some French dictionary ordering.
6	Specify whether to check whether text requires normalization and whether to perform normalization.

Collations can be used to create collections and indexes. If you create a collection that specifies a collation, the collation is applied to index creation and queries unless you specify a different collation. A collation is valid for a whole operation and cannot be specified on a per-field basis.

Like other metadata, collations can be be derived from the domain type via the collation attribute of the @Document annotation and will be applied directly when running queries, creating collections or indexes.

Annotated collations will not be used when a collection is auto created by MongoDB on first interaction. This would require additional store interaction delaying the entire process. Please use MongoOperations.createCollection for those cases.

Collation french = Collation.of("fr");
Collation german = Collation.of("de");

template.createCollection(Person.class, CollectionOptions.just(collation));

template.indexOps(Person.class).ensureIndex(new Index("name", Direction.ASC).collation(german));

MongoDB uses simple binary comparison if no collation is specified (Collation.simple()).

Using collations with collection operations is a matter of specifying a Collation instance in your query or operation options, as the following two examples show:

Example 1. Using collation with find

Collation collation = Collation.of("de");

Query query = new Query(Criteria.where("firstName").is("Amél")).collation(collation);

List<Person> results = template.find(query, Person.class);

Example 2. Using collation with aggregate

Collation collation = Collation.of("de");

AggregationOptions options = AggregationOptions.builder().collation(collation).build();

Aggregation aggregation = newAggregation(
  project("tags"),
  unwind("tags"),
  group("tags")
    .count().as("count")
).withOptions(options);

AggregationResults<TagCount> results = template.aggregate(aggregation, "tags", TagCount.class);

Indexes are only used if the collation used for the operation matches the index collation.

MongoDB Repositories support Collations via the collation attribute of the @Query annotation.