Renvoie true si deux objets spatiaux sont distants d'une valeur inférieure ou égale à une distance spécifiée, et false dans le cas contraire. Contrairement à ST_Distance, ST_DWithin exploite automatiquement les index spatiaux disponibles, ce qui en fait la solution privilégiée pour les requêtes de proximité.
Syntaxe
boolean ST_DWithin(geometry g1, geometry g2, double precision distanceOfSrid);
boolean ST_DWithin(geography gg1, geography gg2, double precision distanceMeters);
boolean ST_DWithin(geography gg1, geography gg2, double precision distanceMeters, boolean useSpheroid);Paramètres
| Paramètre | Type | Description |
|---|---|---|
g1 |
geometry | Premier objet geometry. |
g2 |
geometry | Deuxième objet geometry. |
distanceOfSrid |
double precision | Distance seuil, exprimée dans l'unité du système de référence spatiale (SRS) des objets geometry. |
gg1 |
geography | Premier objet geography. |
gg2 |
geography | Deuxième objet geography. |
distanceMeters |
double precision | Distance seuil, en mètres. |
useSpheroid |
boolean | Indique s'il faut utiliser un système de référence ellipsoïdal. Cette option améliore la précision des résultats au prix d'une légère baisse de performance. |
Notes d'utilisation
Si les deux arguments sont de type
geometry, ils doivent partager le même identifiant de système de référence spatiale (SRID).Si les deux arguments sont de type
geography, la distance est mesurée en mètres par défaut.La fonction compare les boîtes englobantes en s'appuyant sur tous les index spatiaux disponibles ; les vérifications de proximité bénéficient ainsi d'une accélération par index native.
Pour les vérifications de proximité en 3D, utilisez plutôt ST_3DDWithin.
Exemples
Différence entre ST_DWithin et ST_DFullyWithin
ST_DWithin renvoie true si la distance minimale entre les deux objets est inférieure ou égale au seuil défini. ST_DFullyWithin applique une contrainte plus stricte : chaque point des deux objets doit respecter le seuil de distance.
SELECT ST_DFullyWithin(g1, g2, 2), ST_DWithin(g1, g2, 2)
FROM (
SELECT 'LINESTRING(0 1,1 1)'::geometry AS g1,
'LINESTRING(0 0,0 -1)'::geometry AS g2
) AS test;Résultat attendu :
st_dfullywithin | st_dwithin
-----------------+------------
f | t
(1 row)Étapes suivantes
ST_DFullyWithin : vérifie si tous les points de deux objets respectent une distance spécifiée
ST_3DDWithin : vérification de proximité pour les objets 3D dans un système de coordonnées projeté