docs/reference/collations.txt
**********
Collations
**********
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
Overview
========
.. versionadded:: 3.4
Collations are sets of rules for how to compare strings, typically in a
particular natural language.
For example, in Canadian French, the last accent in a given word
determines the sorting order.
Consider the following French words:
.. code-block:: none
cote < coté < côte < côté
The sort order using the Canadian French collation would result in
the following:
.. code-block:: none
cote < côte < coté < côté
If collation is unspecified, MongoDB uses the simple binary comparison for
strings. As such, the sort order of the words would be:
.. code-block:: none
cote < coté < côte < côté
Usage
=====
You can specify a default collation for collections and indexes when
they are created, or specify a collation for CRUD operations and
aggregations. For operations that support collation, MongoDB uses the
collection's default collation unless the operation specifies a
different collation.
Collation Parameters
~~~~~~~~~~~~~~~~~~~~
.. code-block:: ruby
'collation' => {
'locale' => <string>,
'caseLevel' => <bool>,
'caseFirst' => <string>,
'strength' => <int>,
'numericOrdering' => <bool>,
'alternate' => <string>,
'maxVariable' => <string>,
'normalization' => <bool>,
'backwards' => <bool>
}
The only required parameter is ``locale``, which the server parses as
an `ICU format locale ID <http://userguide.icu-project.org/locale>`_.
For example, set ``locale`` to ``en_US`` to represent US English
or ``fr_CA`` to represent Canadian French.
For a complete description of the available parameters, see the
:manual:`MongoDB manual entry</reference/collation>`.
.. _collation-on-collection:
Assign a Default Collation to a Collection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following example creates a new collection
called ``contacts`` on the ``test`` database and assigns a default
collation with the ``fr_CA`` locale. Specifying a collation when you
create the collection ensures that all operations involving a query
that are run against the
``contacts`` collection use the ``fr_CA`` collation, unless the query
specifies another collation. Any indexes on the new collection also
inherit the default collation, unless the creation command specifies
another collation.
.. code-block:: ruby
client = Mongo::Client.new([ "127.0.0.1:27017" ], :database => "test")
client[:contacts, { "collation" => { "locale" => "fr_CA" } } ].create
.. _collation-on-index:
Assign a Collation to an Index
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To specify a collation for an index, use the ``collation``
option when you create the index.
The following example creates an index on the ``name``
field of the ``address_book`` collection, with the ``unique`` parameter
enabled and a default collation with ``locale`` set to ``en_US``.
.. code-block:: ruby
client = Mongo::Client.new([ "127.0.0.1:27017" ], :database => "test")
client[:address_book].indexes.create_one( { "first_name" => 1 },
"unique" => true,
"collation" => { "locale" => "en_US" }
)
To use this index, make sure your queries also specify the same
collation. The following query uses the above index:
.. code-block:: ruby
client[:address_book].find({"first_name" : "Adam" },
"collation" => { "locale" => "en_US" })
The following queries do **NOT** use the index. The first query uses no
collation, and the second uses a collation with a different ``strength``
value than the collation on the index.
.. code-block:: ruby
client[:address_book].find({"first_name" : "Adam" })
client[:address_book].find({"first_name" : "Adam" },
"collation" => { "locale" => "en_US", "strength" => 2 })
Operations that Support Collation
=================================
All reading, updating, and deleting methods support collation. Some
examples are listed below.
``find()`` and ``sort()``
~~~~~~~~~~~~~~~~~~~~~~~~~
Individual queries can specify a collation to use when matching
and sorting results. The following query and sort operation uses
a German collation with the ``locale`` parameter set to ``de``.
.. code-block:: ruby
client = Mongo::Client.new([ "127.0.0.1:27017" ], :database => "test")
docs = client[:contacts].find({ "city" => "New York" },
{ "collation" => { "locale" => "de" } }).sort( "name" => 1 )
``find_one_and_update()``
~~~~~~~~~~~~~~~~~~~~~~~~~
A collection called ``names`` contains the following documents:
.. code-block:: javascript
{ "_id" : 1, "first_name" : "Hans" }
{ "_id" : 2, "first_name" : "Gunter" }
{ "_id" : 3, "first_name" : "Günter" }
{ "_id" : 4, "first_name" : "Jürgen" }
The following ``find_one_and_update`` operation on the collection
does not specify a collation.
.. code-block:: ruby
client = Mongo::Client.new([ "127.0.0.1:27017" ], :database => "test")
doc = client[:names].find_one_and_update( {"first_name" => { "$lt" => "Gunter" }},
{ "$set" => { "verified" => true } })
Because ``Gunter`` is lexically first in the collection,
the above operation returns no results and updates no documents.
Consider the same ``find_one_and_update`` operation but with the
collation specified. The locale is set to ``de@collation=phonebook``.
.. note::
Some locales have a ``collation=phonebook`` option available for
use with languages which sort proper nouns differently from other
words. According to the ``de@collation=phonebook`` collation,
characters with umlauts come before the same characters without
umlauts.
.. code-block:: ruby
client = Mongo::Client.new([ "127.0.0.1:27017" ], :database => "test")
doc = client[:names].find_one_and_update( { "first_name" => { "$lt" => "Gunter" } },
{ "$set" => { "verified" => true } }, { "collation" => { "locale" => "de@collation=phonebook" },
:return_document => :after } )
The operation returns the following updated document:
.. code-block:: javascript
{ "_id" => 3, "first_name" => "Günter", "verified" => true }
``find_one_and_delete()``
~~~~~~~~~~~~~~~~~~~~~~~~~
Set the ``numericOrdering`` collation parameter to ``true``
to compare numeric string by their numeric values.
The collection ``numbers`` contains the following documents:
.. code-block:: javascript
{ "_id" : 1, "a" : "16" }
{ "_id" : 2, "a" : "84" }
{ "_id" : 3, "a" : "179" }
The following example matches the first document in which field ``a``
has a numeric value greater than 100 and deletes it.
.. code-block:: ruby
docs = numbers.find_one_and_delete({ "a" => { "$gt" => "100" } },
{ "collation" => { "locale" => "en", "numericOrdering" => true } })
After the above operation, the following documents remain in the
collection:
.. code-block:: javascript
{ "_id" : 1, "a" : "16" }
{ "_id" : 2, "a" : "84" }
If you perform the same operation without collation, the server deletes
the first document it finds in which the lexical value of ``a`` is
greater than ``"100"``.
.. code-block:: ruby
numbers = client[:numbers]
docs = numbers.find_one_and_delete({ "a" => { "$gt" => "100" } })
After the above operation the document in which ``a`` was equal to
``"16"`` has been deleted, and the following documents remain in the
collection:
.. code-block:: javascript
{ "_id" : 2, "a" : "84" }
{ "_id" : 3, "a" : "179" }
``delete_many()``
~~~~~~~~~~~~~~~~~
You can use collations with all the various bulk operations which
exist in the Ruby driver.
The collection ``recipes`` contains the following documents:
.. code-block:: javascript
{ "_id" : 1, "dish" : "veggie empanadas", "cuisine" : "Spanish" }
{ "_id" : 2, "dish" : "beef bourgignon", "cuisine" : "French" }
{ "_id" : 3, "dish" : "chicken molé", "cuisine" : "Mexican" }
{ "_id" : 4, "dish" : "chicken paillard", "cuisine" : "french" }
{ "_id" : 5, "dish" : "pozole verde", "cuisine" : "Mexican" }
Setting the ``strength`` parameter of the collation document to ``1``
or ``2`` causes the server to disregard case in the query filter. The
following example uses a case-insensitive query filter
to delete all records in which the ``cuisine`` field matches
``French``.
.. code-block:: ruby
client = Mongo::Client.new([ "127.0.0.1:27017" ], :database => "test")
recipes = client[:recipes]
docs = recipes.delete_many({ "cuisine" => "French" },
"collation" => { "locale" => "en_US", "strength" => 1 })
After the above operation runs, the documents with ``_id`` values of
``2`` and ``4`` are deleted from the collection.
Aggregation
~~~~~~~~~~~
To use collation with an aggregation operation, specify a collation in
the aggregation options.
The following aggregation example uses a collection called ``names``
and groups the ``first_name`` field together, counts the total
number of results in each group, and sorts the
results by German phonebook order.
.. code-block:: ruby
aggregation = names.aggregate(
[
{
"$group" => { "_id" => "$first_name", "name_count" => { "$sum" => 1 } }
},
{
"$sort" => { "_id" => 1 }
},
], { "collation" => { "locale" => "de@collation=phonebook" } }
)
aggregation.each do |doc|
#=> Yields a BSON::Document.
end