python-pymongo-doc 3.6.1+dfsg1-1 / usr / share / doc / python-pymongo-doc / html / _sources / examples / collations.rst.txt

This file is indexed.

/usr/share/doc/python-pymongo-doc/html/_sources/examples/collations.rst.txt is in python-pymongo-doc 3.6.1+dfsg1-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below. 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
Collations
==========

.. seealso:: The API docs for :mod:`~pymongo.collation`.

Collations are a new feature in MongoDB version 3.4. They provide a set of rules
to use when comparing strings that comply with the conventions of a particular
language, such as Spanish or German. If no collation is specified, the server
sorts strings based on a binary comparison. Many languages have specific
ordering rules, and collations allow users to build applications that adhere to
language-specific comparison rules.

In French, for example, the last accent in a given word determines the sorting
order. The correct sorting order for the following four words in French is::

  cote < côte < coté < côté

Specifying a French collation allows users to sort string fields using the
French sort order.

Usage
-----

Users can specify a collation for a
:ref:`collection<collation-on-collection>`, an
:ref:`index<collation-on-index>`, or a
:ref:`CRUD command <collation-on-operation>`.

Collation Parameters:
~~~~~~~~~~~~~~~~~~~~~

Collations can be specified with the :class:`~pymongo.collation.Collation` model
or with plain Python dictionaries. The structure is the same::

   Collation(locale=<string>,
             caseLevel=<bool>,
             caseFirst=<string>,
             strength=<int>,
             numericOrdering=<bool>,
             alternate=<string>,
             maxVariable=<string>,
             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 MongoDB `manual
</>`_.

.. COMMENT add link for manual entry.

.. _collation-on-collection:

Assign a Default Collation to a Collection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following example demonstrates how to create a new collection called
``contacts`` and assign a default collation with the ``fr_CA`` locale. This
operation ensures that all queries that are run against the ``contacts``
collection use the ``fr_CA`` collation unless another collation is explicitly
specified::

  from pymongo import MongoClient
  from pymongo.collation import Collation

  db = MongoClient().test
  collection = db.create_collection('contacts',
                                    collation=Collation(locale='fr_CA'))

.. _collation-on-index:

Assign a Default Collation to an Index
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When creating a new index, you can specify a default collation.

The following example shows how to create an index on the ``name``
field of the ``contacts`` collection, with the ``unique`` parameter
enabled and a default collation with ``locale`` set to ``fr_CA``::

  from pymongo import MongoClient
  from pymongo.collation import Collation

  contacts = MongoClient().test.contacts
  contacts.create_index('name',
                        unique=True,
                        collation=Collation(locale='fr_CA'))

.. _collation-on-operation:

Specify a Collation for a Query
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Individual queries can specify a collation to use when sorting
results. The following example demonstrates a query that runs on the
``contacts`` collection in database ``test``. It matches on
documents that contain ``New York`` in the ``city`` field,
and sorts on the ``name`` field with the ``fr_CA`` collation::

  from pymongo import MongoClient
  from pymongo.collation import Collation

  collection = MongoClient().test.contacts
  docs = collection.find({'city': 'New York'}).sort('name').collation(
      Collation(locale='fr_CA'))

Other Query Types
~~~~~~~~~~~~~~~~~

You can use collations to control document matching rules for several different
types of queries. All the various update and delete methods
(:meth:`~pymongo.collection.Collection.update_one`,
:meth:`~pymongo.collection.Collection.update_many`,
:meth:`~pymongo.collection.Collection.delete_one`, etc.) support collation, and
you can create query filters which employ collations to comply with any of the
languages and variants available to the ``locale`` parameter.

The following example uses a collation with ``strength`` set to
:const:`~pymongo.collation.CollationStrength.SECONDARY`, which considers only
the base character and character accents in string comparisons, but not case
sensitivity, for example. All documents in the ``contacts`` collection with
``jürgen`` (case-insensitive) in the ``first_name`` field are updated::

  from pymongo import MongoClient
  from pymongo.collation import Collation, CollationStrength

  contacts = MongoClient().test.contacts
  result = contacts.update_many(
      {'first_name': 'jürgen'},
      {'$set': {'verified': 1}},
      collation=Collation(locale='de',
                          strength=CollationStrength.SECONDARY))

APT Browse - Built by Thomas Orozco.