Geospatial Queries

    MongoDB supports query operations on geospatial data. This section introduces MongoDB’s geospatial features.

    In MongoDB, you can store geospatial data asGeoJSONobjects or as.

    To calculate geometry over an Earth-like sphere, store your location data asGeoJSON objects.

    To specify GeoJSON data, use an embedded document with:

    • a field namedtypethat specifies theand

    • a field namedcoordinatesthat specifies the object’s coordinates.

      If specifying latitude and longitude coordinates, list thelongitudefirst and thenlatitude:

      • Valid longitude values are between
        -180
        and
        180
        , both inclusive.
      • Valid latitude values are between
        -90
        and
        90
        (both inclusive).

    For example, to specify aGeoJSON Point:

    1. location
    2. :
    3. {
    4. type
    5. :
    6. "Point"
    7. ,
    8. coordinates
    9. :
    10. [
    11. -
    12. 73.856077
    13. ,
    14. 40.848447
    15. ]
    16. }

    For a list of the GeoJSON objects supported in MongoDB as well as examples, see.

    MongoDB geospatial queries on GeoJSON objects calculate on a sphere; MongoDB uses theWGS84reference system for geospatial queries on GeoJSON objects.

    Legacy Coordinate Pairs

    To calculate distances on a Euclidean plane, store your location data as legacy coordinate pairs and use aindex. MongoDB supports spherical surface calculations on legacy coordinate pairs via a2dsphereindex by converting the data to the GeoJSON Point type.

    To specify data as legacy coordinate pairs, you can use either an array (preferred) or an embedded document.

    Specify via an array (

    Preferred

    ):

    1. <
    2. field
    3. >
    4. :
    5. [
    6. <
    7. x
    8. >
    9. ,
    10. <
    11. y
    12. >
    13. ]

    If specifying latitude and longitude coordinates, list thelongitudefirst and thenlatitude; i.e.

    1. <
    2. field
    3. >
    4. :
    5. [
    6. <
    7. longitude
    8. >
    9. ,
    10. <
    11. latitude
    12. >
    13. ]
    • Valid longitude values are between
      -180
      and
      180
      , both inclusive.
    • Valid latitude values are between
      -90
      and
      90
      (both inclusive).

    Specify via an embedded document:

    If specifying latitude and longitude coordinates, the first field, regardless of the field name, must contains thelongitudevalue and the second field, thelatitudevalue ; i.e.

    1. <
    2. field
    3. :
    4. {
    5. <
    6. field1
    7. >
    8. :
    9. <
    10. longitude
    11. >
    12. ,
    13. <
    14. field2
    15. >
    16. :
    17. <
    18. latitude
    19. >
    20. }
    • Valid longitude values are between
      -180
      and
      180
      , both inclusive.
    • Valid latitude values are between
      -90
      and
      90
      (both inclusive).

    To specify legacy coordinate pairs, arrays are preferred over an embedded document as some languages do not guarantee associative map ordering.

    MongoDB provides the following geospatial index types to support the geospatial queries.

    2dsphere

    indexes support queries that calculategeometries on an earth-like sphere.

    To create a2dsphereindex, use themethod and specify the string literal"2dsphere"as the index type:

    1. db
    2. .
    3. collection
    4. .
    5. createIndex
    6. (
    7. {
    9. location
    10. field
    11. >
    12. :
    13. "2dsphere"
    14. }
    15. )

    where the<locationfield>is a field whose value is either aGeoJSON objector a.

    For more information on the2dsphereindex, see2dsphere Indexes.

    indexes support queries that calculategeometries on a two-dimensional plane. Although the index can supportqueries that calculate on a sphere, if possible, use the2dsphereindex for spherical queries.

    To create a2dindex, use themethod, specifying the location field as the key and the string literal"2d"as the index type:

    1. db
    2. .
    3. collection
    4. .
    5. createIndex
    6. (
    7. {
    8. <
    9. location
    10. field
    11. >
    12. :
    13. "2d"
    14. }
    15. )

    where the<locationfield>is a field whose value is alegacy coordinates pair.

    For more information on the2dindex, see.

    Geospatial Indexes and Sharded Collections

    You cannot use a geospatial index as ashard keywhen sharding a collection. However, you can create a geospatial index on a sharded collection by using a different field as the shard key.

    For sharded collections, queries usingand$nearSphereare not supported. You can instead use either thecommand or the$geoNearaggregation stage.

    You can also query for geospatial data for a sharded cluster usingand$geoIntersect.

    Covered Queries

    Ageospatial indexescannot.

    For spherical queries, use the2dsphereindex result.

    The use of2dindex for spherical queries may lead to incorrect results, such as the use of the2dindex for spherical queries that wrap around the poles.

    MongoDB provides the following geospatial query operators:

    For more details, including examples, see the individual reference page.

    Geospatial Command

    MongoDB provides the following geospatial command:

    For more details, including examples, seegeoNearreference page.

    Geospatial Aggregation Stage

    MongoDB provides the following geospatial:

    For more details, including examples, see$geoNearreference page.

    MongoDB geospatial queries can interpret geometry on a flat surface or a sphere.

    2dsphereindexes support only spherical queries (i.e. queries that interpret geometries on a spherical surface).

    2dindexes support flat queries (i.e. queries that interpret geometries on a flat surface) and some spherical queries. While2dindexes support some spherical queries, the use of2dindexes for these spherical queries can result in error. If possible, use2dsphereindexes for spherical queries.

    The following table lists the geospatial query operators, supported query, used by each geospatial operations:

    Create a collectionplaceswith the following documents:

    The following operation creates a2dsphereindex on thelocationfield:

    1. db
    3. places
    4. .
    5. createIndex
    6. (
    7. {
    8. location
    9. :
    10. "2dsphere"
    11. }
    12. )

    The following query uses theoperator to return documents that are at least 1000 meters from and at most 5000 meters from the specified GeoJSON point, sorted in order from nearest to farthest:

    1. db
    2. .
    3. places
    4. .
    5. find
    6. (
    7. {
    8. :
    9. {
    10. $near
    11. :
    12. {
    13. $geometry
    14. :
    15. {
    16. type
    17. :
    18. "Point"
    19. ,
    20. coordinates
    21. :
    22. [
    23. -
    24. 73.9667
    25. ,
    26. 40.78
    27. ]
    28. },
    29. $minDistance
    30. :
    31. 1000
    32. ,
    33. $maxDistance
    34. :
    35. 5000
    36. }
    37. }
    38. }
    39. )

    The following operation uses thegeoNearcommand to return documents that match the query filter{category:"Parks"}, sorted in order of nearest to farthest to the specified GeoJSON point:

    1. db
    2. .
    3. runCommand
    4. (
    5. {
    6. geoNear
    7. :
    8. "places"
    9. ,
    10. near
    11. :
    12. {
    13. type
    14. :
    15. "Point"
    16. ,
    17. coordinates
    18. :
    19. [
    20. -
    21. 73.9667
    22. ,
    23. 40.78
    24. ]
    25. },
    26. spherical
    27. :
    28. true
    29. ,
    30. query
    31. :
    32. {
    33. category
    34. :
    35. "Parks"
    36. }