ST_DWithin function

Syntax

Parameter

geometry1

A value of type ST_Geometry that represents the geometry that is to be compared with geometry2.

geometry2

A value of type ST_Geometry that represents the geometry that is to be compared with geometry1.

distance

A value of type DOUBLE that indicates the distance within which the two geometries must be.

unit

VARCHAR(128) value that identifies the unit in which the result is measured. The supported units of measure are listed in the SYSGEO.ST_UNITS_OF_MEASURE catalog view.

If the unit parameter is omitted, the following rules are used to determine the unit of measure used for the result:

• If geometry1 is in a projected or geocentric coordinate system, the linear unit associated with this coordinate system is the default.
• If geometry1 is in a geographic coordinate system, the angular unit associated with this coordinate system is the default.

Restrictions on unit conversions: An error (SQLSTATE 38SU4) is returned if any of the following conditions occur:

• The geometry is in an unspecified coordinate system and the unit parameter is specified.
• The geometry is in a projected coordinate system and an angular unit is specified.

Return type

Returns 1 (true) if the geometries are within the specified distance of one another, and 0 (false) if they are not.

If the geometries are not in a compatible spatial reference system, an error is returned.

Example

create table points (pk integer not null primary key, geo ST_Point)

insert into points values(1, st_point(10, 10.1, 4326))
insert into points values(2, st_point(10, 19.9999, 4326))
insert into points values(3, st_point(12, 20.53, 4326))

create table polys (pk integer not null primary key, geo st_polygon )

insert into polys values (1, ST_Polygon ('polygon (10 20, 10 40, 20 30, 10 20)', 4326))
insert into polys values (2, ST_Polygon ('polygon ((110 120, 110 140, 120 130, 110 120))', 4326))

select t1.pk as ptsid, t2.pk as plyid, st_dwithin(t1.geo, t2.geo, 100.0) as dw from points t1, polys t2 order by dw desc;
         
PTSID       PLYID       DW
----------- ----------- -----------
          2           1           1
          1           1           0
          1           2           0
          2           2           0
          3           1           0
          3           2           0