Skip to content

Commit e1f080f

Browse files
committed
DOCS-14779 Add context around 5.1 let usage in geoNear
1 parent 2405b95 commit e1f080f

File tree

3 files changed

+154
-2
lines changed

3 files changed

+154
-2
lines changed
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Starting in MongoDB 5.1, the ``near`` parameter in the :pipeline:`$geoNear`
2+
aggregation stage supports the :ref:`let option <geoNear_let_example>` and
3+
:ref:`bound let option <geoNear_bounded_let_example>`.

source/reference/operator/aggregation/geoNear.txt

Lines changed: 146 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -204,8 +204,15 @@ When using :pipeline:`$geoNear`, consider that:
204204
- Starting in version 4.2, :pipeline:`$geoNear` no longer has a default
205205
limit of 100 documents.
206206

207-
Example
208-
-------
207+
- Starting in MongoDB 5.1, the ``near`` parameter supports the
208+
:ref:`let option <geoNear_let_example>` and
209+
:ref:`bound let option <geoNear_bounded_let_example>`.
210+
211+
Examples
212+
--------
213+
214+
Maximum Distance
215+
~~~~~~~~~~~~~~~~
209216

210217
.. note::
211218

@@ -287,6 +294,143 @@ equal to ``Parks``.
287294
}
288295
])
289296

297+
.. _geoNear_let_example:
298+
299+
$geoNear with the ``let`` option
300+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
301+
302+
In this example:
303+
304+
- The ``let`` option is used to set an array value of
305+
``[-73.99279,40.719296]`` to the variable ``$pt``.
306+
307+
- ``$pt`` is specified as a let option to the ``near`` parameter in the
308+
``$geoNear`` stage.
309+
310+
.. code-block:: javascript
311+
:emphasize-lines: 6,16
312+
313+
db.places.aggregate(
314+
[
315+
{
316+
"$geoNear":
317+
{
318+
"near":"$$pt",
319+
"distanceField":"distance",
320+
"maxDistance":2,
321+
"query":{"category":"Parks"},
322+
"includeLocs":"dist.location",
323+
"spherical":true
324+
}
325+
}
326+
],
327+
{
328+
"let":{ "pt": [ -73.99279, 40.719296 ] }
329+
}
330+
)
331+
332+
The aggregation returns all documents with:
333+
334+
- A location at most 2 meters from the point defined in the ``let`` variable
335+
- A ``category`` equal to ``Parks``.
336+
337+
.. code-block:: javascript
338+
:copyable: false
339+
340+
{
341+
_id: ObjectId("61715cf9b0c1d171bb498fd7"),
342+
name: 'Sara D. Roosevelt Park',
343+
location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] },
344+
category: 'Parks',
345+
distance: 1.4957325341976439e-7,
346+
dist: { location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] } }
347+
},
348+
{
349+
_id: ObjectId("61715cf9b0c1d171bb498fd6"),
350+
name: 'Central Park',
351+
location: { type: 'Point', coordinates: [ -73.97, 40.77 ] },
352+
category: 'Parks',
353+
distance: 0.0009348548688841822,
354+
dist: { location: { type: 'Point', coordinates: [ -73.97, 40.77 ] } }
355+
}
356+
357+
.. _geoNear_bounded_let_example:
358+
359+
$geoNear with Bound ``let`` Option
360+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
361+
362+
The ``let`` option can bind a variable which can be used in a
363+
$geoNear query.
364+
365+
In this example, :pipeline:`$lookup` uses:
366+
367+
- ``let`` to define ``$pt``.
368+
- :pipeline:`$geoNear` in the ``pipeline``.
369+
- ``$pt`` to define ``near`` in the :pipeline:`$geoNear` pipeline stage.
370+
371+
.. code-block:: javascript
372+
:emphasize-lines: 5
373+
374+
db.places.aggregate( [
375+
{
376+
$lookup:{
377+
from: "places",
378+
let: { pt: "$location" },
379+
pipeline: [
380+
{
381+
$geoNear: {
382+
near: "$$pt",
383+
distanceField: "distance"
384+
}
385+
}
386+
],
387+
as: "joinedField"
388+
}
389+
},
390+
{
391+
$match: { name: "Sara D. Roosevelt Park" }
392+
}
393+
] );
394+
395+
The aggregation returns a document with:
396+
397+
- The 'Sara D. Roosevelt Park' document as the main document.
398+
- Every document in the places collection as subDocuments using the
399+
``$pt`` variable for calculating distance.
400+
401+
.. code-block:: javascript
402+
:copyable: false
403+
404+
{
405+
_id: ObjectId("61715cf9b0c1d171bb498fd7"),
406+
name: 'Sara D. Roosevelt Park',
407+
location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] },
408+
category: 'Parks',
409+
joinedField: [
410+
{
411+
_id: ObjectId("61715cf9b0c1d171bb498fd7"),
412+
name: 'Sara D. Roosevelt Park',
413+
location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] },
414+
category: 'Parks',
415+
distance: 0
416+
},
417+
{
418+
_id: ObjectId("61715cf9b0c1d171bb498fd6"),
419+
name: 'Central Park',
420+
location: { type: 'Point', coordinates: [ -73.97, 40.77 ] },
421+
category: 'Parks',
422+
distance: 5962.448255234964
423+
},
424+
{
425+
_id: ObjectId("61715cfab0c1d171bb498fd8"),
426+
name: 'Polo Grounds',
427+
location: { type: 'Point', coordinates: [ -73.9375, 40.8303 ] },
428+
category: 'Stadiums',
429+
distance: 13206.535424939102
430+
}
431+
]
432+
}
433+
290434
.. _pipeline-geoNear-key-param-example:
291435

292436
Specify Which Geospatial Index to Use

source/release-notes/5.1.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,11 @@ Aggregation
2020

2121
.. _5.1-rel-notes-new-agg-operators:
2222

23+
$geoNear accepts ``let-bound`` variables
24+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
25+
26+
.. include:: /includes/fact-5.1-geonear-let-allowed.rst
27+
2328
$lookup and $graphLookup with sharded collections
2429
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2530

0 commit comments

Comments
 (0)