Click here to sign up to SurrealDB Cloud

Back to top
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