ST_WithinDistance method

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

Name	Type	Description
geo2	ST_Geometry	The other geometry value whose distance is to be measured from the geometry-expression.
distance	DOUBLE	The distance the two geometries should be within.
unit-name	VARCHAR(128)	The units in which the distance parameter should be interpreted. 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'.

BIT Returns 1 if geometry-expression and geo2 are within the specified distance of each other, otherwise 0.

The ST_WithinDistance method tests if the smallest distance between two geometries does not exceed a specified distance, taking tolerance into consideration.

More precisely, let d denote the smallest distance between geometry-expression and geo2. The expression geometry-expression.ST_WithinDistance( geo2, distance[, unit_name]) evaluates to 1 if either d <= distance or if d exceeds distance by a length that is less than the tolerance of the associated spatial reference system.

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

If the geometry-expression contains circularstrings, then these are interpolated to line strings.

Note

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

SQL/MM (ISO/IEC 13249-3: 2006) Vendor extension

The following example returns an ordered result set with one row for each shape that is within distance 1.4 of the point (2,3).

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

The example returns the following result set:

ShapeID	dist
`2`	`0.0`
`3`	`0.0`
`5`	`1.0`
`6`	`1.21`

The following example creates points representing Halifax, NS and Waterloo, ON, Canada and uses ST_WithinDistance to demonstrate that the distance between the two points is within 850 miles, but not within 840 miles. This example assumes that the 'st_geometry_predefined_uom' feature has been installed by the sa_install_feature system procedure. See sa_install_feature system procedure.

SELECT NEW ST_Point( -63.573566, 44.646244, 4326 )
	.ST_WithinDistance( NEW ST_Point( -80.522372, 43.465187, 4326 )
	                    , 850, 'Statute mile' ) within850,
	NEW ST_Point( -63.573566, 44.646244, 4326 )
	.ST_WithinDistance( NEW ST_Point( -80.522372, 43.465187, 4326 )
	                    , 840, 'Statute mile' ) within840

The example returns the following result set:

within850	within840
`1`	`0`