Scope of changes:

There are several things to document related to the changes for this ticket.

 1) The minDistance option to the geoNear command and $geoNear aggregation stage can now be used with a "2d" index. The same is true for the $minDistance option to the $near and $nearSphere query predicates.

We document in several places that minDistance is only allowed for near queries that use a "2dsphere" index:

• https://docs.mongodb.com/manual/reference/command/geoNear/#dbcmd.geoNear
• https://docs.mongodb.com/manual/reference/operator/query/minDistance/#op._S_minDistance
• https://docs.mongodb.com/manual/reference/operator/query/nearSphere/#op._S_nearSphere
• https://docs.mongodb.com/manual/reference/operator/query/near/#op._S_near

This is no longer the case.

2) The spherical option to the geoNear command and $geoNear stage is no longer required for queries that use a "2dsphere" index.

This is subtle and kind of confusing. The old behavior was that, for any geoNear/$geoNear using a "2dsphere" index, the command would fail unless spherical was explicitly specified as true. We currently document that spherical is required for "2dsphere" indexes in a few places:

• https://docs.mongodb.com/manual/reference/command/geoNear/#dbcmd.geoNear
• https://docs.mongodb.com/manual/reference/operator/aggregation/geoNear/#pipe._S_geoNear

This ticket changes the spherical option such that spherical=true is identical in meaning to the $nearSphere query predicate and spherical=false is identical in meaning to the $near query predicate. This means that:

• The spherical flag must be set to true when using a legacy coordinate pair with a "2dsphere" index. In this case, distances will be in radians.
• The flag has no effect when using a GeoJSON point with a "2dsphere" index, since GeoJSON always implies a spherical CRS and can never be used with a "2d" index. Distances will be in meters.
• When using a "2d" index, the flag controls whether or not a flat or spherical CRS is used. In the case of spherical, the search point must be specified as a legacy coordinate pair, and distances are in radians.

I think this behavior could be summarized in two ways. The first is "The spherical flag controls whether $near or $nearSphere semantics are used." The second is, "When using a '2d' index, the spherical flag controls whether to calculate distances using a planar or spherical geometry". In any case, we need to remove the sentences that say "Required if using a 2dsphere index.".

3) This ticket adds a new key param which is accepted by both the geoNear command and the $geoNear stage, and is used to specify the field path over which to compute the near.

This parameter needs to be documented in both places. We should probably also add an example. Finally, we need to remove or modify sentences like this one: "However, the geoNear command requires that a collection have at most only one 2dsphere and/or only one 2d index ." This is no longer true, since key can be used to disambiguate in the case of multiple geo indexes in the same collection.

Feel free to reach out to me with any questions and/or send a code review my way!

Impact to other docs outside of this product:

MVP:

Resources:

Engineering Ticket Description:

The geoNear command and the $geoNear agg stage currently infer the field path over which to perform the search based on the presence of a "2d" or "2dsphere" index:

https://github.com/mongodb/mongo/blob/88c39edf9275e47e5db4b1dbffb0bf51f9187731/src/mongo/db/commands/geo_near_cmd.cpp#L124-L130

The command will fail if there are multiple geo indexes.

In order to improve this behavior, we should extend the command and agg stage to accept an optional key field. This field must be a string, and will be interpreted as the field path over which to run the search. In order to avoid breaking existing applications, the existing behavior should be preserved when the key field is omitted.