DOCSP-8733: Collation Fundamentals guide (#55)

* DOCSP-8733: Collations Guide

Author: Chris Cho

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

@@ -0,0 +1,8 @@
+// ignored first line
+collection.aggregate(
+  [
+    { $group: { "_id": "$first_name", "nameCount": { "$sum": 1 } } },
+    { $sort: { "_id": 1 } },
+  ],
+  { collation: { locale: "de@collation=phonebook" } },
+);

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

@@ -0,0 +1,18 @@
+// ignored first line
+
+// start create collection with collation
+// Create the collection with a collation
+db.createCollection("souvenirs", {
+  collation: { locale: "fr_CA" },
+});
+// end create collection with collation
+
+// start collection query without collation
+collection.find({type: "photograph"});
+// end collection query without collation
+
+ // start collection query with collation
+ collection.find({type: "photograph"},
+   { collation: { locale: "is", caseFirst: "upper" } }
+ );
+ // end collection query with collation

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

@@ -0,0 +1,3 @@
+// ignored first line
+collection.find({ city: "New York" }, { collation: { locale: "de" } })
+  .sort({ name: 1 });

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

@@ -0,0 +1,11 @@
+// ignored first line
+// start findOneAndDelete example without collation
+await collection.findOneAndDelete({ a: { $gt: "100" } });
+// end findOneAndDelete example without collation
+
+// start findOneAndDelete example with collation
+collection.findOneAndDelete(
+  { a: { $gt: "100" } },
+  { collation: { locale: "en", numericOrdering: true } },
+);
+// end findOneAndDelete example with collation

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

@@ -0,0 +1,15 @@
+// ignored first line
+// start findOneAndUpdate without collation
+collection.findOneAndUpdate(
+  { first_name : { $lt: "Gunter" } },
+  { $set: { verified: true } }
+);
+// end findOneAndUpdate without collation
+
+// start findOneAndUpdate with collation
+collection.findOneAndUpdate(
+  { first_name: { $lt: "Gunter" } },
+  { $set: { verified: true } },
+  { collation: { locale: "de@collation=phonebook" } },
+);
+// end findOneAndUpdate with collation

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

@@ -0,0 +1,4 @@
+// ignored first line
+collection.createIndex(
+  { 'title' : 1 },
+  { 'collation' : { 'locale' : 'en_US' } });

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

@@ -0,0 +1,15 @@
+// ignored first line
+// start query index collation
+collection.find({"year": 1980}, {"collation" : {"locale" : "en_US" }})
+  .sort({"title": -1});
+// end query index collation
+
+// start query without index collation
+// no collation specified
+collection.find({"year": 1980})
+  .sort({"title": -1});
+
+// collation differs from the one on the index
+collection.find({"year": 1980}, {"collation" : {"locale" : "en_US", "strength": 2 }})
+  .sort({"title": -1});
+// end query without index collation

source/fundamentals.txt

@@ -7,8 +7,9 @@ Fundamentals
 .. toctree::
 
    /fundamentals/connection
+   /fundamentals/authentication
    /fundamentals/crud
    /fundamentals/indexes
-   /fundamentals/authentication
+   /fundamentals/collations
    /fundamentals/logging
    /fundamentals/monitoring