Skip to content

DOCSP-49849 - Collation #628

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
May 22, 2025
Merged

DOCSP-49849 - Collation #628

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
eef3229
first draft
mongoKart May 7, 2025
02a59e2
table fixes
mongoKart May 7, 2025
169591e
fixes
mongoKart May 7, 2025
ed9d6bc
rm review
mongoKart May 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 12 additions & 8 deletions source/crud/bulk-write.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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``
Expand Down Expand Up @@ -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``
Expand Down Expand Up @@ -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``
Expand Down Expand Up @@ -470,6 +467,13 @@ a delete operation:
:copyable:
:dedent: 8

.. _csharp-bulk-write-collation:

Collation
~~~~~~~~~

.. include:: /includes/collation.rst

Return Value
------------

Expand Down
12 changes: 9 additions & 3 deletions source/crud/delete.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -158,6 +157,13 @@ following properties:
fields</reference/command/delete/#command-fields>`
for more information.

.. _csharp-delete-collation:

Collation
~~~~~~~~~

.. include:: /includes/collation.rst

Example
~~~~~~~

Expand Down
10 changes: 9 additions & 1 deletion source/crud/query/count.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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``
Expand Down Expand Up @@ -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
Expand Down
11 changes: 10 additions & 1 deletion source/crud/query/distinct.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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``
Expand Down Expand Up @@ -249,6 +251,13 @@ corresponding code.
Angie'S Cafe Pizza
...

.. _csharp-distinct-collation:

Collation
~~~~~~~~~

.. include:: /includes/collation.rst

API Documentation
-----------------

Expand Down
10 changes: 9 additions & 1 deletion source/crud/query/find.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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
~~~~~~~

Expand Down
11 changes: 9 additions & 2 deletions source/crud/replace.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`__

Expand Down Expand Up @@ -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
~~~~~~~~~~~~

Expand Down
110 changes: 110 additions & 0 deletions source/includes/collation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
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``

* - ``alternate``
- | Optional. Specifies whether the driver considers whitespace and punctuation as base
Copy link
Collaborator

@rachel-mack rachel-mack May 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The other table in this doc set uses italics for *Optional.*, but the style guide uses (*Optional)*
I'll leave it up to you.

characters for purposes of comparison.
Copy link
Collaborator

@rachel-mack rachel-mack May 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add an **Accepted Values:** section

Copy link
Collaborator Author

@mongoKart mongoKart May 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For all of the C# enum data types, I linked to the relevant API page, which documents the possible options. Similar for the string types linking to a page with the accepted options.

|
| **Data Type**: `CollationAlternate <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollationAlternate.html>`__
| **Default**: ``CollationAlternate.NonIgnorable`` (spaces and punctuation are
considered base characters)
- ``Alternate``

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

* - ``caseFirst``
- | Optional. Specifies the sort order of case differences during tertiary level comparisons.
Copy link
Collaborator

@rachel-mack rachel-mack May 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

**Accepted Values:**

Copy link
Collaborator Author

@mongoKart mongoKart May 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

see above

|
| **Data Type**: `CollationCaseFirst <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollationCaseFirst.html>`__
| **Default**: ``CollationCaseFirst.Off``
- ``CaseFirst``

* - ``caseLevel``
- | Optional. Specifies whether to include case comparison at strength level ``Primary`` or
``Secondary``.
|
| When this argument is ``true``:
|
| - If the strength is ``Primary``, the driver compares base
characters and case.
| - If the strength is ``Secondary``, the driver compares base
characters, diacritics, other secondary differences, and case.
|
| When this argument is ``false``, the driver doesn't include case comparison at
strength level ``Primary`` or ``Secondary``.
Copy link
Collaborator

@rachel-mack rachel-mack May 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If there's a way to add a link to the strength parameter, I would do that here. I'm assuming this is why you were asking about nesting tables the other day, because that would make sense here.

Suggested change
- | Optional. Specifies whether to include case comparison at strength level ``Primary`` or
``Secondary``.
|
| When this argument is ``true``:
|
| - If the strength is ``Primary``, the driver compares base
characters and case.
| - If the strength is ``Secondary``, the driver compares base
characters, diacritics, other secondary differences, and case.
|
| When this argument is ``false``, the driver doesn't include case comparison at
strength level ``Primary`` or ``Secondary``.
- | Optional. Specifies whether to include case comparison.
|
| When this argument is ``true``, the behaviour depends on the value of the ``Strength`` property:
|
| - If the ``Strength`` property is ``Primary``, the driver compares base
characters and case.
| - If the ``Strength`` property is ``Secondary``, the driver compares base
characters, diacritics, other secondary differences, and case.
|
| When this argument is ``false``, the driver doesn't include case comparison.

Copy link
Collaborator Author

@mongoKart mongoKart May 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know of a way to link to another table row. I could move strength above caseLevel but I just moved them to parameter order and that would throw it off.

a note about the properties: they're read-only and set directly by these parameters, so i talk about the values of the parameters instead of the values of the properties.

|
| **Data Type**: {+bool-data-type+}
| **Default**: ``false``
- ``CaseLevel``

* - ``maxVariable``
- | Optional. Specifies which characters the driver considers ignorable when
``Alternate`` is ``CollationAlternate.Shifted``.
Copy link
Collaborator

@rachel-mack rachel-mack May 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add **Accepted Values:**

Suggested change
- | Optional. Specifies which characters the driver considers ignorable when
``Alternate`` is ``CollationAlternate.Shifted``.
- | Optional. Specifies which characters the driver considers ignorable when the
``Alternate`` property 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.
Copy link
Collaborator

@rachel-mack rachel-mack May 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add an example

Copy link
Collaborator Author

@mongoKart mongoKart May 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

how about a link to the ICU docs

|
| Most text doesn't require normalization.
|
| **Data Type**: {+bool-data-type+}
| **Default**: ``false``
- ``Normalization``

* - ``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, "10" is greater than "2". If this argument is ``false`` or excluded,
the driver compares numeric strings as strings. For example, "10" is less than "2".
Copy link
Collaborator

@rachel-mack rachel-mack May 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They're not being treated as strings so I would leave out the "s, you could make them 10 and 2 if you want to differentiate them:

Suggested change
| If this argument is ``true``, the driver compares numeric strings as numbers.
For example, "10" is greater than "2". If this argument is ``false`` or excluded,
the driver compares numeric strings as strings. For example, "10" is less than "2".
| If this argument is ``true``, the driver compares numeric strings as numbers.
For example, 10 is greater than 2.
|
| If this argument is ``false`` or excluded,
the driver compares numeric strings as strings. For example, "10" is less than "2".

Copy link
Collaborator Author

@mongoKart mongoKart May 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

they aren't being compared as strings, but they still are strings, so i think the quotes are useful. lmk if this change is clearer.

|
| For more information, see :manual:`Collation Restrictions </reference/collation/#restrictions>`
in the {+mdb-server+} manual.
|
| **Data Type**: {+bool-data-type+}
| **Default**: ``false``
- ``NumericOrdering``

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

For more information about collation, see the :manual:`Collation <reference/collation>`
page in the {+mdb-server+} manual.
Copy link
Collaborator

@rachel-mack rachel-mack May 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

404

Suggested change
For more information about collation, see the :manual:`Collation <reference/collation>`
page in the {+mdb-server+} manual.
For more information about collation, see the :manual:`Collation </reference/collation>`
page in the {+mdb-server+} manual.

11 changes: 9 additions & 2 deletions source/includes/page-templates/update/update.rst
View file
Open in desktop
Copy link
Collaborator

@rachel-mack rachel-mack May 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this still being used?

Copy link
Collaborator Author

@mongoKart mongoKart May 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah, it's the page template for update-many and update-one

Original file line number Diff line number Diff line change
Expand Up @@ -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>`__

Expand Down Expand Up @@ -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
------------

Expand Down
10 changes: 9 additions & 1 deletion source/logging-and-monitoring/change-streams.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading