Name

ST_DWithin — Teste si deux géométries se trouvent à une distance donnée

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 use_spheroid = true);

Description

Renvoie true si les géométries se trouvent à une distance donnée

Pour le type geometry : la distance est spécifiée en unités définies par le système de référence spatiale des géométries. Pour que cette fonction ait un sens, les géométries sources doivent se trouver dans le même système de coordonnées (avoir le même SRID).

Pour le type geography : les unités sont en mètres et la mesure de la distance est par défaut use_spheroid = true. Pour une évaluation plus rapide, utilisez use_spheroid = false pour mesurer sur la sphère.

[Note]

Utilisez ST_3DDWithin pour les géométries 3D.

[Note]

Cet appel de fonction inclut une comparaison de la boîte de délimitation qui utilise tous les index disponibles sur les géométries.

Cette méthode implémente la spécification OGC Simple Features Implementation Specification for SQL 1.1.

Disponibilité : la prise en charge du type geography a été introduite dans la version 1.5.0

Amélioration : la version 2.1.0 a amélioré la vitesse de la géographie. Voir Making Geography faster pour plus de détails.

Amélioration : la prise en charge des géométries courbes a été introduite dans la version 2.1.0.

Avant la version 1.3, ST_Expand était couramment utilisé en conjonction avec && et ST_Distance pour tester la distance, et avant la version 1.3.4, cette fonction utilisait cette logique. À partir de la version 1.3.4, ST_DWithin utilise une fonction de distance de court-circuit plus rapide.

Exemples

-- 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.geom, h.hospital_name
  FROM schools s
    LEFT JOIN hospitals h ON ST_DWithin(s.geom, h.geom, 3000)
  ORDER BY s.gid, ST_Distance(s.geom, h.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.geom, h.geom, 3000)
  WHERE h.gid IS NULL;

-- Find broadcasting towers that receiver with limited range can receive.
-- Data is geometry in Spherical Mercator (SRID=3857), ranges are approximate.

-- Create geometry index that will check proximity limit of user to tower
CREATE INDEX ON broadcasting_towers using gist (geom);

-- Create geometry index that will check proximity limit of tower to user
CREATE INDEX ON broadcasting_towers using gist (ST_Expand(geom, sending_range));

-- Query towers that 4-kilometer receiver in Minsk Hackerspace can get
-- Note: two conditions, because shorter LEAST(b.sending_range, 4000) will not use index.
SELECT b.tower_id, b.geom
  FROM broadcasting_towers b
  WHERE ST_DWithin(b.geom, 'SRID=3857;POINT(3072163.4 7159374.1)', 4000)
    AND ST_DWithin(b.geom, 'SRID=3857;POINT(3072163.4 7159374.1)', b.sending_range);