mirror of https://gitee.com/bigwinds/arangodb
115 lines
5.7 KiB
Plaintext
115 lines
5.7 KiB
Plaintext
!CHAPTER Geo functions
|
|
|
|
!SECTION 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.
|
|
|
|
!SUBSECTION 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, it is undefined which of the qualifying documents are returned. Optionally,
|
|
the distances 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, in random order
|
|
|
|
!SUBSECTION 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 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, in random order
|
|
|
|
!SUBSECTION 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*).
|
|
|
|
- **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
|
|
|
|
!SECTION Geo utility functions
|
|
|
|
The following helper functions do not use any geo index.
|
|
|
|
!SUBSECTION 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 )
|
|
```
|