Collation¶

On this page

Collation Document
Operations that Support Collation
Behavior

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.

You can specify collation for a collection or a view, an index, or specific operations that support collation.

Collation Document¶

A collation document has the following fields:

{
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

When specifying collation, the locale field is mandatory; all other collation fields are optional. For descriptions of the fields, see Collation Document.

Default collation parameter values vary depending on which locale you specify. For a complete list of default collation parameters and the locales they are associated with, see Collation Default Parameters.

Field Type Description

locale

string

The ICU locale. See Supported Languages and Locales for a list of supported locales.

To specify simple binary comparison, specify locale value of "simple".

strength

integer

Optional. The level of comparison to perform. Corresponds to ICU Comparison Levels. Possible values are:

Value	Description
1	Primary level of comparison. Collation performs comparisons of the base characters only, ignoring other differences such as diacritics and case.
2	Secondary level of comparison. Collation performs comparisons up to secondary differences, such as diacritics. That is, collation performs comparisons of base characters (primary differences) and diacritics (secondary differences). Differences between base characters takes precedence over secondary differences.
3	Tertiary level of comparison. Collation performs comparisons up to tertiary differences, such as case and letter variants. That is, collation performs comparisons of base characters (primary differences), diacritics (secondary differences), and case and variants (tertiary differences). Differences between base characters takes precedence over secondary differences, which takes precedence over tertiary differences. This is the default level.
4	Quaternary Level. Limited for specific use case to consider punctuation when levels 1-3 ignore punctuation or for processing Japanese text.
5	Identical Level. Limited for specific use case of tie breaker.

See ICU Collation: Comparison Levels for details.

caseLevel

boolean

Optional. Flag that determines whether to include case comparison at strength level 1 or 2.

If true, include case comparison; i.e.

When used with strength:1, collation compares base characters and case.
When used with strength:2, collation compares base characters, diacritics (and possible other secondary differences) and case.

If false, do not include case comparison at level 1 or 2. The default is false.

For more information, see ICU Collation: Case Level.

caseFirst

boolean

Optional. A flag that determines sort order of case differences during tertiary level comparisons.

Possible values are:

Value	Description
“upper”	Uppercase sorts before lowercase.
“lower”	Lowercase sorts before uppercase.
“off”	Default value. Similar to `"lower"` with slight differences. See http://userguide.icu-project.org/collation/customization for details of differences.

numericOrdering

boolean

Optional. Flag that determines whether to compare numeric strings as numbers or as strings.

If true, compare as numbers; i.e. "10" is greater than "2".

If false, compare as strings; i.e. "10" is less than "2".

Default is false.

alternate

string

Optional. Field that determines whether collation should consider whitespace and punctuation as base characters for purposes of comparison.

Possible values are:

Value	Description
`"non-ignorable"`	Whitespace and punctuation are considered base characters.
`"shifted"`	Whitespace and punctuation are not considered base characters and are only distinguished at strength levels greater than 3.

See ICU Collation: Comparison Levels for more information.

Default is "non-ignorable".

maxVariable

string

Optional. Field that determines up to which characters are are considered ignorable when alternate: "shifted". Has no effect if alternate: "non-ignorable"

Possible values are:

Value	Description
`"punct"`	Both whitespaces and punctuation are “ignorable”, i.e. not considered base characters.
`"space"`	Whitespace are “ignorable”, i.e. not considered base charactersnot considered base characters.

backwards

boolean

Optional. Flag that determines whether strings with diacritics sort from back of the string, such as with some French dictionary ordering.

If true, compare from back to front.

If false, compare from front to back.

The default value is false.

normalization

boolean

Optional. Flag that determines whether to check if text require normalization and to perform normalization. Generally, majority of text does not require this normalization processing.

If true, check if fully normalized and perform normaliztion to compare text.

If false, does not check.

The default value is false.

See http://userguide.icu-project.org/collation/concepts#TOC-Normalization for details.

Operations that Support Collation¶

You can specify collation for the following operations:

Commands	`mongo` Shell Methods
`create`	`db.createCollection()` `db.createView()`
`createIndexes`	`db.collection.createIndex()`
`aggregate`	`db.collection.aggregate()`
`distinct`	`db.collection.distinct()`
`findAndModify`	`db.collection.findAndModify()` `db.collection.findOneAndDelete()` `db.collection.findOneAndReplace()` `db.collection.findOneAndUpdate()`
`find`	`cursor.collation()` to specify collation for `db.collection.find()`
`mapReduce`	`db.collection.mapReduce()`
`delete`	`db.collection.deleteOne()` `db.collection.deleteMany()` `db.collection.remove()`
`update`	`db.collection.update()` `db.collection.updateOne()`, `db.collection.updateMany()`, `db.collection.replaceOne()`
	Individual update, replace, and delete operations in `db.collection.bulkWrite()`.

Behavior¶

Some collation locales have variants, which employ special language-specific rules. To specify a locale variant, use the following syntax:

{ "locale" : "<locale code>@collation=<variant>" }

For example, to use the pinyin variant of the Chinese collation:

{ "locale" : "zh@collation=pinyin" }

For a complete list of all collation locales and their variants, see Collation Locales.

← Connection String URI Format Collation Locales and Default Parameters →