Documentation SurrealQL Functions Geo functions

Geo functions

These functions can be used when working with and analysing geospatial data.

Function Description
geo::area() Calculates the area of a geometry
geo::bearing() Calculates the bearing between two geolocation points
geo::centroid() Calculates the centroid of a geometry
geo::distance() Calculates the distance between two geolocation points
geo::hash::decode() Decodes a geohash into a geometry point
geo::hash::encode() Encodes a geometry point into a geohash

geo::area

The geo::area function calculates the area of a geometry.

geo::area(geometry) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN geo::area({
type: "Polygon",
coordinates: [[
[-0.38314819, 51.37692386], [0.1785278, 51.37692386],
[0.1785278, 51.61460570], [-0.38314819, 51.61460570],
[-0.38314819, 51.37692386]
]]
});
0.13350018278702186

If the argument is not a geometry type, then an EMPTY value will be returned:

RETURN geo::area(12345);
null

geo::bearing

The geo::bearing function calculates the bearing between two geolocation points.

geo::bearing(point, point) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN geo::bearing( (51.509865, -0.118092), (-0.118092, 51.509865) );
-31.913259585079818

If either argument is not a geolocation point, then an EMPTY value will be returned:

RETURN geo::bearing(12345, true);
null

geo::centroid

The geo::centroid function calculates the centroid between two geolocation points.

geo::centroid(geometry) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN geo::centroid({
type: "Polygon",
coordinates: [[
[-0.38314819, 51.37692386], [0.1785278, 51.37692386],
[0.1785278, 51.61460570], [-0.38314819, 51.61460570],
[-0.38314819, 51.37692386]
]]
});
{
"type": "Point",
"coordinates": [
-0.10231019499999999,
51.49576478
]
}

If either argument is not a geometry type, then an EMPTY value will be returned:

RETURN geo::centroid(12345);
null

geo::distance

The geo::distance function calculates the haversine distance, in metres, between two geolocation points.

geo::distance(point, point) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN geo::distance( (51.509865, -0.118092), (-0.118092, 51.509865) );
7491494.807105545

If either argument is not a geolocation point, then an EMPTY value will be returned:

RETURN geo::distance(12345, true);
null

geo::hash::decode

The geo::hash::decode function converts a geohash into a geolocation point.

geo::hash::decode(point) -> string

The following example shows this function, and its output, when used in a RETURN statement:

RETURN geo::hash::decode("mpuxk4s24f51");
{
"type": "Point",
"coordinates": [
51.50986494496465,
-0.11809204705059528
]
}

If the argument is not a geolocation point, then an EMPTY value will be returned:

RETURN geo::hash::decode(12345);
null

geo::hash::encode

The geo::hash::encode function converts a geolocation point into a geohash.

geo::hash::encode(point) -> string

The function accepts a second argument, which determines the accuracy and granularity of the geohash.

geo::hash::encode(point, number) -> string

The following example shows this function, and its output, when used in a RETURN statement:

RETURN geo::hash::encode( (51.509865, -0.118092) );
"mpuxk4s24f51"

The following example shows this function with two arguments, and its output, when used in a select statement:

RETURN geo::hash::encode( (51.509865, -0.118092), 5 );
"mpuxk"

If the first argument is not a geolocation point, then an EMPTY value will be returned:

RETURN geo::hash::encode(12345);
null