Skip to content

Commit b062539

Browse files
norareidynorareidy
authored
DOCSP-13851: adding a collations page (#117)
* DOCSP-13851: adding a collations page * fixing TOC * fixing spacing and punctuation * code example fix * typo * changes from feedback * spacing fix * review feedback * adding to operation section * fixing code example * addressing feedback * feedback * feedback and code fix * monospace * adding to additional information * handing errors in examples
1 parent 7d265b7 commit b062539

File tree

2 files changed

+299
-2
lines changed

2 files changed

+299
-2
lines changed

‎source/fundamentals.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Fundamentals
1616
/fundamentals/crud
1717
/fundamentals/aggregation
1818
/fundamentals/indexes
19+
/fundamentals/collations
1920
/fundamentals/gridfs
2021
/fundamentals/time-series
2122

‎source/fundamentals/collations.txt‎

Lines changed: 298 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,301 @@ Collations
44

55
.. default-domain:: mongodb
66

7-
A collation is a set of character ordering and matching rules that
8-
apply to a specific language and locale.
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
Overview
14+
--------
15+
16+
In this guide, you can learn how to use **collations** to order your query
17+
or aggregation operation results by string values. A collation is a set of character
18+
ordering conventions that apply to a specific language and locale.
19+
20+
Collations in MongoDB
21+
---------------------
22+
23+
MongoDB sorts strings using *binary collation* by default. This collation
24+
method uses the `ASCII standard <https://en.wikipedia.org/wiki/ASCII>`_
25+
character values to compare and order strings. Certain languages and locales
26+
have specific character ordering conventions that differ from the ASCII
27+
standard.
28+
29+
For example, in Canadian French, the right-most accented character determines
30+
the ordering for strings when the other characters are the same. Consider the
31+
following Canadian French words:
32+
33+
- cote
34+
- coté
35+
- côte
36+
- côté
37+
38+
When using the default binary collation, MongoDB sorts them in the following order:
39+
40+
.. code-block:: none
41+
42+
cote
43+
coté
44+
côte
45+
côté
46+
47+
When using the Canadian French collation, MongoDB sorts them in the following order:
48+
49+
.. code-block:: none
50+
51+
cote
52+
côte
53+
coté
54+
côté
55+
56+
Specify a Collation
57+
-------------------
58+
59+
To specify a collation, create a ``Collation`` object. You must define the ``Locale`` field
60+
of the ``Collation`` object; all other fields are optional. For example, the following code
61+
snippet specifies a ``Collation`` object with the ``"en_US"`` locale collation:
62+
63+
.. code-block:: go
64+
65+
myCollation := &options.Collation{Locale: "en_US"}
66+
67+
For a complete list of ``Collation`` object fields, visit the `Collation API documentation
68+
<{+api+}/mongo/options#Collation>`__. To see all the supported locales and the
69+
default values for the ``Locale`` fields, visit :manual:`Supported Languages and Locales
70+
</reference/collation-locales-defaults/#supported-languages-and-locales>`.
71+
72+
Set a Collation on a Collection or View
73+
---------------------------------------
74+
75+
You can apply a collation when you create a new collection or view. This defines the default
76+
collation for any operations called on that collection or view. Set a collation through a
77+
``CreateCollectionOptions`` or ``CreateViewOptions`` object. Then, call the
78+
``CreateCollection()`` or ``CreateView()`` method with your options object as an argument.
79+
80+
.. _golang-create-collection:
81+
82+
Create a Collection Example
83+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
84+
85+
The following example creates a new collection called ``books`` and specifies a default
86+
collation with the ``"fr"`` locale. The ``Strength`` collation field has a value of ``1``
87+
to ignore differences in letter accents.
88+
89+
.. code-block:: go
90+
91+
myCollation := &options.Collation{Locale: "fr", Strength: 1}
92+
opts := options.CreateCollection().SetCollation(myCollation)
93+
err := db.CreateCollection(context.TODO(), "books", opts)
94+
95+
if err != nil {
96+
panic(err)
97+
}
98+
99+
Use the Default Collation Example
100+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
101+
102+
If you call an operation that uses a collation on the ``books`` collection, the operation
103+
will now use the default collation specified in the :ref:`golang-create-collection`.
104+
105+
Assume the ``books`` collection contains the following documents:
106+
107+
.. code-block:: json
108+
109+
{"name" : "Emma", "length" : "474"}
110+
{"name" : "Les Misérables", "length": "1462"}
111+
{"name" : "Infinite Jest", "length" : "1104"}
112+
{"name" : "Cryptonomicon", "length" : "918"}
113+
{"name" : "Ça", "length" : "1138"}
114+
115+
.. note::
116+
117+
To learn how to insert documents, see :ref:`golang-insert-guide`.
118+
119+
The following example uses the ``Find()`` method to return all documents with a ``name`` value
120+
that alphabetically precedes ``"Infinite Jest"``:
121+
122+
.. io-code-block::
123+
:copyable: true
124+
125+
.. input::
126+
:language: go
127+
128+
filter := bson.D{{"name", bson.D{{"$lt", "Infinite Jest"}}}}
129+
cursor, err := coll.Find(context.TODO(), filter)
130+
if err != nil {
131+
panic(err)
132+
}
133+
134+
var results []bson.D
135+
if err = cursor.All(context.TODO(), &results); err != nil {
136+
panic(err)
137+
}
138+
for _, result := range results {
139+
fmt.Println(result)
140+
}
141+
142+
.. output::
143+
:language: none
144+
:visible: false
145+
146+
[{name Ça} {length 1138}]
147+
[{name Cryptonomicon} {length 918}]
148+
[{name Emma} {length 474}]
149+
150+
Without specifying a default ``books`` collation, the ``Find()`` method would follow default
151+
binary collation rules to determine the ``name`` values that precede ``"Infinite Jest"``. These
152+
rules place words beginning with "Ç" after those beginning with "I". The output would resemble
153+
the following:
154+
155+
.. code-block:: json
156+
:copyable: false
157+
158+
[{name Cryptonomicon} {length 918}]
159+
[{name Emma} {length 474}]
160+
161+
To learn more about the ``Find()`` method, see :ref:`golang-retrieve`.
162+
163+
.. _golang-index-collation:
164+
165+
Set a Collation on an Index
166+
---------------------------
167+
168+
You can apply a collation when you create a new index on a collection. The index stores
169+
an ordered representation of the documents in the collection so your MongoDB instance
170+
does not need to perform the ordering for sorting operations in-memory.
171+
172+
To use the index in an operation, your operation must use the same collation as the one
173+
specified in the index. Additionally, ensure that the operation is covered by the index that
174+
contains the collation. Set a collation through an ``IndexOptions`` object and call the
175+
``CreateOne()`` method with your options object as an argument.
176+
177+
Example
178+
~~~~~~~
179+
180+
After creating the ``books`` collection and applying a default collation, as shown in the
181+
:ref:`golang-create-collection` section, you cannot change the collection's default collation.
182+
However, you can create an index for the collection with a different collation.
183+
184+
The following example uses the ``CreateOne()`` method to create an ascending index on the
185+
``name`` field and specifies a new collation with an ``"en_US"`` locale:
186+
187+
.. io-code-block::
188+
:copyable: true
189+
190+
.. input::
191+
:language: go
192+
193+
myCollation := &options.Collation{Locale: "en_US"}
194+
opts := options.Index().SetCollation(myCollation)
195+
196+
indexModel := mongo.IndexModel{
197+
Keys: bson.D{{"name", 1}},
198+
Options: opts,
199+
}
200+
201+
name, err := coll.Indexes().CreateOne(context.TODO(), indexModel)
202+
if err != nil {
203+
panic(err)
204+
}
205+
fmt.Println("Name of Index Created: " + name)
206+
207+
.. output::
208+
:language: none
209+
:visible: false
210+
211+
Name of Index Created: name_1
212+
213+
.. _golang-op-collation:
214+
215+
Set a Collation on an Operation
216+
-------------------------------
217+
218+
Operations that read, update, and delete documents from a collection can use collations.
219+
Applying a collation to an operation overrides any default collation previously defined
220+
for a collection.
221+
222+
If you apply a new collation to an operation that differs from an index's collation,
223+
you cannot use that index. As a result, the operation may not perform as well as one
224+
that is covered by an index. For more information on the disadvantages of sorting operations
225+
not covered by an index, see :manual:`Using Indexes to Sort Query Results </tutorial/sort-results-with-indexes/>`.
226+
See the :manual:`MongoDB manual </reference/collation/#collation-document>` for a list of
227+
operations that support collation.
228+
229+
Example
230+
~~~~~~~
231+
232+
You can use operations that support collation to update and query documents in the
233+
``books`` collection.
234+
235+
The following example uses the ``Find()`` method to return documents with ``length``
236+
values greater than ``"1000"``. The ``NumericOrdering`` collation field has a value of
237+
``true`` to ensure that values are sorted in numerical order rather than alphabetical
238+
order:
239+
240+
.. io-code-block::
241+
:copyable: true
242+
243+
.. input::
244+
:language: go
245+
246+
filter := bson.D{{"length", bson.D{{"$gt", "1000"}}}}
247+
myCollation := &options.Collation{Locale: "en_US", NumericOrdering: true}
248+
opts := options.Find().SetCollation(myCollation)
249+
250+
cursor, err := coll.Find(context.TODO(), filter, opts)
251+
if err != nil {
252+
panic(err)
253+
}
254+
255+
var results []bson.D
256+
if err = cursor.All(context.TODO(), &results); err != nil {
257+
panic(err)
258+
}
259+
260+
for _, result := range results {
261+
fmt.Println(result)
262+
}
263+
264+
.. output::
265+
:language: none
266+
:visible: false
267+
268+
[{name Infinite Jest} {length 1104}]
269+
[{name Ça} {length 1138}]
270+
[{name Les Misérables} {length 1462}]
271+
272+
Without specifying a collation with a ``NumericOrdering`` field set to ``true``, the
273+
same ``Find()`` operation would compare ``length`` values as strings. For example, the
274+
operation would consider the string ``"824"`` as greater than ``"1000"``. The
275+
output would resemble the following:
276+
277+
.. code-block:: json
278+
:copyable: false
279+
280+
[{name Emma} {length 474}]
281+
[{name Cryptonomicon} {length 918}]
282+
283+
Additional Information
284+
----------------------
285+
286+
To learn more about the ``Find()`` method, see the :ref:`golang-retrieve` guide.
287+
288+
To learn more about collations, visit the following manual pages:
289+
290+
- :manual:`Collation </reference/collation/#collation-document>`
291+
- :manual:`Collation Locales and Default Parameters </reference/collation-locales-defaults/#supported-languages-and-locales>`
292+
293+
API Documentation
294+
~~~~~~~~~~~~~~~~~
295+
296+
To learn more about the methods discussed in this guide, see the following
297+
API Documentation:
298+
299+
- `Collation <{+api+}/mongo/options#Collation>`__
300+
- `CreateCollectionOptions <{+api+}/mongo/options#CreateCollectionOptions>`__
301+
- `IndexModel <{+api+}/mongo#IndexModel>`__
302+
- `CreateOne() <{+api+}/mongo#IndexView.CreateOne>`__
303+
- `IndexOptions <{+api+}/mongo/options#IndexOptions>`__
304+
- `UpdateOptions <{+api+}/mongo/options#UpdateOptions>`__

0 commit comments

Comments
 (0)