Geo Queries

    The ArangoDB allows to select documents based on geographic coordinates. In order for this to work, a geo-spatial index must be defined. This index will use a very elaborate algorithm to lookup neighbors that is a magnitude faster than a simple R* index.

    In general a geo coordinate is a pair of latitude and longitude, which must both be specified as numbers. A geo index can be created on coordinates that are stored in a single list attribute with two elements like [-10, +30] (latitude first, followed by longitude) or on coordinates stored in two separate attributes.

    For example, to index the following documents, an index can be created on the position attribute of the documents:

    If coordinates are stored in two distinct attributes, the index must be created on the two attributes:

    2. db.test.save({ latitude: 10, longitude: 45.5 });
    4. db.test.ensureIndex({ type: "geo", fields: [ "latitude", "longitude" ] });

    In order to find all documents within a given radius around a coordinate use the within operator. In order to find all documents near a given document use the near operator.

    It is possible to define more than one geo-spatial index per collection. In this case you must give a hint using the geo operator which of indexes should be used in a query.

    constructs a near query for a collectioncollection.near(latitude, longitude)

    The returned list is sorted according to the distance, with the nearest document to the coordinate (latitude, longitude) coming first. If there are near documents of equal distance, documents are chosen randomly from this set until the limit is reached. It is possible to change the limit using the limit operator.

    In order to use the near operator, a geo index must be defined for the collection. This index also defines which attribute holds the coordinates for the document. If you have more then one geo-spatial index, you can use the geo operator to select a particular index.

    Note: near does not support negative skips. // However, you can still use limit followed to skip.

    collection.near(latitude, longitude).limit(limit)

    Limits the result to limit documents instead of the default 100.

    Note: Unlike with multiple explicit limits, limit will raise the implicit default limit imposed by within.

    collection.near(latitude, longitude).distance()

    This will add an attribute distance to all documents returned, which contains the distance between the given point and the document in meters.

    collection.near(latitude, longitude).distance(name)

    This will add an attribute name to all documents returned, which contains the distance between the given point and the document in meters.

    Note: this method is not yet supported by the RocksDB storage engine.

    1. FOR doc IN NEAR(@@collection, @latitude, @longitude, @limit)
    2.     RETURN doc

    Examples

    To get the nearest two locations:

    1. arangosh> db.geo.ensureIndex({ type: "geo", fields: [ "loc" ] });
    2. { 
    3.   "bestIndexedLevel" : 17, 
    4.   "fields" : [ 
    5.     "loc" 
    6.   ], 
    7.   "geoJson" : false, 
    8.   "id" : "geo/234", 
    9.   "isNewlyCreated" : true, 
    10.   "maxNumCoverCells" : 8, 
    11.   "name" : "idx_1712165072828104704", 
    12.   "sparse" : true, 
    13.   "type" : "geo", 
    14.   "unique" : false, 
    15.   "worstIndexedLevel" : 4, 
    16.   "code" : 201 
    17. }
    18. arangosh> for (var i = -90;  i <= 90;  i += 10) {
    19. ........>   for (var j = -180; j <= 180; j += 10) {
    20. ........>     db.geo.save({
    21. ........>        name : "Name/" + i + "/" + j,
    22. ........>        loc: [ i, j ] });
    23. ........> } }
    24. arangosh> db.geo.near(0, 0).limit(2).toArray();
    25. [ 
    26.   { 
    27.     "_key" : "940", 
    28.     "_id" : "geo/940", 
    29.     "_rev" : "_dAzO94u---", 
    30.     "name" : "Name/0/0", 
    31.     "loc" : [ 
    32.       0, 
    33.       0 
    34.     ] 
    35.   }, 
    36.   { 
    37.     "_key" : "1014", 
    38.     "_id" : "geo/1014", 
    39.     "_rev" : "_dAzO95a---", 
    40.     "name" : "Name/10/0", 
    41.     "loc" : [ 
    42.       10, 
    43.       0 
    44.     ] 
    45.   } 
    46. ]

    Hide execution results

    Show execution results

    If you need the distance as well, then you can use the distance operator:

    1. arangosh> db.geo.ensureIndex({ type: "geo", fields: [ "loc" ] });
    2. { 
    3.   "bestIndexedLevel" : 17, 
    4.   "fields" : [ 
    5.     "loc" 
    6.   ], 
    7.   "geoJson" : false, 
    8.   "id" : "geo/1656", 
    9.   "isNewlyCreated" : true, 
    10.   "maxNumCoverCells" : 8, 
    11.   "name" : "idx_1712165073088151552", 
    12.   "sparse" : true, 
    13.   "type" : "geo", 
    14.   "unique" : false, 
    15.   "worstIndexedLevel" : 4, 
    16.   "code" : 201 
    17. }
    18. arangosh> for (var i = -90;  i <= 90;  i += 10) {
    19. ........>  for (var j = -180; j <= 180; j += 10) {
    20. ........>     db.geo.save({
    21. ........>         name : "Name/" + i + "/" + j,
    22. ........>         loc: [ i, j ] });
    23. ........> } }
    24. arangosh> db.geo.near(0, 0).distance().limit(2).toArray();
    25. [ 
    26.   { 
    27.     "_id" : "geo/2362", 
    28.     "_key" : "2362", 
    29.     "_rev" : "_dAzP-Gy--C", 
    30.     "loc" : [ 
    31.       0, 
    32.       0 
    33.     ], 
    34.     "name" : "Name/0/0", 
    35.     "distance" : 0 
    36.   }, 
    37.   { 
    38.     "_id" : "geo/2436", 
    39.     "_key" : "2436", 
    40.     "_rev" : "_dAzP-Hm--E", 
    41.     "loc" : [ 
    42.       10, 
    43.       0 
    44.     ], 
    45.     "name" : "Name/10/0", 
    46.     "distance" : 1111949.2664455872 
    47.   } 
    48. ]

    Hide execution results

    1. arangosh> db.geo.ensureIndex({ type: "geo", fields: [ "loc" ] });
    2. arangosh> for (var i = -90;  i <= 90;  i += 10) {
    3. ........>  for (var j = -180; j <= 180; j += 10) {
    4. ........>     db.geo.save({
    6. ........> } }
    7. arangosh> db.geo.near(0, 0).distance().limit(2).toArray();

    Show execution results

    constructs a within query for a collectioncollection.within(latitude, longitude, radius)

    This will find all documents within a given radius around the coordinate (latitude, longitude). The returned array is sorted by distance, beginning with the nearest document.

    In order to use the within operator, a geo index must be defined for the collection. This index also defines which attribute holds the coordinates for the document. If you have more then one geo-spatial index, you can use the geo operator to select a particular index.

    collection.within(latitude, longitude, radius).distance()

    This will add an attribute _distance to all documents returned, which contains the distance between the given point and the document in meters.

    collection.within(latitude, longitude, radius).distance(name)

    This will add an attribute name to all documents returned, which contains the distance between the given point and the document in meters.

    Note: this method is not yet supported by the RocksDB storage engine.

    Note: the within simple query function is deprecated as of ArangoDB 2.6. The function may be removed in future versions of ArangoDB. The preferred way for retrieving documents from a collection using the within operator is to use the AQL WITHIN function in an AQL query as follows:

    1. FOR doc IN WITHIN(@@collection, @latitude, @longitude, @radius, @distanceAttributeName)
    2.     RETURN doc

    Examples

    To find all documents within a radius of 2000 km use:

    1. arangosh> for (var i = -90;  i <= 90;  i += 10) {
    2. ........>  for (var j = -180; j <= 180; j += 10) {
    3. ........> db.geo.save({ name : "Name/" + i + "/" + j, loc: [ i, j ] }); } }
    4. arangosh> db.geo.within(0, 0, 2000 * 1000).distance().toArray();

    Show execution results

    constructs a geo index selectioncollection.geo(location-attribute)

    Looks up a geo index defined on attribute location_attribute.

    Returns a geo index object if an index was found. The near or within operators can then be used to execute a geo-spatial query on this particular index.

    This is useful for collections with multiple defined geo indexes.

    collection.geo(location_attribute, true)

    Looks up a geo index on a compound attribute location_attribute.

    Returns a geo index object if an index was found. The near or within operators can then be used to execute a geo-spatial query on this particular index.

    collection.geo(latitude_attribute, longitude_attribute)

    Looks up a geo index defined on the two attributes latitude_attribute and longitude-attribute.

    Returns a geo index object if an index was found. The near or within operators can then be used to execute a geo-spatial query on this particular index.

    Note: this method is not yet supported by the RocksDB storage engine.

    Note: the geo simple query helper function is deprecated as of ArangoDB 2.6. The function may be removed in future versions of ArangoDB. The preferred way for running geo queries is to use their AQL equivalents.

    Examples

    Assume you have a location stored as list in the attribute home and a destination stored in the attribute work. Then you can use the geo operator to select which geo-spatial attributes (and thus which index) to use in a near query.

    1. arangosh> for (i = -90;  i <= 90;  i += 10) {
    2. ........>  for (j = -180;  j <= 180;  j += 10) {
    3. ........>    db.complex.save({ name : "Name/" + i + "/" + j,
    4. ........>                      home : [ i, j ],
    5. ........>                      work : [ -i, -j ] });
    6. ........>  }
    7. ........> }
    8. ........> 
    9. arangosh> db.complex.near(0, 170).limit(5);
    10. [ArangoError 1570: no suitable geo index found for geo restriction on 'complex']
    11. arangosh> db.complex.ensureIndex({ type: "geo", fields: [ "home" ] });
    12. { 
    13.   "bestIndexedLevel" : 17, 
    14.   "fields" : [ 
    15.     "home" 
    16.   ], 
    17.   "geoJson" : false, 
    18.   "id" : "complex/89170", 
    19.   "isNewlyCreated" : true, 
    20.   "maxNumCoverCells" : 8, 
    21.   "name" : "idx_1712165134763294720", 
    22.   "sparse" : true, 
    23.   "type" : "geo", 
    24.   "unique" : false, 
    25.   "worstIndexedLevel" : 4, 
    26.   "code" : 201 
    27. }
    28. arangosh> db.complex.near(0, 170).limit(5).toArray();
    29. [ 
    30.   { 
    31.     "_key" : "88499", 
    32.     "_id" : "complex/88499", 
    33.     "_rev" : "_dAzP3Xm--I", 
    34.     "name" : "Name/0/170", 
    35.     "home" : [ 
    36.       0, 
    37.       170 
    38.     ], 
    39.     "work" : [ 
    40.       0, 
    41.       -170 
    42.     ] 
    43.   }, 
    44.   { 
    45.     "_key" : "88501", 
    46.     "_id" : "complex/88501", 
    47.     "_rev" : "_dAzP3Xm--K", 
    48.     "name" : "Name/0/180", 
    49.     "home" : [ 
    50.       0, 
    51.       180 
    52.     ], 
    53.     "work" : [ 
    54.       0, 
    55.       -180 
    56.     ] 
    57.   }, 
    58.   { 
    59.     "_key" : "88573", 
    60.     "_id" : "complex/88573", 
    61.     "_rev" : "_dAzP3YC--E", 
    62.     "name" : "Name/10/170", 
    63.     "home" : [ 
    64.       10, 
    65.       170 
    66.     ], 
    67.     "work" : [ 
    68.       -10, 
    69.       -170 
    70.     ] 
    71.   }, 
    72.   { 
    73.     "_key" : "88425", 
    74.     "_id" : "complex/88425", 
    75.     "_rev" : "_dAzP3XC--C", 
    76.     "name" : "Name/-10/170", 
    77.     "home" : [ 
    78.       -10, 
    79.       170 
    80.     ], 
    81.     "work" : [ 
    82.       10, 
    83.       -170 
    84.     ] 
    85.   }, 
    86.   { 
    87.     "_key" : "88429", 
    88.     "_id" : "complex/88429", 
    89.     "_rev" : "_dAzP3XG---", 
    90.     "name" : "Name/0/-180", 
    92.       0, 
    93.       -180 
    94.     ], 
    95.     "work" : [ 
    96.       0, 
    97.       180 
    98.     ] 
    99.   } 
    100. arangosh> db.complex.geo("work").near(0, 170).limit(5);
    101. [ArangoError 1570: no suitable geo index found for geo restriction on 'complex']
    102. arangosh> db.complex.ensureIndex({ type: "geo", fields: [ "work" ] });
    103. { 
    104.   "bestIndexedLevel" : 17, 
    105.   "fields" : [ 
    106.     "work" 
    107.   ], 
    108.   "geoJson" : false, 
    109.   "id" : "complex/89180", 
    110.   "isNewlyCreated" : true, 
    111.   "maxNumCoverCells" : 8, 
    112.   "name" : "idx_1712165134769586176", 
    113.   "sparse" : true, 
    114.   "type" : "geo", 
    115.   "unique" : false, 
    116.   "worstIndexedLevel" : 4, 
    117.   "code" : 201 
    118. }
    119. arangosh> db.complex.geo("work").near(0, 170).limit(5).toArray();
    120. [ 
    121.   { 
    122.     "_key" : "88499", 
    123.     "_id" : "complex/88499", 
    124.     "_rev" : "_dAzP3Xm--I", 
    125.     "name" : "Name/0/170", 
    126.     "home" : [ 
    127.       0, 
    128.       170 
    129.     ], 
    130.     "work" : [ 
    131.       0, 
    132.       -170 
    133.     ] 
    134.   }, 
    135.   { 
    136.     "_key" : "88501", 
    137.     "_id" : "complex/88501", 
    138.     "_rev" : "_dAzP3Xm--K", 
    139.     "name" : "Name/0/180", 
    140.     "home" : [ 
    141.       0, 
    142.       180 
    143.     ], 
    144.     "work" : [ 
    145.       0, 
    146.       -180 
    147.     ] 
    148.   }, 
    149.   { 
    150.     "_key" : "88573", 
    151.     "_id" : "complex/88573", 
    152.     "_rev" : "_dAzP3YC--E", 
    153.     "name" : "Name/10/170", 
    154.     "home" : [ 
    155.       10, 
    156.       170 
    157.     ], 
    158.     "work" : [ 
    159.       -10, 
    160.       -170 
    161.     ] 
    162.   }, 
    163.   { 
    164.     "_key" : "88425", 
    165.     "_id" : "complex/88425", 
    166.     "_rev" : "_dAzP3XC--C", 
    167.     "name" : "Name/-10/170", 
    168.     "home" : [ 
    169.       -10, 
    170.       170 
    171.     ], 
    172.     "work" : [ 
    173.       10, 
    174.       -170 
    175.     ] 
    176.   }, 
    177.   { 
    178.     "_key" : "88429", 
    179.     "_id" : "complex/88429", 
    180.     "_rev" : "_dAzP3XG---", 
    181.     "name" : "Name/0/-180", 
    182.     "home" : [ 
    183.       0, 
    184.       -180 
    185.     ], 
    186.     "work" : [ 
    187.       0, 
    188.       180 
    189.     ] 
    190.   } 
    191. ]

    Hide execution results

    1. arangosh> for (i = -90;  i <= 90;  i += 10) {
    2. ........>  for (j = -180;  j <= 180;  j += 10) {
    3. ........>    db.complex.save({ name : "Name/" + i + "/" + j,
    4. ........>                      home : [ i, j ],
    5. ........>                      work : [ -i, -j ] });
    6. ........>  }
    7. ........> }
    8. ........> 
    9. arangosh> db.complex.near(0, 170).limit(5);
    10. arangosh> db.complex.ensureIndex({ type: "geo", fields: [ "home" ] });
    11. arangosh> db.complex.near(0, 170).limit(5).toArray();
    12. arangosh> db.complex.geo("work").near(0, 170).limit(5);
    13. arangosh> db.complex.ensureIndex({ type: "geo", fields: [ "work" ] });

    Show execution results

    Other ArangoDB geographic features are described in: