DOCSP-46687 - Collation

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 </core/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
 -------------------------
 

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``: 

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 </reference/collation/>` in the {+mdb-server+} manual.
+
+.. tip:: Import Collation
+
+   To create an instance of the ``Collation`` class, you must import it from
+   ``pymongo.collation``. 

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.

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,17 +55,29 @@
 )
 # 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" } }
 
 cursor = movies.find(query)
 # 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 }, 

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' }}
 

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"]
 

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

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 </core/index-compound>` in
-the {+mdb-server+} manual.
+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

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 </geospatial-queries>` 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