DOCSP-47263 Atlas Search string range query (#525)

(cherry picked from commit 26102d5)

Author: jordan-smith721

Diff for: source/fundamentals/atlas-search.txt

@@ -37,7 +37,7 @@ To learn more about the ``$search`` pipeline stage, see :manual:`$search
 The examples in this guide use the following documents in a collection called
 ``guitars``:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id": 1, "make": "Fender", "description": "Classic guitars known for their versatility.", "establishedYear": 1946, "in_stock": true, "rating": 9 }
    { "_id": 2, "make": "Gibson", "description": "Classic guitars known for their rich, full tones.", "establishedYear": 1902, "in_stock": true, "rating": 8 }
@@ -108,7 +108,7 @@ collection using the string "Gib" in the ``make`` field.
 
 The search returns the following document:
 
-.. code-block:: json
+.. code-block:: text
 
     { "_id" : 2, "make" : "Gibson", "description" : "Classic guitars known for their rich, full tones.", "establishedYear" : 1902, "in_stock" : true, "rating" : 8 }
 
@@ -136,7 +136,7 @@ that match all of the following criteria:
 
 The search returns the following documents:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id" : 1, "make" : "Fender", "description" : "...", "establishedYear" : 1946, "in_stock" : true, "rating" : 9 }
    { "_id" : 3, "make" : "PRS", "description" : "...", "establishedYear" : 1985, "in_stock" : true, "rating" : 9 }
@@ -186,7 +186,7 @@ and returns any documents with a ``serial`` field value of ``"YZ5678"``:
 
 The search returns the following document:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id" : 1, "make" : "Fender", "description" : "Classic guitars known for their versatility.", "establishedYear" : 1946, "in_stock" : true, "rating" : 9, "productDetails" : [{ "product_id" : 1234, "serial" : "YZ5678" }] }
 
@@ -210,7 +210,7 @@ which the value of the ``in_stock`` field is ``true``.
 
 The search returns the following documents:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id" : 1, "make" : "Fender", "description" : "...", "establishedYear" : 1946, "in_stock" : true, "rating" : 9 }
    { "_id" : 2, "make" : "Gibson", "description" : "...", "establishedYear" : 1902, "in_stock" : true, "rating" : 8 }
@@ -239,7 +239,7 @@ which the ``rating`` field exists.
 
 The search returns the following documents:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id" : 1, "make" : "Fender", "description" : "...", "establishedYear" : 1946, "in_stock" : true, "rating" : 9 }
    { "_id" : 2, "make" : "Gibson", "description" : "...", "establishedYear" : 1902, "in_stock" : true, "rating" : 8 }
@@ -282,7 +282,7 @@ polygon:
 
 The search returns the following document:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id" : 1, "make" : "Fender", "description" : "...", "establishedYear" : 1946, "in_stock" : true, "in_stock_location" : { "type" : "Point", "coordinates" : ["-73.93615", "40.69791"] }, "rating" : 9 }
 
@@ -328,7 +328,7 @@ polygon:
 
 The search returns the following document:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id" : 1, "make" : "Fender", "description" : "Classic guitars known for their versatility.", "establishedYear" : 1946, "in_stock" : true, "in_stock_location" : { "type" : "Point", "coordinates" : ["-73.93615", "40.69791"] }, "rating" : 9 }
 
@@ -352,7 +352,7 @@ The following example searches the ``guitars`` collection for documents that hav
 
 The search returns the following documents:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id": 1, "make": "Fender", "description": "...", "establishedYear": 1946, "in_stock": true, "rating": 9 }
    { "_id": 2, "make": "Gibson", "description": "...", "establishedYear": 1902, "in_stock": true, "rating": 8 }
@@ -375,7 +375,7 @@ quality."
 
 The search returns the following documents:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id" : 3, "make" : "PRS", "description" : "High-end guitars known for their quality.", "establishedYear" : 1985, "in_stock" : true, "rating" : 9 }
    { "_id" : 4, "make" : "Kiesel", "description" : "Quality guitars made only for custom orders.", "establishedYear" : 2015, "in_stock" : false, "rating" : null }
@@ -406,7 +406,7 @@ order based on how close the value is to the number ``9``.
 
 The search returns the following documents:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id" : 1, "make" : "Fender", "description" : "...", "establishedYear" : 1946, "in_stock" : true, "rating" : 9 }
    { "_id" : 3, "make" : "PRS", "description" : "...", "establishedYear" : 1985, "in_stock" : true, "rating" : 9 }
@@ -434,7 +434,7 @@ the ``description`` field contains the phrase "classic guitars."
 
 The search returns the following documents:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id" : 1, "make" : "Fender", "description" : "Classic guitars known for their versatility.", "establishedYear" : 1946, "in_stock" : true, "rating" : 9 }
    { "_id" : 2, "make" : "Gibson", "description" : "Classic guitars known for their rich, full tones.", "establishedYear" : 1902, "in_stock" : true, "rating" : 8 }
@@ -450,7 +450,7 @@ phrases as follows:
 
 This search returns the following documents:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id" : 1, "make" : "Fender", "description" : "Classic guitars known for their versatility.", "establishedYear" : 1946, "in_stock" : true, "rating" : 9 }
    { "_id" : 4, "make" : "Kiesel", "description" : "Quality guitars made only for custom orders.", "establishedYear" : 2015, "in_stock" : false, "rating" : null }
@@ -484,7 +484,7 @@ the value of the ``description`` field matches each of the following criteria:
 
 The search returns the following documents:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id" : 1, "make" : "Fender", "description" : "Classic guitars known for their versatility.", "establishedYear" : 1946, "in_stock" : true, "rating" : 9 }
    { "_id" : 3, "make" : "PRS", "description" : "High-end guitars known for their quality.", "establishedYear" : 1985, "in_stock" : true, "rating" : 9 }
@@ -497,7 +497,7 @@ Range
 ~~~~~
 
 Use the ``Range()`` method to search for documents in which the value of a
-specified field falls within a given numeric or date range.
+specified field falls within a given numeric, date, or string range.
 
 The following example searches the ``guitars`` collection for all documents with
 an ``establishedYear`` value greater than 1980 and less than 2020.
@@ -510,12 +510,38 @@ an ``establishedYear`` value greater than 1980 and less than 2020.
 
 The search returns the following results:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id" : 3, "make" : "PRS", "description" : "High-end guitars known for their quality.", "establishedYear" : 1985, "in_stock" : true, "rating" : 9 }
    { "_id" : 4, "make" : "Kiesel", "description" : "Quality guitars made only for custom orders.", "establishedYear" : 2015, "in_stock" : false, "rating" : null }
    { "_id" : 6, "make" : "Strandberg", "description" : "Modern guitars known for their headless models.", "establishedYear" : 1982, "in_stock" : false, "rating" : null }
 
+To search for documents in which the value of a specified field is within a
+range of strings, you must first create a :atlas:`token index
+</atlas-search/field-types/token-type/>` on the field. After you create the
+index, you can search for documents based on a range of strings as shown in the
+following example:
+
+.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
+   :start-after: // start-range-string
+   :end-before: // end-range-string
+   :language: csharp
+   :dedent:
+
+The preceding example searches for any documents in which the string value of the
+``make`` field is greater than or equal to ``"Fender"`` and less than or equal
+to ``"Kiesel"``. The driver compares the string values in :wikipedia:`lexicographic order
+<Lexicographic_order>`. 
+
+The search returns the following results:
+
+.. code-block:: text
+
+   { "_id" : 1, "make" : "Fender", "description" : "Classic guitars known for their versatility.", "establishedYear" : 1946, "in_stock" : true, "rating" : 9 }
+   { "_id" : 2, "make" : "Gibson", "description" : "Classic guitars known for their rich, full tones.", "establishedYear" : 1902, "in_stock" : true, "rating" : 8 }
+   { "_id" : 4, "make" : "Kiesel", "description" : "Quality guitars made only for custom orders.", "establishedYear" : 2015, "in_stock" : false, "rating" : null }
+   { "_id" : 5, "make" : "Ibanez", "description" : "Well-crafted guitars used by many professional guitarists.", "establishedYear" : 1957, "in_stock" : true, "rating" : 7 } 
+
 To learn more about the ``range`` operator, see the :atlas:`range </atlas-search/range>` 
 Atlas guide.
 
@@ -535,7 +561,7 @@ the value of the ``make`` field contains exactly six letters.
 
 The search returns the following results:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id" : 1, "make" : "Fender", "description" : "Classic guitars known for their versatility.", "establishedYear" : 1946, "in_stock" : true, "rating" : 9 }
    { "_id" : 2, "make" : "Gibson", "description" : "Classic guitars known for their rich, full tones.", "establishedYear" : 1902, "in_stock" : true, "rating" : 8 }
@@ -585,7 +611,7 @@ the value of the ``description`` field contains the strings "guitars" and
 
 The search returns the following document:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id" : 4, "make" : "Kiesel", "description" : "Quality guitars made only for custom orders.", "establishedYear" : 2015, "in_stock" : false, "rating" : null }
 
@@ -615,7 +641,7 @@ professionals".
 
 The search returns the following document:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id" : 5, "make" : "Ibanez", "description" : "Well-crafted guitars used by many professional guitarists.", "establishedYear" : 1957, "in_stock" : true, "rating" : 7 }
 
@@ -661,7 +687,7 @@ field contains the string "Strand" followed by any other characters.
 
 The search returns the following document:
 
-.. code-block:: json
+.. code-block:: text
 
    { "_id" : 6, "make" : "Strandberg", "description" : "Modern guitars known for their headless models.", "establishedYear" : 1982, "in_stock" : false, "rating" : null }
 

Diff for: source/includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs

@@ -204,13 +204,24 @@ public static List<Guitar> RangeSearch()
     {
         // start-range-search
         var result = guitarsCollection.Aggregate()
-            .Search(Builders<Guitar>.Search.Range(g => g.EstablishedYear, SearchRangeBuilder.Gt(1980).Lt(2020)))
+            .Search(Builders<Guitar>.Search
+            .Range(g => g.EstablishedYear, SearchRangeBuilder.Gt(1980).Lt(2020)))
             .ToList();
         // end-range-search
 
         return result;
     }
 
+    public static List<Guitar> RangeStringSearch()
+    {
+        // start-range-string
+        var result = guitarsCollection.Aggregate()
+             .Search(Builders<Guitar>.Search
+             .Range(g => g.Make, SearchRangeV2Builder.Gte("Fender").Lte("Kiesel")))
+             .ToList();
+        // end-range-string
+    }
+
     public static List<Guitar> RegexSearch()
     {
         // start-regex-search