Collations

find() and sort() Example

The following example calls both find() and sort() on a collection that uses the default binary collation. We use the German collation by setting the value of the locale parameter to de.

myColl.find({ city: "New York" }, { collation: { locale: "de" } })
  .sort({ name: 1 });

findOneAndUpdate() Example

The following example calls the findOneAndUpdate() operation on a collection that uses the default binary collation. The collection contains the following documents:

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

Consider the following findOneAndUpdate() operation on this collection which does not specify a collation:

myColl.findOneAndUpdate(
  { first_name : { $lt: "Gunter" } },
  { $set: { verified: true } }
);

Since "Gunter" is the first sorted result when using a binary collation, none of the documents come lexically before and match the $lt comparison operator in the query document. As a result, the operation does not update any documents.

Consider the same operation with a collation specified with the locale set to de@collation=phonebook. This locale specifies the collation=phonebook option which contains rules for prioritizing proper nouns, identified by capitalization of the first letter. The de@collation=phonebook locale and option sorts characters with umlauts before the same characters without umlauts.

myColl.findOneAndUpdate(
  { first_name: { $lt: "Gunter" } },
  { $set: { verified: true } },
  { collation: { locale: "de@collation=phonebook" } },
);

Since "Günter" lexically comes before "Gunter" using the de@collation=phonebook collation specified in findOneAndUpdate(), the operation returns the following updated document:

{ lastErrorObject: { updatedExisting: true, n: 1 },
  value: { _id: 3, first_name: 'Günter' },
  ok: 1 }

findOneAndDelete() Example

The following example calls the findOneAndDelete() operation on a collection that uses the default binary collation and contains the following documents:

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

In this example, we set the numericOrdering collation parameter to true to sort numeric strings based on their numerical order instead of their lexical order.

myColl.findOneAndDelete(
  { a: { $gt: "100" } },
  { collation: { locale: "en", numericOrdering: true } },
);

After you run the operation above, the collection contains the following documents:

{ "_id" : 1, "a" : "16" }
{ "_id" : 2, "a" : "84" }

If you perform the same operation without collation on the original collection of three documents, it matches documents based on the lexical value of the strings ("16", "84", and "179"), and deletes the first document it finds that matches the query criteria.

await myColl.findOneAndDelete({ a: { $gt: "100" } });

Since all the documents contain lexical values in the a field that match the criteria (greater than the lexical value of "100"), the operation removes the first result. After you run the operation above, the collection contains the following documents:

{ "_id" : 2, "a" : "84" }
{ "_id" : 3, "a" : "179" }

Aggregation Example

To use collation with the aggregate operation, pass the collation document in the options field, after the array of pipeline stages.

The following example shows an aggregation pipeline on a collection that uses the default binary collation. The aggregation groups the first_name field, counts the total number of results in each group, and sorts the results by the German phonebook (de@collation=phonebook locale) order.

myColl.aggregate(
  [
    { $group: { "_id": "$first_name", "nameCount": { "$sum": 1 } } },
    { $sort: { "_id": 1 } },
  ],
  { collation: { locale: "de@collation=phonebook" } },
);