Skip to content

Commit 3f9a672

Browse files
author
Chris Cho
committed
DOCSP-32718: add CodeWhisperer comments to collation code snippets (#763)
* DOCSP-32718: add CodeWhisperer comments to collation code snippets (cherry picked from commit c66ae08)
1 parent ead4108 commit 3f9a672

14 files changed

+126
-61
lines changed

‎source/code-snippets/collation/aggregation-collation.js

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,13 @@
1+
/*
2+
Retrieve the total number of matching names, grouped by the first_name
3+
field and sorted by using the German phonebook collation.
4+
*/
5+
// start aggregation collation
16
myColl.aggregate(
27
[
38
{ $group: { "_id": "$first_name", "nameCount": { "$sum": 1 } } },
49
{ $sort: { "_id": 1 } },
510
],
611
{ collation: { locale: "de@collation=phonebook" } },
712
);
13+
// end aggregation collation

‎source/code-snippets/collation/collection-auto-collation.js

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
// Retrieve documents that match "photograph" in the "type" field
2+
// start auto collation
3+
myColl.find({type: "photograph"});
4+
// end auto collation

‎source/code-snippets/collation/collection-collation.js

Lines changed: 3 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,6 @@
1-
// start create collection with collation
2-
// Create the collection with a collation
1+
// Create the "souvenirs" collection and specify the French Canadian collation
2+
// start collection collation
33
db.createCollection("souvenirs", {
44
collation: { locale: "fr_CA" },
55
});
6-
// end create collection with collation
7-
8-
// start collection query without collation
9-
myColl.find({type: "photograph"});
10-
// end collection query without collation
11-
12-
// start collection query with collation
13-
myColl.find({type: "photograph"},
14-
{ collation: { locale: "is", caseFirst: "upper" } }
15-
);
16-
// end collection query with collation
6+
// end collection collation

‎source/code-snippets/collation/collection-specify-collation.js

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
/*
2+
Retrieve documents that match "photograph" in the "type" field,
3+
sorted by the Iceland collation and uppercase precedence.
4+
*/
5+
// start specified collation
6+
myColl.find({type: "photograph"},
7+
{ collation: { locale: "is", caseFirst: "upper" } }
8+
);
9+
// end specified collation

‎source/code-snippets/collation/find-sort-collation.js

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,8 @@
1+
/*
2+
Retrieve documents that match "New York" in the "city" field,
3+
sorted by the "name" field by using the German collation.
4+
*/
5+
// start find sort collation
16
myColl.find({ city: "New York" }, { collation: { locale: "de" } })
27
.sort({ name: 1 });
8+
// end find sort collation

‎source/code-snippets/collation/findOneAndDelete-collation.js

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1-
// start findOneAndDelete example without collation
2-
await myColl.findOneAndDelete({ a: { $gt: "100" } });
3-
// end findOneAndDelete example without collation
4-
5-
// start findOneAndDelete example with collation
1+
/*
2+
Delete the first document that contains a value greater
3+
than 100 in the "a" field when ordered by using the
4+
English numeric collation order.
5+
*/
6+
// start findOneAndDelete collation
67
myColl.findOneAndDelete(
78
{ a: { $gt: "100" } },
89
{ collation: { locale: "en", numericOrdering: true } },
910
);
10-
// end findOneAndDelete example with collation
11+
// end findOneAndDelete collation

‎source/code-snippets/collation/findOneAndDelete-no-collation.js

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
/*
2+
Delete the first document that contains a value greater
3+
than 100 in the "a" field when ordered by using the default
4+
binary collation order.
5+
*/
6+
// start findOneAndDelete no collation
7+
await myColl.findOneAndDelete({ a: { $gt: "100" } });
8+
// end findOneAndDelete no collation

‎source/code-snippets/collation/findOneAndUpdate-collation.js

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,12 @@
1-
// start findOneAndUpdate without collation
2-
myColl.findOneAndUpdate(
3-
{ first_name : { $lt: "Gunter" } },
4-
{ $set: { verified: true } }
5-
);
6-
// end findOneAndUpdate without collation
7-
8-
// start findOneAndUpdate with collation
1+
/*
2+
Update the "verified" field to "true" for the first document
3+
that precedes "Gunter" when ordered by using the
4+
German phonebook collation order.
5+
*/
6+
// start findOneAndUpdate collation
97
myColl.findOneAndUpdate(
108
{ first_name: { $lt: "Gunter" } },
119
{ $set: { verified: true } },
1210
{ collation: { locale: "de@collation=phonebook" } },
1311
);
14-
// end findOneAndUpdate with collation
12+
// end findOneAndUpdate collation

‎source/code-snippets/collation/findOneAndUpdate-default-order-collation.js

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
/*
2+
Update the "verified" field to "true" for the first document
3+
that precedes "Gunter" when ordered by using the
4+
default binary collation order.
5+
*/
6+
// start findOneAndUpdate default order collation
7+
myColl.findOneAndUpdate(
8+
{ first_name : { $lt: "Gunter" } },
9+
{ $set: { verified: true } }
10+
);
11+
// end findOneAndUpdate default order collation

‎source/code-snippets/collation/index-collation.js

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
1+
/*
2+
Create an index on the "title" field with the "en_US"
3+
locale collation, specifying ascending ordering of the
4+
"title" field.
5+
*/
6+
// start create index collation
17
myColl.createIndex(
28
{ 'title' : 1 },
39
{ 'collation' : { 'locale' : 'en_US' } });
10+
// end create index collation

‎source/code-snippets/collation/query-index-collation.js

Lines changed: 6 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,9 @@
1+
/*
2+
Retrieve documents that match the "year" value "1980"
3+
in descending order of the value of the "title" field,
4+
specifying a collation that uses the index.
5+
*/
16
// start query index collation
27
myColl.find({"year": 1980}, {"collation" : {"locale" : "en_US" }})
38
.sort({"title": -1});
4-
// end query index collation
5-
6-
// start query without index collation
7-
// no collation specified
8-
myColl.find({"year": 1980})
9-
.sort({"title": -1});
10-
11-
// collation differs from the one on the index
12-
myColl.find({"year": 1980}, {"collation" : {"locale" : "en_US", "strength": 2 }})
13-
.sort({"title": -1});
14-
// end query without index collation
9+
// end query index collation

‎source/code-snippets/collation/query-index-no-collation.js

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
/*
2+
Retrieve documents that match the "year" value "1980"
3+
in descending order of the value of the "title" field
4+
that does not use the collation index.
5+
*/
6+
// start index no collation
7+
myColl.find({"year": 1980})
8+
.sort({"title": -1});
9+
// end index no collation

‎source/code-snippets/collation/query-not-indexed-collation.js

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
/*
2+
Retrieve documents that match the "year" value "1980"
3+
in descending order of the value of the "title" field,
4+
specifying a collation that does not use the collation
5+
index.
6+
*/
7+
// start not indexed collation
8+
myColl.find({"year": 1980}, {"collation" : {"locale" : "en_US", "strength": 2 }})
9+
.sort({"title": -1});
10+
// end not indexed collation

‎source/fundamentals/collations.txt

Lines changed: 33 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -120,26 +120,26 @@ collection.
120120

121121
.. literalinclude:: /code-snippets/collation/collection-collation.js
122122
:language: javascript
123-
:start-after: start create collection with collation
124-
:end-before: end create collection with collation
123+
:start-after: start collection collation
124+
:end-before: end collection collation
125125

126126
Any of the operations that support collations automatically apply the collation
127127
defined on the collection. The query below searches the ``souvenirs``
128128
collection and applies the "``fr_CA``" locale collation:
129129

130-
.. literalinclude:: /code-snippets/collation/collection-collation.js
130+
.. literalinclude:: /code-snippets/collation/collection-auto-collation.js
131131
:language: javascript
132-
:start-after: start collection query without collation
133-
:end-before: end collection query without collation
132+
:start-after: start auto collation
133+
:end-before: end auto collation
134134

135135
You can specify a different collation as a parameter in an operation that
136136
supports collations. The following query specifies the "``is``" Iceland locale
137137
and ``caseFirst`` optional parameter with the value "``upper``":
138138

139-
.. literalinclude:: /code-snippets/collation/collection-collation.js
139+
.. literalinclude:: /code-snippets/collation/collection-specify-collation.js
140140
:language: javascript
141-
:start-after: start collection query with collation
142-
:end-before: end collection query with collation
141+
:start-after: start specified collation
142+
:end-before: end specified collation
143143

144144
Assign a Collation to an Index
145145
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -149,6 +149,8 @@ a collection with a collation set to the "``en_US``" locale.
149149

150150
.. literalinclude:: /code-snippets/collation/index-collation.js
151151
:language: javascript
152+
:start-after: start create index collation
153+
:end-before: end create index collation
152154

153155
The following query uses the index we created:
154156

@@ -157,14 +159,19 @@ The following query uses the index we created:
157159
:start-after: start query index collation
158160
:end-before: end query index collation
159161

160-
The following queries **do not** use the index that we created. The first
162+
The following queries **do not** use the index that we created. The first
161163
query does not include a collation and the second contains a different
162164
strength value than the collation on the index.
163165

164-
.. literalinclude:: /code-snippets/collation/query-index-collation.js
166+
.. literalinclude:: /code-snippets/collation/query-not-indexed-collation.js
165167
:language: javascript
166-
:start-after: start query without index collation
167-
:end-before: end query without index collation
168+
:start-after: start not indexed collation
169+
:end-before: end not indexed collation
170+
171+
.. literalinclude:: /code-snippets/collation/query-index-no-collation.js
172+
:language: javascript
173+
:start-after: start index no collation
174+
:end-before: end index no collation
168175

169176
Collation Query Examples
170177
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -183,6 +190,8 @@ setting the value of the ``locale`` parameter to ``de``.
183190

184191
.. literalinclude:: /code-snippets/collation/find-sort-collation.js
185192
:language: javascript
193+
:start-after: start find sort collation
194+
:end-before: end find sort collation
186195

187196
findOneAndUpdate() Example
188197
``````````````````````````
@@ -201,10 +210,10 @@ following documents:
201210
Consider the following ``findOneAndUpdate()`` operation on this collection
202211
which **does not** specify a collation:
203212

204-
.. literalinclude:: /code-snippets/collation/findOneAndUpdate-collation.js
213+
.. literalinclude:: /code-snippets/collation/findOneAndUpdate-default-order-collation.js
205214
:language: javascript
206-
:start-after: start findOneAndUpdate without collation
207-
:end-before: end findOneAndUpdate without collation
215+
:start-after: start findOneAndUpdate default order collation
216+
:end-before: end findOneAndUpdate default order collation
208217

209218
Since "Gunter" is the first sorted result when using a binary collation, none
210219
of the documents come lexically before and match the ``$lt`` comparison
@@ -220,8 +229,8 @@ umlauts.
220229

221230
.. literalinclude:: /code-snippets/collation/findOneAndUpdate-collation.js
222231
:language: javascript
223-
:start-after: start findOneAndUpdate with collation
224-
:end-before: end findOneAndUpdate with collation
232+
:start-after: start findOneAndUpdate collation
233+
:end-before: end findOneAndUpdate collation
225234

226235
Since "Günter" lexically comes before "Gunter" using the
227236
``de@collation=phonebook`` collation specified in ``findOneAndUpdate()``,
@@ -252,8 +261,8 @@ lexical order.
252261

253262
.. literalinclude:: /code-snippets/collation/findOneAndDelete-collation.js
254263
:language: javascript
255-
:start-after: start findOneAndDelete example with collation
256-
:end-before: end findOneAndDelete example with collation
264+
:start-after: start findOneAndDelete collation
265+
:end-before: end findOneAndDelete collation
257266

258267
After you run the operation above, the collection contains the following
259268
documents:
@@ -268,10 +277,10 @@ collection of three documents, it matches documents based on the lexical value
268277
of the strings ("``16``", "``84``", and "``179``"), and deletes the first
269278
document it finds that matches the query criteria.
270279

271-
.. literalinclude:: /code-snippets/collation/findOneAndDelete-collation.js
280+
.. literalinclude:: /code-snippets/collation/findOneAndDelete-no-collation.js
272281
:language: javascript
273-
:start-after: start findOneAndDelete example without collation
274-
:end-before: end findOneAndDelete example without collation
282+
:start-after: start findOneAndDelete no collation
283+
:end-before: end findOneAndDelete no collation
275284

276285
Since all the documents contain lexical values in the ``a`` field that
277286
match the criteria (greater than the lexical value of "``100``"), the operation
@@ -301,3 +310,5 @@ the German phonebook (``de@collation=phonebook`` locale) order.
301310

302311
.. literalinclude:: /code-snippets/collation/aggregation-collation.js
303312
:language: javascript
313+
:start-after: start aggregation collation
314+
:end-before: end aggregation collation

0 commit comments

Comments
 (0)