DOCSP-49849 - Collation (#628)

mongoKart · web-flow · commit e45e0335c684 · 2025-05-22T09:00:39.000-05:00
diff --git a/source/crud/bulk-write.txt b/source/crud/bulk-write.txt
@@ -133,8 +133,7 @@ parameters:
 
    * - ``collation``
      - | *Optional.* The language collation to use when sorting results. See the
-         :manual:`{+mdb+server+} manual</reference/command/delete/#std-label-deletes-array-collation>`
-         for more information.
+         :ref:`<csharp-bulk-write-collation>` section of this page for more information.
        |
        | **Data Type:** `Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Collation.html>`__
        | **Default:** ``null``
@@ -228,9 +227,8 @@ constructor accepts the following parameters:
        | **Data Type:** ``TDocument``
 
    * - ``collation``
-     - | *Optional.* The language collation to use when sorting results. See
-         the :manual:`{+mdb-server+} manual</reference/command/delete/#std-label-deletes-array-collation>`
-         for more information.
+     - | *Optional.* The language collation to use when sorting results. See the
+         :ref:`<csharp-bulk-write-collation>` section of this page for more information.
        |
        | **Data Type:** `Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Collation.html>`__
        | **Default:** ``null``
@@ -298,9 +296,8 @@ parameters:
        | **Data Type:** `FilterDefinition<TDocument> <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FilterDefinition-1.html>`__
 
    * - ``collation``
-     - | *Optional.* The language collation to use when sorting results. See
-         the :manual:`{+mdb-server+} manual</reference/command/delete/#std-label-deletes-array-collation>`
-         for more information.
+     - | *Optional.* The language collation to use when sorting results. See the
+         :ref:`<csharp-bulk-write-collation>` section of this page for more information.
        |
        | **Data Type:** `Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Collation.html>`__
        | **Default:** ``null``
@@ -470,6 +467,13 @@ a delete operation:
         :copyable:
         :dedent: 8
 
+.. _csharp-bulk-write-collation:
+
+Collation
+~~~~~~~~~
+
+.. include:: /includes/collation.rst
+
 Return Value
 ------------
 
diff --git a/source/crud/delete.txt b/source/crud/delete.txt
@@ -139,9 +139,8 @@ following properties:
 
    * - ``Collation``
      - | Gets or sets the type of language collation to use when sorting
-         results. See :manual:`the delete
-         statements</reference/command/delete/#std-label-deletes-array-collation>`
-         for more information.
+         results. See the :ref:`<csharp-delete-collation>` section of this page for more
+         information.
 
    * - ``Comment``
      - | Gets or sets the comment for the operation. See :manual:`the delete command
@@ -158,6 +157,13 @@ following properties:
          fields</reference/command/delete/#command-fields>`
          for more information.
 
+.. _csharp-delete-collation:
+
+Collation
+~~~~~~~~~
+
+.. include:: /includes/collation.rst
+
 Example
 ~~~~~~~
 
diff --git a/source/crud/query/count.txt b/source/crud/query/count.txt
@@ -98,7 +98,8 @@ You can set the following properties in a ``CountOptions`` object:
      - Description
 
    * - ``Collation``
-     - | The type of language collation to use when sorting results.  
+     - | The type of language collation to use when sorting results. See the
+         :ref:`<csharp-count-collation>` section of this page for more information. 
        | Default: ``null``
 
    * - ``Hint`` 
@@ -132,6 +133,13 @@ You can set the following properties in a ``CountOptions`` object:
       CountOptions opts = new CountOptions(){Hint = "_id_"};
       var count = collection.CountDocuments(filter, opts);
 
+.. _csharp-count-collation:
+
+Collation
+~~~~~~~~~
+
+.. include:: /includes/collation.rst
+
 .. _csharp-estimated-count:
 
 Estimated Count
diff --git a/source/crud/query/distinct.txt b/source/crud/query/distinct.txt
@@ -180,7 +180,9 @@ describes the properties you can set on a ``DistinctOptions`` instance:
      - Description
 
    * - ``Collation`` 
-     - | Sets the collation to use for the operation.
+     - | Sets the collation to use for the operation. See the
+         :ref:`<csharp-distinct-collation>` section of this page for more information. 
+       | Default: ``null``
        | **Data type**: `Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.DistinctOptions.Collation.html>`__
 
    * - ``MaxTime``
@@ -249,6 +251,13 @@ corresponding code.
             Angie'S Cafe Pizza
             ...
 
+.. _csharp-distinct-collation:
+
+Collation
+~~~~~~~~~
+
+.. include:: /includes/collation.rst
+
 API Documentation
 -----------------
 
diff --git a/source/crud/query/find.txt b/source/crud/query/find.txt
@@ -208,7 +208,8 @@ You can configure the commonly used options with the following methods:
      - | Gets or sets the number of documents to hold in a cursor at a given time.
 
    * - ``Collation`` 
-     - | Sets the collation options. 
+     - | Sets the collation options. See the
+         :ref:`<csharp-find-collation>` section of this page for more information.
 
    * - ``Comment`` 
      - | Sets the comment to the query. To learn more about query comments, 
@@ -223,6 +224,13 @@ You can configure the commonly used options with the following methods:
 To see a full list of available options, see 
 `FindOptions Properties <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FindOptions.html>`__.
 
+.. _csharp-find-collation:
+
+Collation
+~~~~~~~~~
+
+.. include:: /includes/collation.rst
+
 Example
 ~~~~~~~
 
diff --git a/source/crud/replace.txt b/source/crud/replace.txt
@@ -138,8 +138,8 @@ The ``ReplaceOptions`` class contains the following properties:
 
    * - ``Collation``
      - Specifies the kind of language collation to use when sorting
-       results. See :manual:`the {+mdb-server+} manual </reference/collation/#std-label-collation>`
-       for more information on collation.
+       results. See the :ref:`<csharp-replace-collation>` section of this page for more
+       information.
 
        **Data Type:** `Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Collation.html>`__
 
@@ -199,6 +199,13 @@ code.
          :start-after: // start-replace-one-async-with-options
          :end-before: // end-replace-one-async-with-options
 
+.. _csharp-replace-collation:
+
+Collation
+~~~~~~~~~
+
+.. include:: /includes/collation.rst
+
 Return Value
 ~~~~~~~~~~~~
 
diff --git a/source/includes/collation.rst b/source/includes/collation.rst
@@ -0,0 +1,117 @@
+To configure collation for your operation, create an instance of the
+`Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Collation.html>`__ class.
+
+The following table describes the parameters that the ``Collation`` constructor accepts.
+It also lists the corresponding class property that you can use to read each
+setting's value.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 60 20
+
+   * - Parameter
+     - Description
+     - Class Property
+
+   * - ``locale``
+     - | Specifies the International Components for Unicode (ICU) locale. For a list of
+         supported locales,
+         see :manual:`Collation Locales and Default Parameters </reference/collation-locales-defaults/#supported-languages-and-locales>`
+         in the {+mdb-server+} Manual.
+       |
+       | If you want to use simple binary comparison, use the ``Collation.Simple`` static
+         property to return a ``Collation`` object with the ``locale`` set to ``"simple"``.
+       | **Data Type**: {+string-data-type+} 
+     - ``Locale`` 
+
+   * - ``caseLevel``
+     - | *(Optional)* Specifies whether to include case comparison.
+       |
+       | When this argument is ``true``, the driver's behavior depends on the value of
+         the ``strength`` argument:
+       |
+       | - If ``strength`` is ``CollationStrength.Primary``, the driver compares base
+           characters and case.
+       | - If ``strength`` is ``CollationStrength.Secondary``, the driver compares base
+           characters, diacritics, other secondary differences, and case.
+       | - If ``strength`` is any other value, this argument is ignored.
+       |
+       | When this argument is ``false``, the driver doesn't include case comparison at
+         strength level ``Primary`` or ``Secondary``.
+       |
+       | **Data Type**: {+bool-data-type+} 
+       | **Default**: ``false``
+     - ``CaseLevel``
+
+   * - ``caseFirst``
+     - | *(Optional)* Specifies the sort order of case differences during tertiary level comparisons.
+       |
+       | **Data Type**: `CollationCaseFirst <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollationCaseFirst.html>`__
+       | **Default**: ``CollationCaseFirst.Off``
+     - ``CaseFirst``
+
+   * - ``strength``
+     - | *(Optional)* Specifies the level of comparison to perform, as defined in the
+         `ICU documentation <https://unicode-org.github.io/icu/userguide/collation/concepts.html#comparison-levels>`__.
+       |
+       | **Data Type**: `CollationStrength <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollationStrength.html>`__
+       | **Default**: ``CollationStrength.Tertiary``
+     - ``Strength``
+
+   * - ``numericOrdering``
+     - | *(Optional)* Specifies whether the driver compares numeric strings as numbers.
+       | 
+       | If this argument is ``true``, the driver compares numeric strings as numbers.
+         For example, when comparing the strings "10" and "2", the driver treats the values
+         as 10 and 2, and finds 10 to be greater.
+       |  
+       | If this argument is ``false`` or excluded, the driver compares numeric strings
+         as strings. For example, when comparing the strings "10" and "2", the driver
+         compares one character at a time. Because "1" is less than "2", the driver finds
+         "10" to be less than "2".
+       |
+       | For more information, see :manual:`Collation Restrictions </reference/collation/#restrictions>`
+         in the {+mdb-server+} manual.
+       |
+       | **Data Type**: {+bool-data-type+}
+       | **Default**: ``false``
+     - ``NumericOrdering``
+
+   * - ``alternate``
+     - | *(Optional)* Specifies whether the driver considers whitespace and punctuation as base
+         characters for purposes of comparison.
+       |
+       | **Data Type**: `CollationAlternate <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollationAlternate.html>`__
+       | **Default**: ``CollationAlternate.NonIgnorable`` (spaces and punctuation are
+         considered base characters)
+     - ``Alternate``
+
+   * - ``maxVariable``
+     - | *(Optional)* Specifies which characters the driver considers ignorable when
+         the ``alternate`` argument is ``CollationAlternate.Shifted``.
+       |
+       | **Data Type**: `CollationMaxVariable <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollationMaxVariable.html>`__ 
+       | **Default**: ``CollationMaxVariable.Punctuation`` (the driver ignores punctuation
+         and spaces)
+     - ``MaxVariable``
+   
+   * - ``normalization``
+     - | *(Optional)* Specifies whether the driver normalizes text as needed.
+       |
+       | Most text doesn't require normalization. For more information about
+         normalization, see the `ICU documentation <https://unicode-org.github.io/icu/userguide/collation/concepts.html#normalization>`__.
+       |
+       | **Data Type**: {+bool-data-type+}
+       | **Default**: ``false``
+     - ``Normalization``
+
+   * - ``backwards``
+     - | *(Optional)* Specifies whether strings containing diacritics sort from the back of the string
+         to the front.
+       |
+       | **Data Type**: {+bool-data-type+} 
+       | **Default**: ``false``
+     - ``Backwards``
+
+For more information about collation, see the :manual:`Collation </reference/collation>`
+page in the {+mdb-server+} manual.
diff --git a/source/includes/page-templates/update/update.rst b/source/includes/page-templates/update/update.rst
@@ -165,8 +165,8 @@ The ``UpdateOptions`` class contains the following properties:
 
    * - ``Collation``
      - Specifies the kind of language collation to use when sorting
-       results. See :manual:`the {+mdb-server+} manual</reference/collation/#std-label-collation>`
-       for more information on collation.
+       results. See the
+       :ref:`<csharp-find-collation>` section of this page for more information.
 
        **Data Type:** `Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Collation.html>`__
 
@@ -199,6 +199,13 @@ The ``UpdateOptions`` class contains the following properties:
 
        **Data Type:** `BsonDocument <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonDocument.html>`__
 
+.. _csharp-update-collation:
+
+Collation
+~~~~~~~~~
+
+.. include:: /includes/collation.rst
+
 Return Value
 ------------
 
diff --git a/source/logging-and-monitoring/change-streams.txt b/source/logging-and-monitoring/change-streams.txt
@@ -289,11 +289,19 @@ of ``Watch()`` and ``WatchAsync()``:
          response from the MongoDB cluster.
 
    * - ``Collation``
-     - | Specifies the collation to use for the change stream cursor.
+     - | Specifies the collation to use for the change stream cursor. See the
+         :ref:`<csharp-change-stream-collation>` section of this page for more information.
 
    * - ``Comment``
      - | Attaches a comment to the operation.
 
+.. _csharp-change-stream-collation:
+
+Collation
+~~~~~~~~~
+
+.. include:: /includes/collation.rst
+
 .. _csharp-change-stream-pre-post-image:
 
 Include Pre-Images and Post-Images
