The ST_DWITHIN function checks whether the shortest distance between two geographic objects is within a specified distance.
Syntax
BOOLEAN ST_DWITHIN(GEOGRAPHY <value1>, GEOGRAPHY <value2>, DOUBLE <distance>)Parameters
value1, value2: Required. Values of the GEOGRAPHY data type. You can construct GEOGRAPHY objects by using functions such as ST_GEOGPOINT, ST_GEOGFROMWKB, ST_GEOGFROMTEXT, ST_MAKELINE, and ST_MAKEPOLYGON.
distance: Required. DOUBLE type. The distance threshold, in meters.
Return value
Returns a BOOLEAN value based on the following rules:
Returns TRUE if the shortest distance between value1 and value2 is less than or equal to distance, and FALSE otherwise.
Returns FALSE if value1 or value2 is an empty geographic object.
Examples
Example 1: Check whether the shortest distance between two points is within a specified distance threshold.
-- Returns FALSE. The distance between the two points is approximately 157249.63 meters, which is greater than the specified threshold of 157249.0. SELECT ST_DWITHIN(ST_GEOGFROMTEXT('POINT(0 0)'), ST_GEOGFROMTEXT('POINT(1 1)'), 157249.0); -- Returns TRUE. The distance between the two points is less than the specified threshold of 157249.7. SELECT ST_DWITHIN(ST_GEOGFROMTEXT('POINT(0 0)'), ST_GEOGFROMTEXT('POINT(1 1)'), 157249.7);Example 2: Handling empty geographic objects
-- Returns FALSE because one of the geographic objects is empty. SELECT ST_DWITHIN(ST_GEOGFROMTEXT('POINT(0 0)'), ST_GEOGFROMTEXT('POINT EMPTY'), 157249.7);Example 3: Check if a point is inside a polygon by using a distance of 0.
-- Returns TRUE because POINT(0 0) is inside the POLYGON, and the shortest distance is 0. SELECT ST_DWITHIN(ST_GEOGFROMTEXT('POINT(0 0)'), ST_GEOGFROMTEXT('POLYGON((-1 -1, 1 -1, 1 1, -1 1, -1 -1))'), 0.0);