ST_WithinDistanceFilter method

geometry-expression.ST_WithinDistanceFilter(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. 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'.

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

The ST_WithinDistanceFilter method provides an efficient test to determine if two geometries might be within a specified distance of each other (as determined by the ST_WithinDistance method). Returns 1 if the geometry-expression might be within the given distance of geo2, otherwise it returns 0.

This test is less expensive than ST_WithinDistance, but may return 1 in some cases where the smallest distance between the two geometries is actually larger than the specified distance. Therefore, this method can be useful as a primary filter when further processing will determine the true distance between the geometries.

The implementation of ST_WithinDistanceFilter relies upon metadata associated with the stored geometries. Because the available metadata may change between server versions, depending upon how the data is loaded, or where ST_WithinDistanceFilter is used within a query, the expression geometry-expression.ST_WithinDistanceFilter(geo2, distance [, unit_name ]) can return different results when geometry-expression is not within the specified distance of geo2. Whenever geometry-expression is within the specified distance of geo2, ST_WithinDistanceFilter always returns 1.

Note

By default, ST_WithinDistanceFilter 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.

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

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. See sa_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`

ST_WithinDistanceFilter method

Syntax

Parameters

Returns

Remarks

Note

See also

Standards and compatibility

Example