DOCS-14779 Add context around 5.1 let usage in geoNear

Author: ianf-mongodb

source/includes/fact-5.1-geonear-let-allowed.rst

@@ -0,0 +1,3 @@
+Starting in MongoDB 5.1, the ``near`` parameter in the :pipeline:`$geoNear`
+aggregation stage supports the :ref:`let option <geoNear_let_example>` and
+:ref:`bound let option <geoNear_bounded_let_example>`.

source/reference/operator/aggregation/geoNear.txt

@@ -204,8 +204,15 @@ When using :pipeline:`$geoNear`, consider that:
 - Starting in version 4.2, :pipeline:`$geoNear` no longer has a default
   limit of 100 documents.
 
-Example
--------
+- Starting in MongoDB 5.1, the ``near`` parameter supports the 
+  :ref:`let option <geoNear_let_example>` and
+  :ref:`bound let option <geoNear_bounded_let_example>`.
+
+Examples
+--------
+
+Maximum Distance
+~~~~~~~~~~~~~~~~
 
 .. note::
 
@@ -287,6 +294,143 @@ equal to ``Parks``.
       }
    ])
 
+.. _geoNear_let_example:
+
+$geoNear with the ``let`` option
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In this example:
+
+- The ``let`` option is used to set an array value of 
+  ``[-73.99279,40.719296]`` to the variable ``$pt``.
+
+- ``$pt`` is specified as a let option to the ``near`` parameter in the 
+  ``$geoNear`` stage.
+
+.. code-block:: javascript
+   :emphasize-lines: 6,16
+
+   db.places.aggregate(
+   [
+      {
+         "$geoNear":
+         {
+            "near":"$$pt",
+            "distanceField":"distance",
+            "maxDistance":2,
+            "query":{"category":"Parks"},
+            "includeLocs":"dist.location",
+            "spherical":true
+         }
+      }
+   ],
+   {
+      "let":{ "pt": [ -73.99279, 40.719296 ] }
+   }
+   )
+
+The aggregation returns all documents with: 
+
+- A location at most 2 meters from the point defined in  the ``let`` variable
+- A ``category`` equal to ``Parks``.
+
+.. code-block:: javascript
+   :copyable: false
+
+   {
+      _id: ObjectId("61715cf9b0c1d171bb498fd7"),
+      name: 'Sara D. Roosevelt Park',
+      location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] },
+      category: 'Parks',
+      distance: 1.4957325341976439e-7,
+      dist: { location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] } }
+   },
+   {
+      _id: ObjectId("61715cf9b0c1d171bb498fd6"),
+      name: 'Central Park',
+      location: { type: 'Point', coordinates: [ -73.97, 40.77 ] },
+      category: 'Parks',
+      distance: 0.0009348548688841822,
+      dist: { location: { type: 'Point', coordinates: [ -73.97, 40.77 ] } }
+   }
+
+.. _geoNear_bounded_let_example:
+
+$geoNear with Bound ``let`` Option
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``let`` option can bind a variable which can be used in a 
+$geoNear query.
+
+In this example, :pipeline:`$lookup` uses:
+
+- ``let`` to define ``$pt``.
+- :pipeline:`$geoNear` in the ``pipeline``.
+- ``$pt`` to define ``near`` in the :pipeline:`$geoNear` pipeline stage.
+
+.. code-block:: javascript
+   :emphasize-lines: 5
+
+      db.places.aggregate( [
+      {
+         $lookup:{
+            from: "places",
+            let: { pt: "$location" },
+            pipeline: [
+               {
+                  $geoNear: {
+                     near: "$$pt",
+                     distanceField: "distance"
+                  }
+               }
+            ],
+            as: "joinedField"
+         }
+      },
+      { 
+         $match: { name: "Sara D. Roosevelt Park" }
+      }
+   ] );
+
+The aggregation returns a document with: 
+
+- The 'Sara D. Roosevelt Park' as the main document.
+- Every document in the places collection as subDocuments using the 
+  ``$pt`` variable for calculating distance.
+
+.. code-block:: javascript
+   :copyable: false
+
+   {
+    _id: ObjectId("61715cf9b0c1d171bb498fd7"),
+    name: 'Sara D. Roosevelt Park',
+    location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] },
+    category: 'Parks',
+    joinedField: [
+      {
+        _id: ObjectId("61715cf9b0c1d171bb498fd7"),
+        name: 'Sara D. Roosevelt Park',
+        location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] },
+        category: 'Parks',
+        distance: 0
+      },
+      {
+        _id: ObjectId("61715cf9b0c1d171bb498fd6"),
+        name: 'Central Park',
+        location: { type: 'Point', coordinates: [ -73.97, 40.77 ] },
+        category: 'Parks',
+        distance: 5962.448255234964
+      },
+      {
+        _id: ObjectId("61715cfab0c1d171bb498fd8"),
+        name: 'Polo Grounds',
+        location: { type: 'Point', coordinates: [ -73.9375, 40.8303 ] },
+        category: 'Stadiums',
+        distance: 13206.535424939102
+      }
+    ]
+  }
+
 .. _pipeline-geoNear-key-param-example:
 
 Specify Which Geospatial Index to Use

source/release-notes/5.1.txt

@@ -20,6 +20,11 @@ Aggregation
 
 .. _5.1-rel-notes-new-agg-operators:
 
+$geoNear accepts ``let-bound`` variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/fact-5.1-geonear-let-allowed.rst
+
 $lookup and $graphLookup with sharded collections
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~