diff --git a/source/databases-collections.txt b/source/databases-collections.txt index 1195dd14..0b7ee96d 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -113,6 +113,25 @@ document count. The following example creates a capped collection called To learn more about capped collections, see :manual:`Capped Collections ` in the {+mdb-server+} manual. +Collation +~~~~~~~~~ + +When you create a collection, you can specify a default **collation** for all operations +you perform on the collection. + +.. include:: /includes/collation-description.rst + +The following example creates the same collection as the previous example, +but with a default collation of ``fr_CA``: + +.. code-block:: python + :emphasize-lines: 4 + + from pymongo.collation import Collation + + database = client["test_database"] + database.create_collection("example_collection", collation=Collation(locale='fr_CA')) + Get a List of Collections ------------------------- diff --git a/source/fundamentals/collations.txt b/source/fundamentals/collations.txt deleted file mode 100644 index 75876ee7..00000000 --- a/source/fundamentals/collations.txt +++ /dev/null @@ -1,149 +0,0 @@ -.. _pymongo-collations: - -Collations -========== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: order, sort, translation, accent, diacritic, compare - -Collations 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. However, many languages have specific -ordering rules, and collations allow users to build applications that adhere to -these rules. - -In French, for example, the last accent in a given word determines the sorting -order. The following example shows the correct sorting order for four words in French: - -.. code-block:: none - - cote < côte < coté < côté - -Specifying a French collation allows users to sort string fields using the -French sort order. - -Usage ------ - -You can specify a collation for a :ref:`collection `, an -:ref:`index`, or a :ref:`CRUD command `. - -Collation Parameters: -~~~~~~~~~~~~~~~~~~~~~ - -You can specify a collation by using the ``~pymongo.collation.Collation`` model -or Python dictionaries. In either case, the structure is the same: - -.. code-block:: python - - Collation(locale=, - caseLevel=, - caseFirst=, - strength=, - numericOrdering=, - alternate=, - maxVariable=, - backwards=) - -The only required parameter is ``locale``, which the server parses as -an `ICU format locale ID `__. -For example, set ``locale`` to ``en_US`` to represent US English -or ``fr_CA`` to represent Canadian French. - -.. _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. - -.. code-block:: python - - 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``. - -.. code-block:: python - - 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A query can specify a collation to use when sorting -results. The following example demonstrates a query that runs on the -``contacts`` collection in the ``test`` database. It matches on -documents that contain ``New York`` in the ``city`` field, -and sorts on the ``name`` field with the ``fr_CA`` collation. - -.. code-block:: python - - 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 methods that perform update or delete operations support collation, -and you can create query filters that use 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 -``~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. - -.. code-block:: python - - 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)) diff --git a/source/includes/collation-description-indexes.rst b/source/includes/collation-description-indexes.rst new file mode 100644 index 00000000..c15c6072 --- /dev/null +++ b/source/includes/collation-description-indexes.rst @@ -0,0 +1,12 @@ +When you create an index, you can specify a default **collation** for all operations +you perform on fields that are included in the index. + +.. include:: /includes/collation-description.rst + +To use an index with a specified collation, your operation must meet the following criteria: + +- The operation uses the same collation as the one specified in the index. +- The operation is covered by the index that contains the collation. + +The following example creates the same index as the previous example, +but with a default collation of ``fr_CA``: \ No newline at end of file diff --git a/source/includes/collation-description.rst b/source/includes/collation-description.rst new file mode 100644 index 00000000..3e275dd7 --- /dev/null +++ b/source/includes/collation-description.rst @@ -0,0 +1,11 @@ +A collation is a set of language-specific rules for string comparison, such as +for letter case and accent marks. + +To specify a collation, create an instance of the ``Collation`` class or a Python dictionary. +For a list of options to pass to the ``Collation`` constructor or include as keys in the +dictionary, see :manual:`Collation ` in the {+mdb-server+} manual. + +.. tip:: Import Collation + + To create an instance of the ``Collation`` class, you must import it from + ``pymongo.collation``. \ No newline at end of file diff --git a/source/includes/collation-override-note.rst b/source/includes/collation-override-note.rst new file mode 100644 index 00000000..dcf0ec84 --- /dev/null +++ b/source/includes/collation-override-note.rst @@ -0,0 +1,4 @@ +.. note:: Operation Collation Overrides Default + + When you specify a collation as part of an operation, it overrides the default + collation for the collection. \ No newline at end of file diff --git a/source/includes/indexes/indexes.py b/source/includes/indexes/indexes.py index 5e238034..7a3525a3 100644 --- a/source/includes/indexes/indexes.py +++ b/source/includes/indexes/indexes.py @@ -2,6 +2,12 @@ movies.create_index("title") # end-index-single +# start-index-single-collation +from pymongo.collation import Collation + +movies.create_index("title", collation=Collation(locale='fr_CA')) +# end-index-single-collation + # start-index-single-query query = { "title": "Batman" } sort = [("title", 1)] @@ -13,6 +19,13 @@ movies.create_index([("type", pymongo.ASCENDING), ("genre", pymongo.ASCENDING)]) # end-compound-index +# start-compound-index-collation +from pymongo.collation import Collation + +movies.create_index([("type", pymongo.ASCENDING), ("genre", pymongo.ASCENDING)], + collation=Collation(locale='fr_CA')) +# end-compound-index-collation + # start-index-compound-query query = { "type": "movie", "genre": "Drama" } sort = [("type", pymongo.ASCENDING), ("genre", pymongo.ASCENDING)] @@ -24,6 +37,12 @@ result = movies.create_index("cast") # end-index-multikey +# start-index-multikey-collation +from pymongo.collation import Collation + +result = movies.create_index("cast", collation=Collation(locale='fr_CA')) +# end-index-multikey-collation + # start-index-multikey-query query = { "cast": "Viola Davis" } @@ -36,6 +55,15 @@ ) # end-index-text-single +# start-index-text-single-collation +from pymongo.collation import Collation + +movies.create_index( + [( "plot", "text" )], + collation=Collation(locale='fr_CA') +) +# end-index-text-single-collation + # start-index-text-single-query query = { "$text": { "$search": "a time-traveling DeLorean" } } @@ -43,10 +71,13 @@ # end-index-text-single-query # start-index-text-multi +from pymongo.collation import Collation + result = myColl.create_index( [("title", "text"), ("genre", "text")], default_language="english", - weights={ "title": 10, "genre": 3 } + weights={ "title": 10, "genre": 3 }, + collation=Collation(locale='fr_CA') ) # end-index-text-multi @@ -56,14 +87,31 @@ ) # end-index-geo +# start-index-geo-collation +from pymongo.collation import Collation + +theaters.create_index( + [( "location.geo", "2dsphere" )], + collation=Collation(locale='fr_CA')) +# end-index-geo-collation + # start-index-wildcard movies.create_index({ "location.$**": pymongo.ASCENDING }) # end-index-wildcard +# start-index-wildcard-collation +movies.create_index({ "location.$**": pymongo.ASCENDING }, + collation=Collation(locale='fr_CA')) +# end-index-wildcard-collation + # start-index-unique theaters.create_index("theaterId", unique=True) # end-index-unique +# start-index-unique-collation +theaters.create_index("theaterId", unique=True, collation=Collation(locale='fr_CA')) +# end-index-unique-collation + # start-index-clustered sample_mflix.create_collection("movies", clusteredIndex={ "key": { "_id": 1 }, diff --git a/source/includes/write/delete.py b/source/includes/write/delete.py index 4441785d..8bed6ad4 100644 --- a/source/includes/write/delete.py +++ b/source/includes/write/delete.py @@ -10,6 +10,14 @@ result = restaurants.delete_many(query_filter) # end-delete-many +# start-delete-many-collation +from pymongo.collation import Collation + +query_filter = { "borough": "Brooklyn" } + +result = restaurants.delete_many(query_filter, collation=Collation(locale='fr_CA')) +# end-delete-many-collation + # start-delete-options query_filter = { 'name': {'$regex': 'Mongo' }} diff --git a/source/includes/write/update.py b/source/includes/write/update.py index d94c679a..e1dd7ac9 100644 --- a/source/includes/write/update.py +++ b/source/includes/write/update.py @@ -20,6 +20,20 @@ result = restaurants.update_many(query_filter, update_operation) # end-update-many +# start-update-many-collation +from pymongo.collation import Collation + +restaurants = database["restaurants"] + +query_filter = {'cuisine' : 'Pizza'} +update_operation = { '$set' : + { 'cuisine' : 'Pasta' } +} + +result = restaurants.update_many(query_filter, update_operation, + collation=Collation(locale='fr_CA')) +# end-update-many-collation + # start-update-options restaurants = database["restaurants"] diff --git a/source/indexes.txt b/source/indexes.txt index f57f4d27..3ed60759 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -102,7 +102,7 @@ Create Search Index :language: python :copyable: -To learn more about creating serach indexes, see the :ref:`pymongo-atlas-search-index-create` +To learn more about creating search indexes, see the :ref:`pymongo-atlas-search-index-create` guide. List Search Indexes diff --git a/source/indexes/compound-index.txt b/source/indexes/compound-index.txt index 11d35fa5..78f8836e 100644 --- a/source/indexes/compound-index.txt +++ b/source/indexes/compound-index.txt @@ -50,4 +50,14 @@ the preceding code example: :end-before: end-index-compound-query For more information, see :manual:`Compound Indexes ` in -the {+mdb-server+} manual. \ No newline at end of file +the {+mdb-server+} manual. + +Collation +~~~~~~~~~ + +.. include:: /includes/collation-description-indexes.rst + +.. literalinclude:: /includes/indexes/indexes.py + :language: python + :start-after: start-compound-index-collation + :end-before: end-compound-index-collation \ No newline at end of file diff --git a/source/indexes/geospatial-index.txt b/source/indexes/geospatial-index.txt index 311cb1fc..66d742c0 100644 --- a/source/indexes/geospatial-index.txt +++ b/source/indexes/geospatial-index.txt @@ -75,3 +75,13 @@ MongoDB also supports ``2d`` indexes for calculating distances on a Euclidean pl coordinate pairs" syntax used in MongoDB 2.2 and earlier. For more information, see the :manual:`Geospatial Queries guide ` in the MongoDB Server manual. + +Collation +~~~~~~~~~ + +.. include:: /includes/collation-description-indexes.rst + +.. literalinclude:: /includes/indexes/indexes.py + :language: python + :start-after: start-index-geo-collation + :end-before: end-index-geo-collation diff --git a/source/indexes/multikey-index.txt b/source/indexes/multikey-index.txt index f0980694..3eac056a 100644 --- a/source/indexes/multikey-index.txt +++ b/source/indexes/multikey-index.txt @@ -50,4 +50,14 @@ The following is an example of a query that uses the index created in the preced Multikey indexes behave differently from other indexes in terms of query coverage, index bound computation, and sort behavior. To learn more about multikey indexes, including a discussion of their behavior and limitations, -see the :manual:`Multikey Indexes ` guide in the {+mdb-server+} manual. \ No newline at end of file +see the :manual:`Multikey Indexes ` guide in the {+mdb-server+} manual. + +Collation +~~~~~~~~~ + +.. include:: /includes/collation-description-indexes.rst + +.. literalinclude:: /includes/indexes/indexes.py + :language: python + :start-after: start-index-multikey-collation + :end-before: end-index-multikey-collation \ No newline at end of file diff --git a/source/indexes/single-field-index.txt b/source/indexes/single-field-index.txt index 163d32be..d4da7204 100644 --- a/source/indexes/single-field-index.txt +++ b/source/indexes/single-field-index.txt @@ -57,3 +57,14 @@ The following is an example of a query that is covered by the index created in t To learn more, see :manual:`Single Field Indexes ` in the {+mdb-server+} manual. + +Collation +~~~~~~~~~ + +.. include:: /includes/collation-description-indexes.rst + +.. literalinclude:: /includes/indexes/indexes.py + :start-after: start-index-single-collation + :end-before: end-index-single-collation + :language: python + :copyable: \ No newline at end of file diff --git a/source/indexes/text-index.txt b/source/indexes/text-index.txt index 66b61ab6..1ae00306 100644 --- a/source/indexes/text-index.txt +++ b/source/indexes/text-index.txt @@ -41,7 +41,7 @@ free MongoDB Atlas cluster and load the sample datasets, see the :ref:``. Text Index on a Single Field -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------- The following example creates a text index on the ``plot`` field: @@ -58,8 +58,18 @@ preceding code example: :start-after: start-index-text-single-query :end-before: end-index-text-single-query +Collation +~~~~~~~~~ + +.. include:: /includes/collation-description-indexes.rst + +.. literalinclude:: /includes/indexes/indexes.py + :language: python + :start-after: start-index-text-single-collation + :end-before: end-index-text-single-collation + Text Index on Multiple Fields -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- A collection can contain only one text index. If you want to create a text index for multiple text fields, create a compound diff --git a/source/indexes/unique-index.txt b/source/indexes/unique-index.txt index cbe36d75..fe54765a 100644 --- a/source/indexes/unique-index.txt +++ b/source/indexes/unique-index.txt @@ -48,6 +48,16 @@ The following example creates a descending unique index on the ``theaterId`` fie For more information, see the :manual:`Unique Indexes ` guide in the {+mdb-server+} manual. +Collation +~~~~~~~~~ + +.. include:: /includes/collation-description-indexes.rst + +.. literalinclude:: /includes/indexes/indexes.py + :language: python + :start-after: start-index-unique-collation + :end-before: end-index-unique-collation + Troubleshooting --------------- diff --git a/source/indexes/wildcard-index.txt b/source/indexes/wildcard-index.txt index 32a3893f..a90aa467 100644 --- a/source/indexes/wildcard-index.txt +++ b/source/indexes/wildcard-index.txt @@ -43,4 +43,14 @@ values of the ``location`` field, including values nested in subdocuments and ar :end-before: end-index-wildcard For more information, see the :manual:`Wildcard Indexes` -page in the {+mdb-server+} manual. \ No newline at end of file +page in the {+mdb-server+} manual. + +Collation +~~~~~~~~~ + +.. include:: /includes/collation-description-indexes.rst + +.. literalinclude:: /includes/indexes/indexes.py + :language: python + :start-after: start-index-wildcard-collation + :end-before: end-index-wildcard-collation \ No newline at end of file diff --git a/source/read/retrieve.txt b/source/read/retrieve.txt index ee42f421..ea3434b5 100644 --- a/source/read/retrieve.txt +++ b/source/read/retrieve.txt @@ -141,7 +141,8 @@ named arguments to them. The following table describes the commonly used argumen - | Limits the number of documents to hold in a cursor at a given time. * - ``collation`` - - | An instance of the ``Collation`` class that sets the collation options. + - | The collation options for the find operation. See :ref:`pymongo-retrieve-collation` + for more Information. * - ``comment`` - | A string to attach to the query. This can help you trace and interpret the @@ -168,6 +169,36 @@ For a full list of available arguments, see the `API documentation <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.find>`__ for the ``find() method``. +.. _pymongo-retrieve-collation: + +Collation +````````` + +When you perform a query, you can specify a **collation** for the driver to follow when +sorting the results. + +.. include:: /includes/collation-description.rst + +The following example performs the same find operation as the previous example, +but with a default collation of ``fr_CA``: + +.. code-block:: python + :copyable: true + + cursor = sample_restaurants.restaurants.find({"cuisine": "Italian"}, max_time_ms=10000, + collation=Collation(locale="fr_CA")) + +Alternatively, you can specify a collation by chaining the ``collation()`` method +to the ``find()`` method: + +.. code-block:: python + :copyable: true + + cursor = sample_restaurants.restaurants.find({"cuisine": "Italian"}, max_time_ms=10000) + .collation(Collation(locale="fr_CA") + +.. include:: /includes/collation-override-note.rst + .. _pymongo-retrieve-additional-information: Additional Information diff --git a/source/write/delete.txt b/source/write/delete.txt index 5c12b2fa..b265809b 100644 --- a/source/write/delete.txt +++ b/source/write/delete.txt @@ -100,8 +100,7 @@ the delete operation. * - ``collation`` - | Specifies the kind of language collation to use when sorting - results. For more information, see :manual:`Collation ` - in the {+mdb-server+} manual. + results. See :ref:`pymongo-delete-collation` for more information. * - ``hint`` - | Gets or sets the index to scan for documents. @@ -139,6 +138,27 @@ It also uses the ``comment`` option to add a comment to the operation: ``delete_many()``, the driver would delete only the first document with a ``name`` value that includes ``"Mongo"``. +.. _pymongo-delete-collation: + +Collation +````````` + +When you perform a delete operation, you can specify a **collation** for the driver to +use. + +.. include:: /includes/collation-description.rst + +The following example performs the same delete operation as the previous example, +but with a default collation of ``fr_CA``: + +.. literalinclude:: /includes/write/delete.py + :start-after: start-delete-many-collation + :end-before: end-delete-many-collation + :language: python + :copyable: + +.. include:: /includes/collation-override-note.rst + Return Value ~~~~~~~~~~~~ diff --git a/source/write/update.txt b/source/write/update.txt index 49d7dcce..e9cab858 100644 --- a/source/write/update.txt +++ b/source/write/update.txt @@ -119,8 +119,7 @@ the update operation. * - ``collation`` - | Specifies the kind of language collation to use when sorting - results. For more information, see :manual:`Collation ` - in the {+mdb-server+} manual. + results. See :ref:`pymongo-update-collation` for more information. * - ``array_filters`` - | A list of filters that specifies which array elements an update applies @@ -158,6 +157,27 @@ match any existing documents. :language: python :copyable: +.. _pymongo-update-collation: + +Collation +````````` + +When you perform an update operation, you can specify a **collation** for the driver to +use. + +.. include:: /includes/collation-description.rst + +The following example performs the same update operation as the previous example, +but with a default collation of ``fr_CA``: + +.. literalinclude:: /includes/write/update.py + :start-after: start-update-many-collation + :end-before: end-update-many-collation + :language: python + :copyable: + +.. include:: /includes/collation-override-note.rst + Return Value ~~~~~~~~~~~~