ST_COVERS scalar function

Edit online

The ST_COVERS function takes two geometry objects as input parameters and returns the integer 1 if the first geometry completely covers the second geometry. Otherwise, it returns the integer 0 (zero) to indicate that the first geometry does not completely cover the second.

If geometry1 or geometry2 is null, the result is the null value. If geometry1 or geometry2 is empty, 0 (zero) is returned. If both geometry1 and geometry2 are empty, 1 is returned.

geometry1: A value of type ST_GEOMETRY or one of its subtypes that represents the geometry that is to be tested to completely contain geometry2.

geometry2: A value of type ST_GEOMETRY or one of its subtypes that represents the geometry that is to be tested to be completely covered by geometry1.

The result of the function is INTEGER.

Notes

One geometry (geometry1) covers another (geometry2) if any of the following conditions are true:

the interior of geometry1 intersects the interior of geometry2 and the interior or boundary of geometry2 does not intersect the exterior of geometry1.
the interior of geometry1 intersects the boundary of geometry2 and the interior or boundary of geometry2 does not intersect the exterior of geometry1.
the boundary of geometry1 intersects the interior of geometry2 and the interior or boundary of geometry2 does not intersect the exterior of geometry1.
the boundaries of either geometry intersect and the interior or boundary of geometry2 does not intersect the exterior of geometry1.

Example

Use the ST_COVERS function to determine which points are covered by a polygon.

CREATE TABLE sample_points(point_id INTEGER, point QSYS2.ST_POINT);
CREATE TABLE sample_polygons(polygon_id INTEGER, polygon QSYS2.ST_POLYGON);

INSERT INTO sample_points VALUES
  (1, QSYS2.ST_POINT(10, 20)),
  (2, QSYS2.ST_POINT('point(41 41)'));
  
INSERT INTO sample_polygons VALUES
  (100, QSYS2.ST_POLYGON('polygon((0 0, 0 40, 40 40, 40 0, 0 0))'));
  
SELECT polygon_id,
       point_id,
       CASE QSYS2.ST_COVERS(polygon, point)
          WHEN 0 THEN 'does not cover'
          WHEN 1 THEN 'covers'
       END AS covers
FROM sample_points, sample_polygons;

Results:


POLYGON_ID    POINT_ID    COVERS
-----------   ---------   -----------------
        100           1   covers
        100           2   does not cover