-
Notifications
You must be signed in to change notification settings - Fork 1.7k
DOCS-14779 Add context around 5.1 let usage in geoNear #6073
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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>`. |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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``. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What is the significance of the name "pt"? Is it short for "point", or is it an acronym of some kind? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Its just the variable name for the point array. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thanks for clarifying. fwiw I don't love this as a variable name because it wasn't immediately clear to me what the significance of it was, but we can leave it alone. |
||
|
||
- ``$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' document 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 | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the maximum and minimum distance examples should still be the first examples in this section. I'm worried that if we put the
let
option first, we're introducing a fairly abstract / complex example as the first one on the page. Let's make sure that the simplest, most straight-forward examples appear first when possible.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Updated.