Skip to content

DOC-772 | GEO_POINT() accepts elevation but z coordinate is ignored in geo functions #733

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

DOC-772 | GEO_POINT() accepts elevation but z coordinate is ignored in geo functions #733

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3a718f5
GEO_POINT() accepts elevation but z coordinate is ignored in geo func…
Simran-B Jul 2, 2025
a84931e
Add more details
Simran-B Jul 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
213 changes: 116 additions & 97 deletions site/content/3.12/aql/functions/geo.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,9 +71,9 @@ called `location` (with coordinates in `[longitude, latitude]` order):
GeoJSON uses a geographic coordinate reference system,
World Geodetic System 1984 (WGS 84), and units of decimal degrees.

Internally ArangoDB maps all coordinate pairs onto a unit sphere. Distances are
projected onto a sphere with the Earth's *Volumetric mean radius* of *6371
km*. ArangoDB implements a useful subset of the GeoJSON format
Internally, ArangoDB maps all coordinate pairs onto a unit sphere. Distances are
projected onto a sphere with the Earth's *Volumetric mean radius* of
*6371 km*. ArangoDB implements a useful subset of the GeoJSON format
[(RFC 7946)](https://tools.ietf.org/html/rfc7946).
Feature Objects and the GeometryCollection type are not supported.
Supported geometry object types are:
Expand All @@ -98,6 +98,18 @@ a longitude and a latitude:
}
```

GeoJSON Points can optionally have a third coordinate for the elevation, but
ArangoDB doesn't use it in calculations:

```json
{
"location": {
"type": "Point",
"coordinates": [ 100.0, 0.0, 43.0 ]
}
}
```

#### MultiPoint

A [GeoJSON MultiPoint](https://tools.ietf.org/html/rfc7946#section-3.1.7) is
Expand Down Expand Up @@ -425,11 +437,11 @@ fully contains `geoJsonB` (every point in B is also in A). The object `geoJsonA`
has to be of type _Polygon_ or _MultiPolygon_. For other types containment is
not well-defined because of numerical stability problems.

- **geoJsonA** (object): first GeoJSON object
- **geoJsonB** (object): second GeoJSON object, or a coordinate array in
`[longitude, latitude]` order
- **geoJsonA** (object): First GeoJSON object.
- **geoJsonB** (object): Second GeoJSON object, or a coordinate array in
`[longitude, latitude]` order.
- returns **bool** (bool): `true` if every point in B is also contained in A,
otherwise `false`
otherwise `false`.

{{< info >}}
ArangoDB follows and exposes the same behavior as the underlying
Expand Down Expand Up @@ -468,14 +480,14 @@ Return the distance between two GeoJSON objects in meters, measured from the
**centroid** of each shape. For a list of supported types see the
[geo index page](#geojson).

- **geoJsonA** (object): first GeoJSON object, or a coordinate array in
`[longitude, latitude]` order
- **geoJsonB** (object): second GeoJSON object, or a coordinate array in
`[longitude, latitude]` order
- **ellipsoid** (string, *optional*): reference ellipsoid to use.
- **geoJsonA** (object): First GeoJSON object, or a coordinate array in
`[longitude, latitude]` order.
- **geoJsonB** (object): Second GeoJSON object, or a coordinate array in
`[longitude, latitude]` order.
- **ellipsoid** (string, *optional*): Reference ellipsoid to use.
Supported are `"sphere"` (default) and `"wgs84"`.
- returns **distance** (number): the distance between the centroid points of
the two objects on the reference ellipsoid in **meters**
- returns **distance** (number): The distance between the centroid points of
the two objects on the reference ellipsoid in **meters**.

```aql
LET polygon = {
Expand Down Expand Up @@ -522,10 +534,10 @@ functions.
Return the area for a [Polygon](#polygon) or [MultiPolygon](#multipolygon)
on a sphere with the average Earth radius, or an ellipsoid.

- **geoJson** (object): a GeoJSON object
- **ellipsoid** (string, *optional*): reference ellipsoid to use.
- **geoJson** (object): A GeoJSON object.
- **ellipsoid** (string, *optional*): Reference ellipsoid to use.
Supported are `"sphere"` (default) and `"wgs84"`.
- returns **area** (number): the area of the polygon in **square meters**
- returns **area** (number): The area of the polygon in **square meters**.

```aql
LET polygon = {
Expand All @@ -541,8 +553,8 @@ RETURN GEO_AREA(polygon, "wgs84")

Checks whether two [GeoJSON objects](#geojson) are equal or not.

- **geoJsonA** (object): first GeoJSON object.
- **geoJsonB** (object): second GeoJSON object.
- **geoJsonA** (object): First GeoJSON object.
- **geoJsonB** (object): Second GeoJSON object.
- returns **bool** (bool): `true` if they are equal, otherwise `false`.

```aql
Expand Down Expand Up @@ -572,10 +584,10 @@ RETURN GEO_EQUALS(polygonA, polygonB) // false
Checks whether the [GeoJSON object](#geojson) `geoJsonA`
intersects with `geoJsonB` (i.e. at least one point in B is also in A or vice-versa).

- **geoJsonA** (object): first GeoJSON object
- **geoJsonB** (object): second GeoJSON object, or a coordinate array in
`[longitude, latitude]` order
- returns **bool** (bool): true if B intersects A, false otherwise
- **geoJsonA** (object): First GeoJSON object.
- **geoJsonB** (object): Second GeoJSON object, or a coordinate array in
`[longitude, latitude]` order.
- returns **bool** (bool): `true` if B intersects A, `false` otherwise.

You can optimize queries that contain a `FILTER` expression of the following
form with an S2-based [geospatial index](../../index-and-search/indexing/working-with-indexes/geo-spatial-indexes.md):
Expand Down Expand Up @@ -604,19 +616,19 @@ Checks whether the distance between two [GeoJSON objects](#geojson)
lies within a given interval. The distance is measured from the **centroid** of
each shape.

- **geoJsonA** (object\|array): first GeoJSON object, or a coordinate array
in `[longitude, latitude]` order
- **geoJsonB** (object\|array): second GeoJSON object, or a coordinate array
in `[longitude, latitude]` order
- **low** (number): minimum value of the desired range
- **high** (number): maximum value of the desired range
- **includeLow** (bool, optional): whether the minimum value shall be included
- **geoJsonA** (object\|array): First GeoJSON object, or a coordinate array
in `[longitude, latitude]` order.
- **geoJsonB** (object\|array): Second GeoJSON object, or a coordinate array
in `[longitude, latitude]` order.
- **low** (number): Minimum value of the desired range.
- **high** (number): Maximum value of the desired range.
- **includeLow** (bool, optional): Whether the minimum value shall be included
in the range (left-closed interval) or not (left-open interval). The default
value is `true`
- **includeHigh** (bool): whether the maximum value shall be included in the
value is `true`.
- **includeHigh** (bool): Whether the maximum value shall be included in the
range (right-closed interval) or not (right-open interval). The default value
is `true`
- returns **bool** (bool): whether the evaluated distance lies within the range
is `true`.
- returns **bool** (bool): Whether the evaluated distance lies within the range.

### IS_IN_POLYGON()

Expand All @@ -630,10 +642,10 @@ favor of the new [`GEO_CONTAINS()` AQL function](#geo_contains), which works wit

`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 `[latitude, longitude]`
- **latitude** (number): the latitude of the point to search
- **longitude** (number): the longitude of the point to search
- **polygon** (array): An array of arrays with two elements each, representing the
points of the polygon in the format `[latitude, longitude]`.
- **latitude** (number): The latitude of the point to search for.
- **longitude** (number): The longitude of the point to search for.
- 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
Expand All @@ -648,17 +660,17 @@ 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.
The second 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
`[latitude, longitude]`. This can be changed by setting the 3rd parameter to `true` to
`[latitude, longitude]`. This can be changed by setting the third parameter to `true` to
interpret the points as `[longitude, latitude]`. `coord` is then also interpreted in
the same way.

- **polygon** (array): an array of arrays with 2 elements each, representing the
points of the polygon
- **coord** (array): the point to search as a numeric array with two elements
- **useLonLat** (bool, *optional*): if set to `true`, the coordinates in
- **polygon** (array): An array of arrays with 2 elements each, representing the
points of the polygon.
- **coord** (array): The point to search as a numeric array with two elements.
- **useLonLat** (bool, *optional*): If set to `true`, the coordinates in
`polygon` and the coordinate pair `coord` are interpreted as
`[longitude, latitude]` (like in GeoJSON). The default is `false` and the
format `[latitude, longitude]` is expected.
Expand Down Expand Up @@ -687,8 +699,9 @@ will help you to make all your AQL queries shorter and easier to read.
Construct a GeoJSON LineString.
Needs at least two longitude/latitude pairs.

- **points** (array): an array of `[longitude, latitude]` pairs
- returns **geoJson** (object): a valid GeoJSON LineString
- **points** (array): An array of `[longitude, latitude]` pairs, or optionally
`[longitude, latitude, elevation]`.
- returns **geoJson** (object): A valid GeoJSON LineString.

```aql
---
Expand All @@ -707,8 +720,9 @@ RETURN GEO_LINESTRING([
Construct a GeoJSON MultiLineString.
Needs at least two elements consisting valid LineStrings coordinate arrays.

- **points** (array): array of LineStrings
- returns **geoJson** (object): a valid GeoJSON MultiLineString
- **points** (array): An array of arrays of `[longitude, latitude]` pairs,
or optionally `[longitude, latitude, elevation]`.
- returns **geoJson** (object): A valid GeoJSON MultiLineString.

```aql
---
Expand All @@ -727,8 +741,9 @@ RETURN GEO_MULTILINESTRING([

Construct a GeoJSON LineString. Needs at least two longitude/latitude pairs.

- **points** (array): an array of `[longitude, latitude]` pairs
- returns **geoJson** (object): a valid GeoJSON Point
- **points** (array): An array of `[longitude, latitude]` pairs, or optionally
`[longitude, latitude, elevation]`.
- returns **geoJson** (object): A valid GeoJSON Point.

```aql
---
Expand All @@ -742,13 +757,15 @@ RETURN GEO_MULTIPOINT([

### GEO_POINT()

`GEO_POINT(longitude, latitude) → geoJson`
`GEO_POINT(longitude, latitude, elevation) → geoJson`

Construct a valid GeoJSON Point.

- **longitude** (number): the longitude portion of the point
- **latitude** (number): the latitude portion of the point
- returns **geoJson** (object): a GeoJSON Point
- **longitude** (number): The longitude portion of the point.
- **latitude** (number): The latitude portion of the point.
- **elevation** (number, *optional*): The elevation portion of the point
(introduced in v3.12.6).
- returns **geoJson** (object): A valid GeoJSON Point.

```aql
---
Expand All @@ -769,8 +786,9 @@ any subsequent linear ring will be interpreted as holes.

For details about the rules, see [GeoJSON polygons](#polygon).

- **points** (array): an array of (arrays of) `[longitude, latitude]` pairs
- returns **geoJson** (object\|null): a valid GeoJSON Polygon
- **points** (array): An array of (arrays of) `[longitude, latitude]` pairs,
or optionally `[longitude, latitude, elevation]`.
- returns **geoJson** (object\|null): A valid GeoJSON Polygon.

A validation step is performed using the S2 geometry library. If the
validation is not successful, an AQL warning is issued and `null` is
Expand Down Expand Up @@ -809,8 +827,9 @@ Construct a GeoJSON MultiPolygon. Needs at least two Polygons inside.
See [`GEO_POLYGON()`](#geo_polygon) and [GeoJSON MultiPolygon](#multipolygon)
for the rules of Polygon and MultiPolygon construction.

- **polygons** (array): an array of arrays of arrays of `[longitude, latitude]` pairs
- returns **geoJson** (object\|null): a valid GeoJSON MultiPolygon
- **polygons** (array): An array of arrays of arrays of `[longitude, latitude]`
pairs, or optionally `[longitude, latitude, elevation]`.
- returns **geoJson** (object\|null): A valid GeoJSON MultiPolygon.

A validation step is performed using the S2 geometry library, if the
validation is not successful, an AQL warning is issued and `null` is
Expand Down Expand Up @@ -860,31 +879,31 @@ FOR doc IN coll
RETURN doc
```
Assuming there exists a geo-type index on `latitude` and `longitude`, the
optimizer will recognize it and accelerate the query.
optimizer recognizes it and accelerates the query.
{{< /warning >}}

`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,
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.
Optionally, the distances in meters between the specified coordinate pair
(*latitude* and *longitude*) and the stored coordinate pairs can be returned as
(`latitude` and `longitude`) and the stored coordinate pairs 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 of the point to search
- **longitude** (number): the longitude of the point to search
- **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 (in meters)
has to be specified in the `distanceName` argument. The result documents
contains the distance value in an attribute of that name.

- **coll** (collection): A collection.
- **latitude** (number): The latitude of the point to search for.
- **longitude** (number): The longitude of the point to search for.
- **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 are returned.
- **distanceName** (string, *optional*): Include the distance (in meters)
between the reference point and the stored point in the result, using the
attribute name *distanceName*
- returns **docArray** (array): an array of documents, sorted by distance
(shortest distance first)
attribute name `distanceName`.
- returns **docArray** (array): An array of documents, sorted by distance
(shortest distance first).

### WITHIN()

Expand All @@ -901,29 +920,29 @@ FOR doc IN coll
```

Assuming there exists a geo-type index on `latitude` and `longitude`, the
optimizer will recognize it and accelerate the query.
optimizer recognizes it and accelerates the query.
{{< /warning >}}

`WITHIN(coll, latitude, longitude, radius, distanceName) → docArray`

Return all documents from collection *coll* that are within a radius of *radius*
around the specified coordinate pair (*latitude* and *longitude*). The documents
Return all documents from collection `coll` that are within a radius of `radius`
around the specified coordinate pair (`latitude` and `longitude`). The documents
returned are sorted by distance to the reference point, with the closest
distances being returned first. Optionally, the distance (in meters) between the
reference point and the stored point 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
the `distanceName` argument. The result documents contains the distance
value in an attribute of that name.

- **coll** (collection): a collection
- **latitude** (number): the latitude of the point to search
- **longitude** (number): the longitude of the point to search
- **radius** (number): radius in meters
- **distanceName** (string, *optional*): include the distance (in meters)
- **coll** (collection): A collection.
- **latitude** (number): The latitude of the point to search for.
- **longitude** (number): The longitude of the point to search for.
- **radius** (number): Radius in meters.
- **distanceName** (string, *optional*): Include the distance (in meters)
between the reference point and stored point in the result, using the
attribute name *distanceName*
- returns **docArray** (array): an array of documents, sorted by distance
(shortest distance first)
attribute name `distanceName`.
- returns **docArray** (array): An array of documents, sorted by distance
(shortest distance first).

### WITHIN_RECTANGLE()

Expand All @@ -947,18 +966,18 @@ FOR doc IN coll
```

Assuming there exists a geo-type index on `latitude` and `longitude`, the
optimizer will recognize it and accelerate the query.
optimizer recognizes it and accelerates the query.
{{< /warning >}}

`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.
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 latitude of the bottom-left point to search
- **longitude1** (number): the longitude of the bottom-left point to search
- **latitude2** (number): the latitude of the top-right point to search
- **longitude2** (number): the longitude of the top-right point to search
- returns **docArray** (array): an array of documents, in random order
- **coll** (collection): A collection.
- **latitude1** (number): The latitude of the bottom-left point to search for.
- **longitude1** (number): The longitude of the bottom-left point to search for.
- **latitude2** (number): The latitude of the top-right point to search for.
- **longitude2** (number): The longitude of the top-right point to search for.
- returns **docArray** (array): An array of documents, in random order.
Loading