cursor.collation()¶

Definition定义¶

cursor.collation(<collation document>)¶

mongo Shell Method

This page documents the mongo shell method, and does not refer to the MongoDB Node.js driver (or any other driver) method. 本页记录了mongo shell方法，未提及MongoDB Node.js驱动程序（或任何其他驱动程序）方法。For corresponding MongoDB driver API, refer to your specific MongoDB driver documentation instead.有关相应的MongoDB驱动程序API，请参阅特定的MongoDB驱动程序文档。

New in version 3.4.版本3.4中的新功能。

Specifies the collation for the cursor returned by the db.collection.find(). 指定db.collection.find()返回的游标的排序规则。To use, append to the db.collection.find().要使用，请附加到db.collection.find()。

The cursor.collation() accepts the following collation document:cursor.collation()接受以下排序规则文档：

{
   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. 指定排序规则时，locale字段是必需的；所有其他排序规则字段都是可选的。For descriptions of the fields, see Collation Document.有关这些字段的描述，请参阅排序规则文档。

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.限于特定用例，当水平1-3忽略标点符号或处理日语文本时考虑标点符号。 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. 如果为false，则不包括级别1或2的案例比较。The default is false.默认值为false。 For more information, see ICU Collation: Case Level.
caseFirst	string	Optional.可选。A field 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.空格和标点符号不被视为基本字符，只能在大于3的强度级别进行区分。 See ICU Collation: Comparison Levels for more information. Default is "non-ignorable".
maxVariable	string	Optional.可选。Field that determines up to which characters 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 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.如果为true，则从后到前进行比较。 If false, compare from front to back.如果为false，则从前面到后面进行比较。 The default value is false.默认值为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 normalization to compare text.如果为true，请检查是否完全规范化，并执行规范化以比较文本。 If false, does not check.如果为false，则不进行检查。 The default value is false.默认值为false。 See http://userguide.icu-project.org/collation/concepts#TOC-Normalization for details.

Examples示例¶

Consider a collection foo with the following documents:使用以下文档来考虑foo集合：

{ "_id" : 1, "x" : "a" }
{ "_id" : 2, "x" : "A" }
{ "_id" : 3, "x" : "á" }

The following operation specifies a query filter of x: "a". The operation also includes a collation option with locale: "en_US" (US English locale) and strength: 1 (compare base characters only; i.e. ignore case and diacritics):

db.foo.find( { x: "a" } ).collation( { locale: "en_US", strength: 1 } )

The operation returns the following documents:该操作将返回以下文档：

{ "_id" : 1, "x" : "a" }
{ "_id" : 2, "x" : "A" }
{ "_id" : 3, "x" : "á" }

If you do not specify the collation, i.e. db.collection.find( { x: "a" } ), the query would only match the following document:如果不指定排序规则，即db.collection.find( { x: "a" } )，则查询将只匹配以下文档：

db.foo.find( { x: "a" } )

You can chain other cursor methods, such as cursor.sort() and cursor.count(), to cursor.collation():

db.collection.find({...}).collation({...}).sort({...});
db.collection.find({...}).collation({...}).count();