mirror of https://gitee.com/bigwinds/arangodb
150 lines
7.3 KiB
Plaintext
150 lines
7.3 KiB
Plaintext
Geo functions
|
|
=============
|
|
|
|
Geo index functions
|
|
-------------------
|
|
|
|
AQL offers the following functions to filter data based on
|
|
[geo indexes](../../Manual/Indexing/Geo.html). These functions require the collection to have at
|
|
least one geo index. If no geo index can be found, calling this function will fail
|
|
with an error at runtime. There is no error when explaining the query however.
|
|
|
|
### NEAR()
|
|
|
|
`NEAR(coll, latitude, longitude, limit, distanceName) → docArray`
|
|
|
|
Return at most *limit* documents from collection *coll* that are near *latitude*
|
|
and *longitude*. The result contains at most *limit* documents, returned sorted by
|
|
distance, with closest distances being returned first. If more than *limit* documents
|
|
qualify, with the distance being exactly the same among multiple documents around the
|
|
limit, it is undefined which of the qualifying documents are returned. Optionally,
|
|
the distances in meters between the specified coordinate (*latitude* and *longitude*)
|
|
and the document coordinates can be returned as well. To make use of that, the desired
|
|
attribute name for the distance result has to be specified in the *distanceName* argument.
|
|
The result documents will contain the distance value in an attribute of that name.
|
|
|
|
- **coll** (collection): a collection
|
|
- **latitude** (number): the latitude portion of the search coordinate
|
|
- **longitude** (number): the longitude portion of the search coordinate
|
|
- **limit** (number, *optional*): cap the result to at most this number of documents.
|
|
The default is 100. If more documents than *limit* are found, it is undefined which
|
|
ones will be returned.
|
|
- **distanceName** (string, *optional*): include the distance to the search coordinate
|
|
in each document in the result (in meters), using the attribute name *distanceName*
|
|
- returns **docArray** (array): an array of documents, sorted by distance (shortest
|
|
distance first)
|
|
|
|
### WITHIN()
|
|
|
|
`WITHIN(coll, latitude, longitude, radius, distanceName) → docArray`
|
|
|
|
Return all documents from collection *coll* that are within a radius of *radius*
|
|
around the specified coordinate (*latitude* and *longitude*). The documents returned
|
|
are sorted by distance to the search coordinate, with the closest distances being
|
|
returned first. Optionally, the distance in meters between the search coordinate and
|
|
the document coordinates can be returned as well. To make use of that, an attribute
|
|
name for the distance result has to be specified in the *distanceName* argument.
|
|
The result documents will contain the distance value in an attribute of that name.
|
|
|
|
- **coll** (collection): a collection
|
|
- **latitude** (number): the latitude portion of the search coordinate
|
|
- **longitude** (number): the longitude portion of the search coordinate
|
|
- **radius** (number): radius in meters
|
|
- **distanceName** (string, *optional*): include the distance to the search coordinate
|
|
in each document in the result (in meters), using the attribute name *distanceName*
|
|
- returns **docArray** (array): an array of documents, sorted by distance (shortest
|
|
distance first)
|
|
|
|
### WITHIN_RECTANGLE()
|
|
|
|
`WITHIN_RECTANGLE(coll, latitude1, longitude1, latitude2, longitude2) → docArray`
|
|
|
|
Return all documents from collection *coll* that are positioned inside the bounding
|
|
rectangle with the points (*latitude1*, *longitude1*) and (*latitude2*, *longitude2*).
|
|
There is no guaranteed order in which the documents are returned.
|
|
|
|
- **coll** (collection): a collection
|
|
- **latitude1** (number): the bottom-left latitude portion of the search coordinate
|
|
- **longitude1** (number): the bottom-left longitude portion of the search coordinate
|
|
- **latitude2** (number): the top-right latitude portion of the search coordinate
|
|
- **longitude2** (number): the top-right longitude portion of the search coordinate
|
|
- returns **docArray** (array): an array of documents, in random order
|
|
|
|
Geo utility functions
|
|
---------------------
|
|
|
|
The following helper functions do **not use any geo index**. On large datasets,
|
|
it is advisable to use them in combination with index-accelerated geo functions
|
|
to limit the number of calls to these non-accelerated functions because of their
|
|
computational costs.
|
|
|
|
### DISTANCE()
|
|
|
|
`DISTANCE(latitude1, longitude1, latitude2, longitude2) → distance`
|
|
|
|
Calculate the distance between two arbitrary coordinates in meters (as birds
|
|
would fly). The value is computed using the haversine formula, which is based
|
|
on a spherical Earth model. It's fast to compute and is accurate to around 0.3%,
|
|
which is sufficient for most use cases such as location-aware services.
|
|
|
|
- **latitude1** (number): the latitude portion of the first coordinate
|
|
- **longitude1** (number): the longitude portion of the first coordinate
|
|
- **latitude2** (number): the latitude portion of the second coordinate
|
|
- **longitude2** (number): the longitude portion of the second coordinate
|
|
- returns **distance** (number): the distance between both coordinates in meters
|
|
|
|
```js
|
|
// Distance between Brandenburg Gate (Berlin) and ArangoDB headquarters (Cologne)
|
|
DISTANCE(52.5163, 13.3777, 50.9322, 6.94) // 476918.89688380965 (~477km)
|
|
|
|
// Sort a small number of documents based on distance to Central Park (New York)
|
|
FOR doc IN documentSubset // e.g. documents returned by a traversal
|
|
SORT DISTANCE(doc.latitude, doc.longitude, 40.78, -73.97)
|
|
RETURN doc
|
|
```
|
|
|
|
### IS_IN_POLYGON()
|
|
|
|
Determine whether a coordinate is inside a polygon.
|
|
|
|
`IS_IN_POLYGON(polygon, latitude, longitude) → bool`
|
|
|
|
- **polygon** (array): an array of arrays with 2 elements each, representing the
|
|
points of the polygon in the format *[lat, lon]*
|
|
- **latitude** (number): the latitude portion of the search coordinate
|
|
- **longitude** (number): the longitude portion of the search coordinate
|
|
- returns **bool** (bool): *true* if the point (*latitude*, *longitude*) is inside the
|
|
*polygon* or *false* if it's not. The result is undefined (can be *true* or *false*)
|
|
if the specified point is exactly on a boundary of the polygon.
|
|
|
|
```js
|
|
// will check if the point (lat 4, lon 7) is contained inside the polygon
|
|
IS_IN_POLYGON( [ [ 0, 0 ], [ 0, 10 ], [ 10, 10 ], [ 10, 0 ] ], 4, 7 )
|
|
```
|
|
|
|
`IS_IN_POLYGON(polygon, coord, useLonLat) → bool`
|
|
|
|
The 2nd parameter can alternatively be specified as an array with two values.
|
|
|
|
By default, each array element in *polygon* is expected to be in the format *[lat, lon]*.
|
|
This can be changed by setting the 3rd parameter to *true* to interpret the points as
|
|
*[lon, lat]*. *coord* will then also be interpreted in the same way.
|
|
|
|
- **polygon** (array): an array of arrays with 2 elements each, representing the
|
|
points of the polygon
|
|
- **coord** (array): the search coordinate as a number array with two elements
|
|
- **useLonLat** (bool, *optional*): if set to *true*, the coordinates in *polygon* and
|
|
the search coordinate *coord* will be interpreted as *[lon, lat]*. The default is
|
|
*false* and the format *[lat, lon]* is expected.
|
|
- returns **bool** (bool): *true* if the point *coord* is inside the *polygon* or
|
|
*false* if it's not. The result is undefined (can be *true* or *false*) if the
|
|
specified point is exactly on a boundary of the polygon.
|
|
|
|
```js
|
|
// will check if the point (lat 4, lon 7) is contained inside the polygon
|
|
IS_IN_POLYGON( [ [ 0, 0 ], [ 0, 10 ], [ 10, 10 ], [ 10, 0 ] ], [ 4, 7 ] )
|
|
|
|
// will check if the point (lat 4, lon 7) is contained inside the polygon
|
|
IS_IN_POLYGON( [ [ 0, 0 ], [ 10, 0 ], [ 10, 10 ], [ 0, 10 ] ], [ 7, 4 ], true )
|
|
```
|