Collations

Overview

In this guide, you can learn how to use collations to order your query or aggregation operation results by string values. A collation is a set of character ordering conventions that apply to a specific language and locale.

Collations in MongoDB

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.

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 them in the following order:

cote
coté
côte
côté

When using the Canadian French collation, MongoDB sorts them in the following order:

cote
côte
coté
côté

Specify a Collation

To specify a collation, create a Collation object. You must define the Locale field of the Collation object; all other fields are optional. For example, the following code example specifies a Collation object with the "en_US" locale collation:

myCollation := &options.Collation{Locale: "en_US"}

For a complete list of Collation object fields, visit the Collation API documentation. To see all the supported locales and the default values for the Locale fields, visit Supported Languages and Locales.

Set a Collation on a Collection or View

You can apply a collation when you create a new collection or view. This defines the default collation for any operations called on that collection or view. Set a collation through a CreateCollectionOptions or CreateViewOptions object. Then, call the CreateCollection() or CreateView() method with your options object as an argument.

myCollation := &options.Collation{Locale: "fr", Strength: 1}
opts := options.CreateCollection().SetCollation(myCollation)
err := db.CreateCollection(context.TODO(), "books", opts)
if err != nil {
   panic(err)
}

{"name" : "Emma", "length" : "474"}
{"name" : "Les Misérables", "length": "1462"}
{"name" : "Infinite Jest", "length" : "1104"}
{"name" : "Cryptonomicon", "length" : "918"}
{"name" : "Ça", "length" : "1138"}

filter := bson.D{{"name", bson.D{{"$lt", "Infinite Jest"}}}}
cursor, err := coll.Find(context.TODO(), filter)
if err != nil {
   panic(err)
}
var results []bson.D
if err = cursor.All(context.TODO(), &results); err != nil {
   panic(err)
}
for _, result := range results {
   res, _ := bson.MarshalExtJSON(result, false, false)
   fmt.Println(string(res))
}

{"name":"Emma","length":"474"}
{"name":"Cryptonomicon","length":"918"}
{"name":"Ça","length":"1138"}

{"name":"Emma","length":"474"}
{"name":"Cryptonomicon","length":"918"}

Set a Collation on an Index

You can apply 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 MongoDB instance doesn't perform the ordering for sorting operations in-memory.

To use the index in an operation, your operation must use the same collation as the one specified in the index. Additionally, ensure that the operation is covered by the index that contains the collation. Set a collation through an IndexOptions object and pass this object as an argument to the CreateOne() method.

 myCollation := &options.Collation{Locale: "en_US"}
 opts := options.Index().SetCollation(myCollation)
 indexModel := mongo.IndexModel{
   Keys:    bson.D{{"name", 1}},
   Options: opts,
 }
 name, err := coll.Indexes().CreateOne(context.TODO(), indexModel)
 if err != nil {
   panic(err)
 }
 fmt.Println("Name of Index Created: " + name)

 Name of Index Created: name_1

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 default collation previously defined for a collection.

If you apply a new collation to an operation that differs from an index's collation, you cannot use that index. As a result, 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 Using Indexes to Sort Query Results. See the MongoDB manual for a list of operations that support collation.

filter := bson.D{{"length", bson.D{{"$gt", "1000"}}}}
myCollation := &options.Collation{Locale: "en_US", NumericOrdering: true}
opts := options.Find().SetCollation(myCollation)
cursor, err := coll.Find(context.TODO(), filter, opts)
if err != nil {
   panic(err)
}
var results []bson.D
if err = cursor.All(context.TODO(), &results); err != nil {
   panic(err)
}
for _, result := range results {
   res, _ := bson.MarshalExtJSON(result, false, false)
   fmt.Println(string(res))
}

{"name":"Les Misérables","length":"1462"}
{"name":"Infinite Jest","length":"1104"}
{"name":"Ça","length":"1138"}

{"name":"Emma","length":"474"}
{"name":"Les Misérables","length":"1462"}
{""name":"Infinite Jest","length":"1104"}
{"name":"Cryptonomicon","length":"918"}
{"name":"Ça","length":"1138"}

Additional Information

To learn more about the Find() method, see the Retrieve Data guide.

To learn more about collations, visit the following manual pages:

• Collation

• Collation Locales and Default Parameters