DOCS-14779 Add context around 5.1 let usage in geoNear #6073

ianf-mongodb · 2021-11-03T19:10:08Z

No description provided.

jeff-allen-mongo

Hey @ianf-mongodb , just a few small things to address prior to merge. Thanks!

jeff-allen-mongo · 2021-11-03T19:25:31Z

source/reference/operator/aggregation/geoNear.txt

+
+.. _geoNear_let_example:
+
+$geoNear with the ``let`` option


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.

jeff-allen-mongo · 2021-11-03T19:30:22Z

source/reference/operator/aggregation/geoNear.txt

+In this example:
+
+- The ``let`` option is used to set an array value of 
+  ``[-73.99279,40.719296]`` to the variable ``$pt``.


What is the significance of the name "pt"? Is it short for "point", or is it an acronym of some kind?

Its just the variable name for the point array.

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.

jeff-allen-mongo · 2021-11-03T19:31:25Z

source/reference/operator/aggregation/geoNear.txt

+- ``$pt`` is a let option to the ``near`` parameter to the ``$geoNear`` 
+  stage.


This phrasing here is a little off.

Suggested change

- ``$pt`` is a let option to the ``near`` parameter to the ``$geoNear``

stage.

- ``$pt`` is specified as a let option to the ``near`` parameter in the ``$geoNear``

stage.

jeff-allen-mongo · 2021-11-03T19:31:55Z

source/reference/operator/aggregation/geoNear.txt

+
+.. _geoNear_bounded_let_example:
+
+$geoNear With Bound ``let`` Option


Suggested change

$geoNear With Bound ``let`` Option

$geoNear with Bound ``let`` Option

jeff-allen-mongo · 2021-11-03T19:38:33Z

source/reference/operator/aggregation/geoNear.txt

+   db.places.aggregate(
+   [
+   {
+      $lookup: 
+         {
+            from: "places",
+            let: { pt: "$location" },
+            pipeline: [
+               {
+                  $geoNear:
+                     {
+                        near: "$$pt",
+                        distanceField: "distance"
+                     }
+               }
+               ],
+            as: "joinedField"
+         }
+      },
+      { $match: { name: "Sara D. Roosevelt Park" } }
+   ]
+   );


The indentation here is a little off. We (generally) need the closing brackets to align with their opening counterparts. Suggest something like:

Suggested change

db.places.aggregate(

[

{

$lookup:

{

from: "places",

let: { pt: "$location" },

pipeline: [

{

$geoNear:

{

near: "$$pt",

distanceField: "distance"

}

}

],

as: "joinedField"

}

},

{ $match: { name: "Sara D. Roosevelt Park" } }

]

);

db.places.aggregate( [

{

$lookup: {

from: "places",

let: { pt: "$location" },

pipeline: [

{

$geoNear: {

near: "$$pt",

distanceField: "distance"

}

}

],

as: "joinedField"

}

},

{

$match: { name: "Sara D. Roosevelt Park" }

}

] );

jeff-allen-mongo · 2021-11-03T19:47:33Z

source/reference/operator/aggregation/geoNear.txt

+   }
+   )
+
+The aggregation returns the following:


Can we explain a little bit what the results mean? The other examples on this page have explanations like:

The following aggregation uses $geoNear to find documents with a location at most 2 meters from the center [ -73.99279 , 40.719296 ] and category equal to Parks.

Users might have an easier time following these examples if we briefly explain what the goal of the pipeline we've created is.

I specified this above each of the queries :

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.

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.

Do you mean explictly changing "the aggregation returns the following" to describe the pipeline? I tried to copy the existing format as much as possible.

Yeah I saw, but my point was more that we've explained what the parameters are but not how they affect the end result. I think if we adjusted:

The aggregation returns the following:

To be something like:

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::

it could help paint a clearer picture. The examples which were on the page prior to this change do have an explanation like this. However, if you think the current approach is clear enough we can leave this alone.

ianf-mongodb

Updated + responded.

jeff-allen-mongo

Thanks for the updates and comments @ianf-mongodb. Responded.

source/reference/operator/aggregation/geoNear.txt

jeff-allen-mongo · 2021-11-04T14:01:45Z

source/reference/operator/aggregation/geoNear.txt

+In this example:
+
+- The ``let`` option is used to set an array value of 
+  ``[-73.99279,40.719296]`` to the variable ``$pt``.


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.

jeff-allen-mongo · 2021-11-04T14:09:54Z

source/reference/operator/aggregation/geoNear.txt

+   {
+    _id: ObjectId("61715cf9b0c1d171bb498fd7"),


Do these objects need to be indented 1-2 more spaces? I'm wondering why the syntax highlighting isn't working in this code-block.

Yes Corrected

jeff-allen-mongo · 2021-11-04T14:17:08Z

source/reference/operator/aggregation/geoNear.txt

+   }
+   )
+
+The aggregation returns the following:


Yeah I saw, but my point was more that we've explained what the parameters are but not how they affect the end result. I think if we adjusted:

The aggregation returns the following:

To be something like:

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::

it could help paint a clearer picture. The examples which were on the page prior to this change do have an explanation like this. However, if you think the current approach is clear enough we can leave this alone.

ianf-mongodb · 2021-11-04T18:51:51Z

Hey Jeff added the context to the example queries and corrected the code box so it is displaying the syntax highlighting correctly now. @jeff-allen-mongo

jeff-allen-mongo · 2021-11-04T19:30:51Z

Thanks @ianf-mongodb , did you see this comment from my last review? I don't see the update for that one.

Co-authored-by: jeff-allen-mongo <[email protected]>

ianf-mongodb

Committed suggestion.

* DOCSP-33168: Add missing sharding step * rewording * copy review

ianf-mongodb force-pushed the DOCS-14779-geoNear-let-near-argument-allowed branch from ca66a80 to 0e5c11a Compare November 3, 2021 19:11

jeff-allen-mongo requested changes Nov 3, 2021

View reviewed changes

jeff-allen-mongo reviewed Nov 3, 2021

View reviewed changes

ianf-mongodb force-pushed the DOCS-14779-geoNear-let-near-argument-allowed branch from 0e5c11a to 12635b1 Compare November 4, 2021 12:40

ianf-mongodb commented Nov 4, 2021

View reviewed changes

ianf-mongodb force-pushed the DOCS-14779-geoNear-let-near-argument-allowed branch 3 times, most recently from 31797fe to 82caaae Compare November 4, 2021 12:58

jeff-allen-mongo reviewed Nov 4, 2021

View reviewed changes

ianf-mongodb force-pushed the DOCS-14779-geoNear-let-near-argument-allowed branch 2 times, most recently from cd61d17 to e5da078 Compare November 4, 2021 18:41

DOCS-14779 Add context around 5.1 let usage in geoNear

e1f080f

ianf-mongodb force-pushed the DOCS-14779-geoNear-let-near-argument-allowed branch from e5da078 to e1f080f Compare November 4, 2021 18:55

Update source/reference/operator/aggregation/geoNear.txt

9a49330

Co-authored-by: jeff-allen-mongo <[email protected]>

ianf-mongodb commented Nov 5, 2021

View reviewed changes

jeff-allen-mongo approved these changes Nov 5, 2021

View reviewed changes

jeff-allen-mongo merged commit 911c14d into mongodb:master Nov 5, 2021

mongo-cr-bot pushed a commit that referenced this pull request Jan 30, 2024

DOCSP-33168: Add missing sharding step (#6018) (#6073)

d9bb6bb

* DOCSP-33168: Add missing sharding step * rewording * copy review

		- ``$pt`` is a let option to the ``near`` parameter to the ``$geoNear``
		stage.


		.. _geoNear_bounded_let_example:

		$geoNear With Bound ``let`` Option

DOCS-14779 Add context around 5.1 let usage in geoNear #6073

DOCS-14779 Add context around 5.1 let usage in geoNear #6073

Uh oh!

Conversation

ianf-mongodb commented Nov 3, 2021

Uh oh!

jeff-allen-mongo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ianf-mongodb Nov 4, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ianf-mongodb left a comment

Choose a reason for hiding this comment

Uh oh!

jeff-allen-mongo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ianf-mongodb Nov 4, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ianf-mongodb commented Nov 4, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jeff-allen-mongo commented Nov 4, 2021

Uh oh!

ianf-mongodb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ianf-mongodb Nov 4, 2021 •

edited

Loading

ianf-mongodb Nov 4, 2021 •

edited

Loading

ianf-mongodb commented Nov 4, 2021 •

edited

Loading