Skip to content

Commit 96655ab

Browse files
authored
DOCSP-47055: Collation (#258)
* DOCSP-47055: Collation * add to each page * edit * edits * list format * SA feedback
1 parent 09d6e1b commit 96655ab

File tree

8 files changed

+160
-10
lines changed

8 files changed

+160
-10
lines changed

source/crud/delete.txt

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -101,8 +101,8 @@ options you can set in the array:
101101

102102
* - ``collation``
103103
- | Specifies the kind of language collation to use when comparing
104-
strings. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`
105-
in the {+mdb-server+} manual.
104+
strings. To learn more, see the :ref:`php-delete-collation` section
105+
of this page.
106106

107107
* - ``writeConcern``
108108
- | Sets the write concern for the operation. This option defaults to
@@ -132,6 +132,13 @@ options you can set in the array:
132132
fields </reference/command/delete/#command-fields>` guide in the
133133
{+mdb-server+} manual.
134134

135+
.. _php-delete-collation:
136+
137+
Collation
138+
~~~~~~~~~
139+
140+
.. include:: /includes/collation.rst
141+
135142
Example
136143
~~~~~~~
137144

source/crud/query/count.txt

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,8 @@ describes some options you can set to customize the count operation:
120120
- Description
121121

122122
* - ``collation``
123-
- | The collation to use for the operation.
123+
- | The collation to use for the operation. To learn more,
124+
see the :ref:`php-count-collation` section of this page.
124125
| **Type**: ``array|object``
125126

126127
* - ``hint``
@@ -166,6 +167,13 @@ operation to count a maximum of ``100`` results:
166167

167168
Number of companies with 50 employees: 100
168169

170+
.. _php-count-collation:
171+
172+
Collation
173+
`````````
174+
175+
.. include:: /includes/collation.rst
176+
169177
.. _php-estimated-count:
170178

171179
Retrieve an Estimated Count

source/crud/query/distinct.txt

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,8 @@ options you can set to customize the operation:
123123
- Description
124124

125125
* - ``collation``
126-
- | The collation to use for the operation.
126+
- | The collation to use for the operation. To learn more, see the
127+
:ref:`php-distinct-collation` section of this page.
127128
| **Type**: ``array|object``
128129

129130
* - ``maxTimeMS``
@@ -169,6 +170,13 @@ in an options array to add a comment to the operation:
169170
"Angie'S Cafe Pizza"
170171
...
171172

173+
.. _php-distinct-collation:
174+
175+
Collation
176+
`````````
177+
178+
.. include:: /includes/collation.rst
179+
172180
API Documentation
173181
-----------------
174182

source/crud/query/retrieve.txt

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,8 @@ you can set in the array:
190190

191191
* - ``collation``
192192
- | The collation to use for the operation. The default value is the collation
193-
specified for the collection.
193+
specified for the collection. To learn more, see the :ref:`php-retrieve-collation`
194+
section of this page.
194195
| **Type**: ``array|object``
195196

196197
* - ``comment``
@@ -233,6 +234,13 @@ For a full list of options, see the API documentation for the
233234
`findOne() <{+api+}/method/MongoDBCollection-findOne/#parameters>`__ and
234235
`find() <{+api+}/method/MongoDBCollection-find/#parameters>`__ parameters.
235236

237+
.. _php-retrieve-collation:
238+
239+
Collation
240+
`````````
241+
242+
.. include:: /includes/collation.rst
243+
236244
.. _php-retrieve-additional-information:
237245

238246
Additional Information

source/crud/replace.txt

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -159,8 +159,8 @@ table describes some options you can set in the array:
159159

160160
* - ``collation``
161161
- | Specifies the kind of language collation to use when sorting
162-
results. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`
163-
in the {+mdb-server+} manual.
162+
results. To learn more, see the :ref:`php-replace-collation`
163+
section of this page.
164164

165165
* - ``hint``
166166
- | Gets or sets the index to scan for documents.
@@ -182,6 +182,13 @@ table describes some options you can set in the array:
182182
fields </reference/command/insert/#command-fields>` guide in the
183183
{+mdb-server+} manual.
184184

185+
.. _php-replace-collation:
186+
187+
Collation
188+
~~~~~~~~~
189+
190+
.. include:: /includes/collation.rst
191+
185192
Example
186193
~~~~~~~
187194

source/crud/update.txt

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -125,8 +125,8 @@ describes some options you can set in the array:
125125

126126
* - ``collation``
127127
- | Specifies the kind of language collation to use when sorting
128-
results. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`
129-
in the {+mdb-server+} manual.
128+
results. To learn more, see the :ref:`php-update-collation` section
129+
of this page.
130130

131131
* - ``arrayFilters``
132132
- | Specifies which array elements an update applies to if the operation modifies
@@ -166,6 +166,13 @@ match any existing documents.
166166
:language: php
167167
:dedent:
168168

169+
.. _php-update-collation:
170+
171+
Collation
172+
`````````
173+
174+
.. include:: /includes/collation.rst
175+
169176
Return Value
170177
~~~~~~~~~~~~
171178

source/includes/collation.rst

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
To specify a collation for your operation, pass an ``$options`` array
2+
parameter that sets the ``collation`` option to the operation method.
3+
Assign the ``collation`` option to an array that configures the collation
4+
rules.
5+
6+
The following table describes the fields you can set to configure
7+
the collation:
8+
9+
.. list-table::
10+
:widths: 30 70
11+
:header-rows: 1
12+
13+
* - Field
14+
- Description
15+
16+
* - ``locale``
17+
- | *(Required)* Specifies the International Components for Unicode (ICU) locale. For a
18+
list of supported locales, see :manual:`Collation Locales and Default Parameters
19+
</reference/collation-locales-defaults/#supported-languages-and-locales>`
20+
in the {+mdb-server+} manual.
21+
|
22+
| **Data Type**: {+string-data-type+}
23+
24+
* - ``caseLevel``
25+
- | *(Optional)* Specifies whether to include case comparison.
26+
|
27+
| When set to ``true``, the comparison behavior depends on the value of
28+
the ``strength`` field:
29+
|
30+
| - If ``strength`` is ``1``, the {+library-short+} compares base
31+
| characters and case.
32+
|
33+
| - If ``strength`` is ``2``, the {+library-short+} compares base
34+
| characters, diacritics, other secondary differences, and case.
35+
|
36+
| - If ``strength`` is any other value, this field is ignored.
37+
|
38+
| When set to ``false``, the {+library-short+} doesn't include case comparison at
39+
strength level ``1`` or ``2``.
40+
|
41+
| **Data Type**: {+bool-data-type+}
42+
| **Default**: ``false``
43+
44+
* - ``caseFirst``
45+
- | *(Optional)* Specifies the sort order of case differences during tertiary
46+
level comparisons.
47+
|
48+
| **Data Type**: {+string-data-type+}
49+
| **Default**: ``"off"``
50+
51+
* - ``strength``
52+
- | *(Optional)* Specifies the level of comparison to perform, as defined in the
53+
`ICU documentation <https://unicode-org.github.io/icu/userguide/collation/concepts.html#comparison-levels>`__.
54+
|
55+
| **Data Type**: {+int-data-type+}
56+
| **Default**: ``3``
57+
58+
* - ``numericOrdering``
59+
- | *(Optional)* Specifies whether the driver compares numeric strings as numbers.
60+
|
61+
| If set to ``true``, the {+library-short+} compares numeric strings as numbers.
62+
For example, when comparing the strings "10" and "2", the library uses the
63+
strings' numeric values and treats "10" as greater than "2".
64+
|
65+
| If set to ``false``, the {+library-short+} compares numeric strings
66+
as strings. For example, when comparing the strings "10" and "2", the library
67+
compares one character at a time and treats "10" as less than "2".
68+
|
69+
| For more information, see :manual:`Collation Restrictions </reference/collation/#restrictions>`
70+
in the {+mdb-server+} manual.
71+
|
72+
| **Data Type**: {+bool-data-type+}
73+
| **Default**: ``false``
74+
75+
* - ``alternate``
76+
- | *(Optional)* Specifies whether the library considers whitespace and punctuation as base
77+
characters for comparison purposes.
78+
|
79+
| **Data Type**: {+string-data-type+}
80+
| **Default**: ``"non-ignorable"``
81+
82+
* - ``maxVariable``
83+
- | *(Optional)* Specifies which characters the library considers ignorable when
84+
the ``alternate`` field is set to ``"shifted"``.
85+
|
86+
| **Data Type**: {+string-data-type+}
87+
| **Default**: ``"punct"``
88+
89+
* - ``backwards``
90+
- | *(Optional)* Specifies whether strings containing diacritics sort from the back of the string
91+
to the front.
92+
|
93+
| **Data Type**: {+bool-data-type+}
94+
| **Default**: ``false``
95+
96+
To learn more about collation and the possible values for each field, see the :manual:`Collation </reference/collation>`
97+
entry in the {+mdb-server+} manual.

source/monitoring-logging/change-streams.txt

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,8 @@ can set in the array:
174174
| This option is mutually exclusive with ``startAfter`` and ``resumeAfter``.
175175

176176
* - ``collation``
177-
- | Sets the collation to use for the change stream cursor.
177+
- | Sets the collation to use for the change stream cursor. To learn more,
178+
see the :ref:`php-change-stream-collation` section of this page.
178179

179180
For a full list of ``watch()`` options, see `MongoDB\\Collection::watch()
180181
<{+api+}/method/MongoDBCollection-watch/>`__ in the API
@@ -255,6 +256,13 @@ output:
255256
:manual:`Change Streams with Document Pre- and Post-Images </changeStreams#change-streams-with-document-pre--and-post-images>`
256257
in the {+mdb-server+} manual.
257258

259+
.. _php-change-stream-collation:
260+
261+
Collation
262+
~~~~~~~~~
263+
264+
.. include:: /includes/collation.rst
265+
258266
Additional Information
259267
----------------------
260268

0 commit comments

Comments
 (0)