diff --git a/source/crud/delete.txt b/source/crud/delete.txt index 2dd0cec1..437ad491 100644 --- a/source/crud/delete.txt +++ b/source/crud/delete.txt @@ -101,8 +101,8 @@ options you can set in the array: * - ``collation`` - | Specifies the kind of language collation to use when comparing - strings. For more information, see :manual:`Collation ` - in the {+mdb-server+} manual. + strings. To learn more, see the :ref:`php-delete-collation` section + of this page. * - ``writeConcern`` - | Sets the write concern for the operation. This option defaults to @@ -132,6 +132,13 @@ options you can set in the array: fields ` guide in the {+mdb-server+} manual. +.. _php-delete-collation: + +Collation +~~~~~~~~~ + +.. include:: /includes/collation.rst + Example ~~~~~~~ diff --git a/source/crud/query/count.txt b/source/crud/query/count.txt index 19765deb..59e3dd65 100644 --- a/source/crud/query/count.txt +++ b/source/crud/query/count.txt @@ -120,7 +120,8 @@ describes some options you can set to customize the count operation: - Description * - ``collation`` - - | The collation to use for the operation. + - | The collation to use for the operation. To learn more, + see the :ref:`php-count-collation` section of this page. | **Type**: ``array|object`` * - ``hint`` @@ -166,6 +167,13 @@ operation to count a maximum of ``100`` results: Number of companies with 50 employees: 100 +.. _php-count-collation: + +Collation +````````` + +.. include:: /includes/collation.rst + .. _php-estimated-count: Retrieve an Estimated Count diff --git a/source/crud/query/distinct.txt b/source/crud/query/distinct.txt index 8a71ca01..90f99960 100644 --- a/source/crud/query/distinct.txt +++ b/source/crud/query/distinct.txt @@ -123,7 +123,8 @@ options you can set to customize the operation: - Description * - ``collation`` - - | The collation to use for the operation. + - | The collation to use for the operation. To learn more, see the + :ref:`php-distinct-collation` section of this page. | **Type**: ``array|object`` * - ``maxTimeMS`` @@ -169,6 +170,13 @@ in an options array to add a comment to the operation: "Angie'S Cafe Pizza" ... +.. _php-distinct-collation: + +Collation +````````` + +.. include:: /includes/collation.rst + API Documentation ----------------- diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt index 4e76dff1..755e3a4f 100644 --- a/source/crud/query/retrieve.txt +++ b/source/crud/query/retrieve.txt @@ -190,7 +190,8 @@ you can set in the array: * - ``collation`` - | The collation to use for the operation. The default value is the collation - specified for the collection. + specified for the collection. To learn more, see the :ref:`php-retrieve-collation` + section of this page. | **Type**: ``array|object`` * - ``comment`` @@ -233,6 +234,13 @@ For a full list of options, see the API documentation for the `findOne() <{+api+}/method/MongoDBCollection-findOne/#parameters>`__ and `find() <{+api+}/method/MongoDBCollection-find/#parameters>`__ parameters. +.. _php-retrieve-collation: + +Collation +````````` + +.. include:: /includes/collation.rst + .. _php-retrieve-additional-information: Additional Information diff --git a/source/crud/replace.txt b/source/crud/replace.txt index 5c3ba370..b277192d 100644 --- a/source/crud/replace.txt +++ b/source/crud/replace.txt @@ -159,8 +159,8 @@ table describes some options you can set in the array: * - ``collation`` - | Specifies the kind of language collation to use when sorting - results. For more information, see :manual:`Collation ` - in the {+mdb-server+} manual. + results. To learn more, see the :ref:`php-replace-collation` + section of this page. * - ``hint`` - | Gets or sets the index to scan for documents. @@ -182,6 +182,13 @@ table describes some options you can set in the array: fields ` guide in the {+mdb-server+} manual. +.. _php-replace-collation: + +Collation +~~~~~~~~~ + +.. include:: /includes/collation.rst + Example ~~~~~~~ diff --git a/source/crud/update.txt b/source/crud/update.txt index b6e22d02..103e6ce1 100644 --- a/source/crud/update.txt +++ b/source/crud/update.txt @@ -125,8 +125,8 @@ describes some options you can set in the array: * - ``collation`` - | Specifies the kind of language collation to use when sorting - results. For more information, see :manual:`Collation ` - in the {+mdb-server+} manual. + results. To learn more, see the :ref:`php-update-collation` section + of this page. * - ``arrayFilters`` - | Specifies which array elements an update applies to if the operation modifies @@ -166,6 +166,13 @@ match any existing documents. :language: php :dedent: +.. _php-update-collation: + +Collation +````````` + +.. include:: /includes/collation.rst + Return Value ~~~~~~~~~~~~ diff --git a/source/includes/collation.rst b/source/includes/collation.rst new file mode 100644 index 00000000..bed2508b --- /dev/null +++ b/source/includes/collation.rst @@ -0,0 +1,97 @@ +To specify a collation for your operation, pass an ``$options`` array +parameter that sets the ``collation`` option to the operation method. +Assign the ``collation`` option to an array that configures the collation +rules. + +The following table describes the fields you can set to configure +the collation: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Field + - Description + + * - ``locale`` + - | *(Required)* Specifies the International Components for Unicode (ICU) locale. For a + list of supported locales, see :manual:`Collation Locales and Default Parameters + ` + in the {+mdb-server+} manual. + | + | **Data Type**: {+string-data-type+} + + * - ``caseLevel`` + - | *(Optional)* Specifies whether to include case comparison. + | + | When set to ``true``, the comparison behavior depends on the value of + the ``strength`` field: + | + | - If ``strength`` is ``1``, the {+library-short+} compares base + | characters and case. + | + | - If ``strength`` is ``2``, the {+library-short+} compares base + | characters, diacritics, other secondary differences, and case. + | + | - If ``strength`` is any other value, this field is ignored. + | + | When set to ``false``, the {+library-short+} doesn't include case comparison at + strength level ``1`` or ``2``. + | + | **Data Type**: {+bool-data-type+} + | **Default**: ``false`` + + * - ``caseFirst`` + - | *(Optional)* Specifies the sort order of case differences during tertiary + level comparisons. + | + | **Data Type**: {+string-data-type+} + | **Default**: ``"off"`` + + * - ``strength`` + - | *(Optional)* Specifies the level of comparison to perform, as defined in the + `ICU documentation `__. + | + | **Data Type**: {+int-data-type+} + | **Default**: ``3`` + + * - ``numericOrdering`` + - | *(Optional)* Specifies whether the driver compares numeric strings as numbers. + | + | If set to ``true``, the {+library-short+} compares numeric strings as numbers. + For example, when comparing the strings "10" and "2", the library uses the + strings' numeric values and treats "10" as greater than "2". + | + | If set to ``false``, the {+library-short+} compares numeric strings + as strings. For example, when comparing the strings "10" and "2", the library + compares one character at a time and treats "10" as less than "2". + | + | For more information, see :manual:`Collation Restrictions ` + in the {+mdb-server+} manual. + | + | **Data Type**: {+bool-data-type+} + | **Default**: ``false`` + + * - ``alternate`` + - | *(Optional)* Specifies whether the library considers whitespace and punctuation as base + characters for comparison purposes. + | + | **Data Type**: {+string-data-type+} + | **Default**: ``"non-ignorable"`` + + * - ``maxVariable`` + - | *(Optional)* Specifies which characters the library considers ignorable when + the ``alternate`` field is set to ``"shifted"``. + | + | **Data Type**: {+string-data-type+} + | **Default**: ``"punct"`` + + * - ``backwards`` + - | *(Optional)* Specifies whether strings containing diacritics sort from the back of the string + to the front. + | + | **Data Type**: {+bool-data-type+} + | **Default**: ``false`` + +To learn more about collation and the possible values for each field, see the :manual:`Collation ` +entry in the {+mdb-server+} manual. \ No newline at end of file diff --git a/source/monitoring-logging/change-streams.txt b/source/monitoring-logging/change-streams.txt index 35cf9f5a..c1256474 100644 --- a/source/monitoring-logging/change-streams.txt +++ b/source/monitoring-logging/change-streams.txt @@ -174,7 +174,8 @@ can set in the array: | This option is mutually exclusive with ``startAfter`` and ``resumeAfter``. * - ``collation`` - - | Sets the collation to use for the change stream cursor. + - | Sets the collation to use for the change stream cursor. To learn more, + see the :ref:`php-change-stream-collation` section of this page. For a full list of ``watch()`` options, see `MongoDB\\Collection::watch() <{+api+}/method/MongoDBCollection-watch/>`__ in the API @@ -255,6 +256,13 @@ output: :manual:`Change Streams with Document Pre- and Post-Images ` in the {+mdb-server+} manual. +.. _php-change-stream-collation: + +Collation +~~~~~~~~~ + +.. include:: /includes/collation.rst + Additional Information ----------------------