Skip to content

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

Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions source/includes/fact-5.1-geonear-let-allowed.rst
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>`.
148 changes: 146 additions & 2 deletions source/reference/operator/aggregation/geoNear.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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::

Expand Down Expand Up @@ -287,6 +294,143 @@ equal to ``Parks``.
}
])

.. _geoNear_let_example:

$geoNear with the ``let`` option
Copy link
Collaborator

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In this example:

- The ``let`` option is used to set an array value of
``[-73.99279,40.719296]`` to the variable ``$pt``.
Copy link
Collaborator

Choose a reason for hiding this comment

The 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?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Its just the variable name for the point array.

Copy link
Collaborator

Choose a reason for hiding this comment

The 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
Expand Down
5 changes: 5 additions & 0 deletions source/release-notes/5.1.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down