ST_DWithin
Name
ST_DWithin — Returns true if the geometries are within the specified distance of one another. For geometry units are in those of spatial reference and For geography units are in meters and measurement is defaulted to use_spheroid=true (measure around spheroid), for faster check, use_spheroid=false to measure along sphere.
Synopsis
boolean
ST_DWithin
(
geometry
g1
, geometry
g2
, double precision
distance_of_srid
)
;
boolean
ST_DWithin
(
geography
gg1
, geography
gg2
, double precision
distance_meters
)
;
boolean
ST_DWithin
(
geography
gg1
, geography
gg2
, double precision
distance_meters
, boolean
use_spheroid
)
;
Description
Returns true if the geometries are within the specified distance of one another.
For Geometries: The distance is specified in units defined by the spatial reference system of the geometries. For this function to make sense, the source geometries must both be of the same coordinate projection, having the same SRID.
For geography units are in meters and measurement is defaulted to use_spheroid=true, for faster check, use_spheroid=false to measure along sphere.
![[Note]](images/note.png)
|
|
|
This function call will automatically include a bounding box comparison that will make use of any indexes that are available on the geometries. |
|
|
|
|
Prior to 1.3, ST_Expand was commonly used in conjunction with && and ST_Distance to achieve the same effect and in pre-1.3.4 this function was basically short-hand for that construct. From 1.3.4, ST_DWithin uses a more short-circuit distance function which should make it more efficient than prior versions for larger buffer regions. |
|
|
|
|
Use ST_3DDWithin if you have 3D geometries. |
This method implements the
OpenGIS Simple Features
Implementation Specification for SQL 1.1.
Availability: 1.5.0 support for geography was introduced
Enhanced: 2.1.0 improved speed for geography. See Making Geography faster for details.
Enhanced: 2.1.0 support for curved geometries was introduced.
Examples
--Find the nearest hospital to each school --that is within 3000 units of the school. -- We do an ST_DWithin search to utilize indexes to limit our search list -- that the non-indexable ST_Distance needs to process --If the units of the spatial reference is meters then units would be meters SELECT DISTINCT ON (s.gid) s.gid, s.school_name, s.the_geom, h.hospital_name FROM schools s LEFT JOIN hospitals h ON ST_DWithin(s.the_geom, h.the_geom, 3000) ORDER BY s.gid, ST_Distance(s.the_geom, h.the_geom); --The schools with no close hospitals --Find all schools with no hospital within 3000 units --away from the school. Units is in units of spatial ref (e.g. meters, feet, degrees) SELECT s.gid, s.school_name FROM schools s LEFT JOIN hospitals h ON ST_DWithin(s.the_geom, h.the_geom, 3000) WHERE h.gid IS NULL;