ST_Contains

ST_Contains takes two geometries as input parameter and returns 1 if the first geometry completely contains the second; otherwise it returns 0 (zero) to indicate that the first geometry does not completely contain the second.

If any of the given geometries is null or is empty, then null is returned.

If the second geometry is not represented in the same spatial reference system as the first geometry, it will be converted to the other spatial reference system.

Syntax

Parameter

geometry1: A value of one of the seven distinct spatial data types that represents the geometry that is to be tested to completely contain geometry2.
geometry2: A value of one of the seven distinct spatial data types that represents the geometry that is to be tested to be completely within geometry1.

Return type

INTEGER

Examples

Example 1

The following code creates and populates these tables.


SET CURRENT PATH = CURRENT PATH, db2gse; 

CREATE TABLE sample_points(id SMALLINT, geometry ST_POINT);

CREATE TABLE sample_lines(id SMALLINT, geometry ST_LINESTRING);

CREATE TABLE sample_polygons(id SMALLINT, geometry ST_POLYGON);

INSERT INTO sample_points (id, geometry)
VALUES
    (1, ST_Point(10, 20, 1));

INSERT INTO sample_points (id, geometry)
VALUES
    (2, ST_Point('point(41 41)', 1));

INSERT INTO sample_lines (id, geometry)
VALUES
    (10, ST_LineString('linestring (1 10, 3 12, 10 10)', 1) );

INSERT INTO sample_lines (id, geometry)
VALUES
    (20, ST_LineString('linestring (50 10, 50 12, 45 10)', 1) );

INSERT INTO sample_polygons(id, geometry)
VALUES
      (100, ST_Polygon('polygon((0 0, 0 40, 40 40, 40 0, 0 0))',  1) );

Example 2

The following code fragment uses the ST_Contains function to determine which points are contained by a particular polygon.


SELECT poly.id AS polygon_id,
       CASE ST_Contains(poly.geometry, pts.geometry)
          WHEN 0 THEN 'does not contain'
          WHEN 1 THEN 'does contain'
       END AS contains,
       pts.id AS point_id
FROM   sample_points pts, sample_polygons poly;

Results:


POLYGON_ID CONTAINS         POINT_ID
---------- ---------------- --------
       100 does contain            1
       100 does not contain        2

Example 3

The following code fragment uses the ST_Contains function to determine which lines are contained by a particular polygon.


SELECT poly.id AS polygon_id,
       CASE ST_Contains(poly.geometry, line.geometry)
          WHEN 0 THEN 'does not contain'
          WHEN 1 THEN 'does contain' 
       END AS contains,
       line.id AS line_id
FROM   sample_lines line, sample_polygons poly;

Results:


POLYGON_ID CONTAINS         LINE_ID
---------- ---------------- -------
       100 does contain          10
       100 does not contain      20