====================== $geoNear (aggregation) ====================== .. default-domain:: mongodb .. contents:: On this page :local: :backlinks: none :depth: 1 :class: singlecol Definition ---------- .. pipeline:: $geoNear Outputs documents in order of nearest to farthest from a specified point. The :pipeline:`$geoNear` stage has the following prototype form: .. code-block:: javascript { $geoNear: { } } The :pipeline:`$geoNear` operator accepts a :term:`document` that contains the following :pipeline:`$geoNear` options. Specify all distances in the same units as those of the processed documents' coordinate system: .. list-table:: :header-rows: 1 :widths: 20 20 80 * - Field - Type - Description * - ``spherical`` - boolean - Determines how MongoDB calculates the distance between two points: - When ``true``, MongoDB uses :query:`$nearSphere` semantics and calculates distances using spherical geometry. - When ``false``, MongoDB uses :query:`$near` semantics: spherical geometry for :doc:`2dsphere ` indexes and planar geometry for :doc:`2d ` indexes. *Default: false.* * - ``limit`` - number - Optional. The maximum number of documents to return. The default value is ``100``. See also the ``num`` option. * - ``num`` - number - Optional. The ``num`` option provides the same function as the ``limit`` option. Both define the maximum number of documents to return. If both options are included, the ``num`` value overrides the ``limit`` value. * - ``maxDistance`` - number - Optional. The maximum distance from the center point that the documents *can* be. MongoDB limits the results to those documents that fall within the specified distance from the center point. Specify the distance in meters if the specified point is :term:`GeoJSON` and in radians if the specified point is :term:`legacy coordinate pairs `. * - ``query`` - document - Optional. Limits the results to the documents that match the query. The query syntax is the usual MongoDB :ref:`read operation query ` syntax. .. include:: /includes/fact-geoNear-restrict-near-in-query.rst * - ``distanceMultiplier`` - number - Optional. The factor to multiply all distances returned by the query. For example, use the ``distanceMultiplier`` to convert radians, as returned by a spherical query, to kilometers by multiplying by the radius of the Earth. * - ``uniqueDocs`` - boolean - Optional. If this value is ``true``, the query returns a matching document once, even if more than one of the document's location fields match the query. .. include:: /includes/deprecation-uniqueDocs.rst * - ``near`` - GeoJSON point or :term:`legacy coordinate pair ` - The point for which to find the closest documents. If using a :doc:`2dsphere ` index, you can specify the point as either a GeoJSON point or legacy coordinate pair. If using a :doc:`2d ` index, specify the point as a legacy coordinate pair. * - ``distanceField`` - string - The output field that contains the calculated distance. To specify a field within an embedded document, use :term:`dot notation`. * - ``includeLocs`` - string - Optional. This specifies the output field that identifies the location used to calculate the distance. This option is useful when a location field contains multiple locations. To specify a field within an embedded document, use :term:`dot notation`. * - ``minDistance`` - number - Optional. The minimum distance from the center point that the documents can be. MongoDB limits the results to those documents that fall outside the specified distance from the center point. Specify the distance in meters for GeoJSON data and in radians for legacy coordinate pairs. .. versionadded:: 3.2 * - ``key`` - string - Optional. Specify the geospatial indexed field to use when calculating the distance. If your collection has multiple ``2d`` and/or multiple ``2dsphere`` indexes, you **must** use the ``key`` option to specify the indexed field path to use. :ref:`pipeline-geoNear-key-param-example` provides a full example. If there is more than one ``2d`` index or more than one ``2dsphere`` index and you do not specify a ``key``, MongoDB will return an error. If you do not specify the ``key``, and you have at most only one ``2d`` index and/or only one ``2dsphere`` index, MongoDB looks first for a ``2d`` index to use. If a ``2d`` index does not exists, then MongoDB looks for a ``2dsphere`` index to use. .. versionadded:: 4.0 Behavior -------- When using :pipeline:`$geoNear`, consider that: - You can only use :pipeline:`$geoNear` as the first stage of a pipeline. - You must include the ``distanceField`` option. The ``distanceField`` option specifies the field that will contain the calculated distance. - .. include:: /includes/extracts/geoNear-stage-index-requirement.rst If you have more than one geospatial index on the collection, use the ``keys`` parameter to specify which field to use in the calculation. If you have only one geospatial index, :pipeline:`$geoNear` implicitly uses the indexed field for the calculation. .. |geoNear| replace:: :pipeline:`$geoNear` stage - .. include:: /includes/fact-geoNear-restrict-near-in-query.rst - .. include:: /includes/extracts/views-unsupported-geoNear.rst Generally, the options for :pipeline:`$geoNear` are similar to the deprecated :dbcommand:`geoNear` command with the following exceptions: - ``distanceField`` is a mandatory field for the :pipeline:`$geoNear` pipeline operator; the option does not exist in the :dbcommand:`geoNear` command. - ``includeLocs`` accepts a ``string`` in the :pipeline:`$geoNear` pipeline operator and a ``boolean`` in the :dbcommand:`geoNear` command. Examples -------- .. include:: /includes/geospatial-places-data-setup.rst Maximum Distance ~~~~~~~~~~~~~~~~ The ``places`` collection above has a ``2dsphere`` index. The following aggregation uses :pipeline:`$geoNear` to find documents with a location at most 2 meters from the center ``[ -73.99279 , 40.719296 ]`` and ``category`` equal to ``Parks``. .. code-block:: javascript db.places.aggregate([ { $geoNear: { near: { type: "Point", coordinates: [ -73.99279 , 40.719296 ] }, distanceField: "dist.calculated", maxDistance: 2, query: { type: "public" }, includeLocs: "dist.location", num: 5, spherical: true } } ]) The aggregation returns the following: .. code-block:: javascript { "_id" : 8, "name" : "Sara D. Roosevelt Park", "type" : "public", "location" : { "type" : "Point", "coordinates" : [ -73.9928, 40.7193 ] }, "dist" : { "calculated" : 0.9539931676365992, "location" : { "type" : "Point", "coordinates" : [ -73.9928, 40.7193 ] } } } The matching document contains two new fields: - ``dist.calculated`` field that contains the calculated distance, and - ``dist.location`` field that contains the location used in the calculation. Minimum Distance ~~~~~~~~~~~~~~~~ .. versionadded:: 3.2 The following example uses the option ``minDistance`` to specify the minimum distance from the center point that the documents can be. MongoDB limits the results to those documents that fall outside the specified distance from the center point. .. code-block:: javascript db.places.aggregate([ { $geoNear: { near: { type: "Point", coordinates: [ -73.99279 , 40.719296 ] }, distanceField: "dist.calculated", minDistance: 2, query: { type: "public" }, includeLocs: "dist.location", num: 5, spherical: true } } ]) .. _pipeline-geoNear-key-param-example: Specify Which Geospatial Index to Use ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionadded:: 4.0 Consider a ``places`` collection that has a :doc:`2dsphere ` index on the ``location`` field and a :doc:`2d ` index on the ``legacy`` field. A document in the ``places`` collection resembles the following: .. code-block:: javascript { "_id" : 3, "name" : "Polo Grounds", "location": { "type" : "Point", "coordinates" : [ -73.9375, 40.8303 ] }, "legacy" : [ -73.9375, 40.8303 ], "category" : "Stadiums" } The following example uses the ``keys`` option to specify that the aggregation should use the ``location`` field values for the :pipeline:`$geoNear` operation rather than the ``legacy`` field values. .. code-block:: javascript db.places.aggregate([ { $geoNear: { near: { type: "Point", coordinates: [ -73.98142 , 40.71782 ] }, key: "location", distanceField: "dist.calculated", query: { "category": "Parks" } } } ]) The aggregation returns the following: .. code-block:: javascript { "_id" : 2, "name" : "Sara D. Roosevelt Park", "location" : { "type" : "Point", "coordinates" : [ -73.9928, 40.7193 ] }, "category" : "Parks", "dist" : { "calculated" : 974.175764916902 } } { "_id" : 1, "name" : "Central Park", "location" : { "type" : "Point", "coordinates" : [ -73.97, 40.77 ] }, "legacy" : [ -73.97, 40.77 ], "category" : "Parks", "dist" : { "calculated" : 5887.92792958097 } }