Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ocient.com/llms.txt

Use this file to discover all available pages before exploring further.

spatial measurement functions can perform basic calculations on geospatial data, such as measuring the distance between two POINT objects or the area of a POLYGON object.

​
ST_AREA

Returns the area of the specified geospatial object in the specified unit of measurement. Syntax
SQL
ST_AREA(geo [, units] [, use_spheroid ] )
ArgumentData TypeDescription
geoPOINT, LINESTRING, or POLYGONA geospatial object to be measured in the specified measurement unit.
unitsSTRINGOptional.
Supported units are 'FEET', 'KILOMETERS', 'MILES', and 'METERS'.
The default value is 'METERS'.
use_spheroidBOOLEANOptional.
If you set this value to TRUE, this function uses a spheroid model instead of a spherical model.
Defaults to FALSE.
Example
SQL
SELECT ST_AREA(
        ST_POLYGON(ST_LINESTRING('LINESTRING(2 3, 2 4, 4 2, 2 3)')),
        'MILES');
Output: 196932665.2369081

​
ST_ANGLE

Calculates the angle between two lines. The lines are represented by three POINT values, including one point for each line (a, b), and a third point (c) representing the vertex where they intersect. The function calculates the spherical angle as formed by the two great circles defined by (a, c) and (b, c). ST_ANGLE returns the value in radians, in the range [0, 2pi], excluding the value 2pi. If either a or b is the same or exactly antipodal to c, the function returns NULL. If any argument is NULL, the function returns NULL. Syntax
SQL
ST_ANGLE(endpoint_a, vertex_c, endpoint_b)
ArgumentData TypeDescription
endpoint_aPOINTA POINT that represents an endpoint for a line between its position and the vertex_c value.
vertex_cPOINTA POINT that represents the intersection between two lines. The lines comprise the endpoints between endpoint_a and vertex_c, and endpoint_b and vertex_c.
endpoint_bPOINTA POINT that represents an endpoint for a line between its position and the vertex_c value.
Example
SQL
SELECT ST_ANGLE(ST_POINT(1,0), ST_POINT(0,0), ST_POINT(1,1));
Output: 5.49778714378213

​
ST_AZIMUTH

Returns the azimuth of the line from point1 to point2 in radians. Returns NULL if either of the points are empty. Returns 0 if both of the points are the same. Syntax
SQL
ST_AZIMUTH(point1, point2)
ArgumentData TypeDescription
point1POINTAn endpoint for a line to be calculated for its azimuth value.
point2POINTAn endpoint for a line to be calculated for its azimuth value.
Example
SQL
SELECT ST_AZIMUTH(ST_POINT(1,1), ST_POINT(2,2));
Output: 0.785398163397448

​
ST_DISTANCE

Returns the minimum distance between the specified arguments. The ST_DISTANCE function returns the minimum distance in the specified unit of measurement. The use_spheroid optional argument enables the computation to use a spheroid model rather than a spherical one. Syntax
SQL
ST_DISTANCE(geo1, geo2 [, units] [, use_spheroid] )
ArgumentData TypeDescription
geo1POINT, LINESTRING, or POLYGONA geospatial object to be measured for its minimum distance to geo2.
geo2POINT, LINESTRING, or POLYGONA geospatial object to be measured for its minimum distance to geo1.
unitsSTRINGOptional.
Supported units include 'FEET', 'KILOMETERS', 'MILES', and 'METERS'.
If you do not specify this argument, the value defaults to 'METERS'.
use_spheroidBOOLEANOptional.
If you set this value to TRUE, this function uses a spheroid model instead of a spherical model.
Defaults to FALSE.
Example
SQL
SELECT ST_DISTANCE(
        ST_LINESTRING('LINESTRING(2 3, 2 4)'),
        ST_LINESTRING('LINESTRING(1 2, 1 4, 1 5)'),
        'METERS',
        true);
Output: 111050.10339481
To use ST_DISTANCE as a spatiotemporal function to calculate the minimum simultaneous distance between two linestring-timestamp array pairs, see the ST_DISTANCE function in Spatiotemporal Measurement.

​
ST_DISTANCESPHERE

Returns the minimum distance between the specified arguments using a spherical computation. This function is identical to ST_DISTANCE with the use_spheroid argument set to FALSE.
SQL
ST_DISTANCESPHERE(geo1, geo2 [, units] )
See ST_DISTANCE for usage example.

​
ST_DISTANCESPHEROID

Returns the minimum distance between the specified arguments using a spheroid computation. This function is identical to ST_DISTANCE with the use_spheroid argument set to TRUE.
SQL
ST_DISTANCESPHEROID(geo1, geo2 [, units] )
See ST_DISTANCE for usage example.

​
ST_EUCLIDEANDISTANCE3D

Returns the minimum distance between two geospatial points with altitude values. The distance represents the length of a Euclidean line between the points. Syntax
SQL
ST_EUCLIDEANDISTANCE3D(point1, altitude1, point2, altitude2 [, units] )
ArgumentData TypeDescription
point1POINTA geospatial point that represents a Euclidean line with point2.
altitude1DOUBLEDistance from the surface of the Earth for point1.
This argument uses meters, unless you specify a different unit of measurement with the units argument.
point2POINTA geospatial point that represents a Euclidean line with point1.
altitude2DOUBLEDistance from the surface of the Earth for point2.
This argument uses meters, unless you specify a different unit of measurement with the units argument.
unitsVARCHAROptional.
This argument specifies the unit of measurement for the distance input arguments and the function output. Supported units are 'FEET', 'KILOMETERS', 'MILES', and 'METERS'.
The default value is 'METERS'.
Example
SQL
SELECT ST_EUCLIDEANDISTANCE3D(
    ST_POINT(0,0),1000.0,
	ST_POINT(0,1),1000.0,
	'METERS');
Output: 111211.09372321835

​
ST_HAUSDORFFDISTANCE

Returns the Hausdorff distance between two geographies in a specified measurement. If any argument is NULL or empty, the function returns NULL. The two geographies can be POINT, LINESTRING, or POLYGON values. The system promotes these geographies to filled polygons. Behavior is undefined if the resulting polygons are not convex. Syntax
SQL
ST_HAUSDORFFDISTANCE(geo1, geo2 [, units] [, use_spheroid] )
ArgumentData TypeDescription
geo1POINT, LINESTRING, or POLYGONA geospatial object to be measured for its Hausdorff distance to geo2.
geo2POINT, LINESTRING, or POLYGONA geospatial object to be measured for its Hausdorff distance to geo1.
unitsSTRINGOptional.
Supported units are 'FEET', 'KILOMETERS', 'MILES', and 'METERS'.
The default value is 'METERS'.
use_spheroidBOOLEANOptional.
If you set this argument to TRUE, this function uses a spheroid model instead of a spherical model.
Defaults to FALSE.
Example
SQL
SELECT ST_HAUSDORFFDISTANCE(
        ST_POLYGON('POLYGON((1 1, 2 2, 1 2, 1 1))'),
        ST_POLYGON('POLYGON((0 0, 2 1, 2 0, 0 0))'),
        'METERS',
        TRUE);
Output: 156899.5136831999

​
ST_LENGTH

Returns the length of the specified line in the specified measurement unit. Returns 0 for all geography types except for LINESTRING. To return the total length of a POLYGON, use ST_PERIMETER. Syntax
SQL
ST_LENGTH(geo [, units] [, use_spheroid] )
ArgumentData TypeDescription
geoLINESTRINGA line that is to be measured for its length.
The function accepts POINT and POLYGON data types, but returns 0.
unitsSTRINGOptional.
Supported units are 'FEET', 'KILOMETERS', 'MILES', and 'METERS'.
The default value is 'METERS'.
use_spheroidBOOLEANOptional.
If you set this argument to TRUE, this function uses a spheroid model instead of a spherical model.
Defaults to FALSE.
Example
SQL
SELECT ST_LENGTH(
        ST_LINESTRING('LINESTRING(1 2, 1 4)'),
        'METERS',
        false);
Output: 222390.10395618092

​
ST_LENGTH2D

Alias for ST_LENGTH.

​
ST_MINIMUMDISTANCETOSURFACE

Calculates the shortest distance between any point along a Euclidean line segment in three-dimensional space and the surface of the Earth. Two input points and their altitudes define this line segment. The line can go above or below the surface of the Earth. The function takes the difference of both points from the center of the Earth to calculate the distance between the nearest point of the line and the surface of the Earth. The function returns the distance in meters or another unit of measurement if specified. If the returned distance is positive, the shortest distance is above the surface. If the result is negative, the shortest distance is below the surface. Syntax
SQL
ST_MINIMUMDISTANCETOSURFACE(point1, altitude1, point2, altitude2 [, units] )
ArgumentData TypeDescription
point1POINTA geospatial point that represents a Euclidean line with point2.
altitude1DOUBLEDistance from the surface of the Earth for point1.
This argument uses meters, unless you specify a different unit of measurement with the units argument.
point2POINTA geospatial point that represents a Euclidean line with point1.
altitude2DOUBLEDistance from the surface of the Earth for point2.
This argument uses meters, unless you specify a different unit of measurement with the units argument.
unitsVARCHAROptional.
This argument specifies the unit of measurement for the distance input arguments and the function output. Supported units are 'FEET', 'KILOMETERS', 'MILES', and 'METERS'.
The default value is 'METERS'.
Examples This example takes a line from two points and calculates the distance of the nearest point to the surface of the Earth.
SQL
SELECT ST_MINIMUMDISTANCETOSURFACE(
    ST_POINT(0,0),1000.0,
	ST_POINT(0,1),1000.0,
	'METERS');
Output: 757.3734914669767 In this example, the output is negative, meaning the smallest distance is actually below the surface of the Earth.
SQL
SELECT ST_MINIMUMDISTANCETOSURFACE(
    ST_POINT(0,0),1000.0,
	ST_POINT(0,5),1000.0,
	'METERS');
Output: -5064.738915202208

​
ST_MAXDISTANCE

Returns the maximum distance between the specified arguments. ST_MAXDISTANCE returns the maximum distance in the specified unit of measurement. The use_spheroid optional argument enables the computation to use a spheroid model rather than a spherical one. Syntax
SQL
ST_MAXDISTANCE(geo1, geo2 [, units] [, use_spheroid] )
ArgumentData TypeDescription
geo1POINT, LINESTRING, or POLYGONA geospatial object to be measured for its maximum distance to geo2.
geo2POINT, LINESTRING, or POLYGONA geospatial object to be measured for its maximum distance to geo1.
unitsSTRINGOptional.
Supported units are 'FEET', 'KILOMETERS', 'MILES', and 'METERS'.
The default value is 'METERS'.
use_spheroidBOOLEANOptional.
If you set this argument to TRUE, this function uses a spheroid model instead of a spherical model.
Defaults to FALSE.
Example
SQL
SELECT ST_MAXDISTANCE(
        ST_POLYGON(ST_LINESTRING('LINESTRING(1 2, 1 4, 1 7, 1 2)')),
        ST_POLYGON(ST_LINESTRING('LINESTRING(1 2, 1 4, 1 5, 1 2)')),
        'METERS',
        false);
Output: 555975.2598904524
To use ST_MAXDISTANCE as a spatiotemporal function to calculate the maximum simultaneous distance between two linestring-timestamp array pairs, see the ST_MAXDISTANCE function in Spatiotemporal Measurement.

​
ST_PERIMETER

Returns the length of the exterior (outer ring) of the POLYGON in the specified unit of measurement. Returns 0 for all geography types except for POLYGON. To return the length of a LINESTRING, use ST_LENGTH. Syntax
SQL
ST_PERIMETER(geo, [, units] [, use_spheroid] )
ArgumentData TypeDescription
geoPOLYGONA POLYGON that is to be measured for its total perimeter length.
The function accepts POINT and LINESTRING data types, but returns 0.
unitsSTRINGOptional.
Supported units are 'FEET', 'KILOMETERS', 'MILES', and 'METERS'.
The default value is 'METERS'.
use_spheroidBOOLEANOptional.
If you set this argument to TRUE, this function uses a spheroid model instead of a spherical model.
Defaults to FALSE.
Example
SQL
SELECT ST_PERIMETER(
        ST_POLYGON(ST_LINESTRING('LINESTRING(1 2, 1 3, 1 3, 1 2)')),
        'METERS',
        false);
Output: 222390.1039561809

​
ST_PERIMETER2D

Alias for ST_PERIMETER. Geospatial Data Types Spatial Operators Spatial Relationships
Last modified on May 21, 2026