ST_Distance method for type ST

ST_Distance method for type ST_Geometry

Returns the smallest distance between the geometry-expression and the specified geometry value.

Syntax

geometry-expression.ST_Distance(geo2[, unit-name])

Parameters

Name	Type	Description
geo2	ST_Geometry	The other geometry value whose distance is to be measured from the geometry-expression.
unit-name	VARCHAR(128)	The units in which the distance should be computed. Defaults to the unit of the spatial reference system. The unit name must match the UNIT_NAME column of a row in the ST_UNITS_OF_MEASURE view where UNIT_TYPE is 'LINEAR'.

Returns

DOUBLE Returns the smallest distance between the geometry-expression and geo2 in the specified linear units of measure. If either geometry-expression or geo2 is empty, then NULL is returned.

The ST_Distance method computes the shortest distance between two geometries. For planar spatial reference systems, the distance is calculated as the Cartesian distance within the plane, computed in the linear units of measure for the associated spatial reference system. For round-Earth spatial reference systems, the distance is computed taking the curvature of the Earth's surface into account using the ellipsoid parameters in the spatial reference system definition.

Note

For round-Earth spatial reference systems, the ST_Distance method is only supported if geometry-expression and geo2 contain only points.

Note

By default, ST_Distance uses the original format for a geometry, if it is available. Otherwise, the internal format is used. For more information about internal and original formats, see STORAGE FORMAT clause, CREATE SPATIAL REFERENCE SYSTEM statement.

Standards and compatibility

Example

The following example returns an ordered result set with one row for each shape and the corresponding distance from the point (2,3).

SELECT ShapeID, ROUND( Shape.ST_Distance( NEW ST_Point( 2, 3 ) ), 2 ) AS dist
FROM SpatialShapes 
WHERE ShapeID < 17
ORDER BY dist

The example returns the following result set:

ShapeID	dist
`2`	`0.0`
`3`	`0.0`
`5`	`1.0`
`6`	`1.21`
`16`	`1.41`
`1`	`5.1`

The following example creates points representing Halifax, NS and Waterloo, ON, Canada and uses ST_Distance to find the distance between the two points in miles, returning the result 846. This example assumes that the 'st_geometry_predefined_uom' feature has been installed by the sa_install_feature system procedure.

SELECT ROUND( NEW ST_Point( -63.573566, 44.646244, 4326 )
	.ST_Distance( NEW ST_Point( -80.522372, 43.465187, 4326 )
	                    , 'Statute mile' ), 0 )

Discuss this page in DocCommentXchange.