ST_WithinDistanceFilter method for type ST

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. 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 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 possibly be within a specified distance of each other (as determined by method ST_WithinDistance). Returns 1 if the geometry-expression might be within the given distance of geo2, otherwise 0.

This test is cheaper 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 meta-data associated with the stored geometries. Because the available meta-data 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 will always return 1.

Note

This method can not be used with geometries in round-Earth spatial reference system.

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 possibly be within distance 1.4 of the point (2,3). Observe that 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`

ST_WithinDistanceFilter method for type ST_Geometry

Syntax

Parameters

Returns

Remarks

Note

See also

Standards and compatibility

Example