ST_WithinDistanceFilter( ST_Geometry , DOUBLE, VARCHAR(128)) method

Syntax

geometry-expression.ST_WithinDistanceFilter( ST_Geometry geo2, DOUBLE distance, VARCHAR(128) unit_name)

Parameters

geo2 – The other geometry value whose distance is to be measured from the geometry-expression.
distance – The distance the two geometries should be within.
unit_name – The units in which the distance parameter should be interpreted. The default is 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

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

Examples

Example 1 – The following example returns an ordered result set with one row for each shape that might be within distance 1.4 of the point (2,3). The result contains a shape that is not actually within the specified distance.

SELECT ShapeID, ROUND( Shape.ST_Distance( NEW ST_Point( 2, 3 ) ), 2 ) AS dist
FROM SpatialShapes
WHERE ShapeID < 17
AND Shape.ST_WithinDistanceFilter( 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
16	1.41

The following example creates points representing Halifax, NS and Waterloo, ON, Canada, and uses ST_WithinDistanceFilter to demonstrate that the distance between the two points might be within 850 miles, but definitely is not within 750 miles. This example assumes that the st_geometry_predefined_uom feature has been installed by the sa_install_feature system procedure. Seesa_install_feature system procedure.

SELECT NEW ST_Point( -63.573566, 44.646244, 4326 )
.ST_WithinDistanceFilter( NEW ST_Point( -80.522372, 43.465187, 4326 )
, 850, 'Statute mile' ) within850,
NEW ST_Point( -63.573566, 44.646244, 4326 )
.ST_WithinDistanceFilter( NEW ST_Point( -80.522372, 43.465187, 4326 )
, 750, 'Statute mile' ) within750

The example returns the following result set:

within850	within750
1	0

Standards

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