ST_Contains function

Use the ST_Contains function to determine whether one geometry is completely contained by anther geometry.

Syntax

Parameter

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 within geometry1.

Return type

INTEGER

Usage

ST_Contains takes two geometries as input parameter and returns 1 if the first geometry completely contains the second or the second geometry is completely contained by the first geometry. Otherwise, it returns 0 (zero) to indicate that the first geometry does not completely contain the second.

The ST_Contains function returns the exact opposite result of the ST_Within function.

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 and uses the same underlying datum, it will be converted to the other spatial reference system.

The pattern matrix of the ST_Contains function states that the interiors of both geometries must intersect and that the interior or boundary of the secondary (geometry b ) must not intersect the exterior of the primary (geometry a). The asterisk (*) indicates that it does not matter if an intersection exists between these parts of the geometries.

Table 1. Matrix for ST_Contains
	Geometry b Interior	Geometry b Boundary	Geometry b Exterior
Geometry a Interior	T	*	*
Geometry a Boundary	*	*	*
Geometry a Exterior	F	F	*

Examples

Figure 1 shows examples of ST_Contains:

A multipoint geometry contains a point or multipoint geometries when all of the points are within the first geometry.
A polygon geometry contains a multipoint geometry when all of the points are either on the boundary of the polygon or in the interior of the polygon.
A linestring geometry contains a point, multipoint, or linestring geometries when all of the points are within the first geometry.
A polygon geometry contains a point, linestring or polygon geometries when the second geometry is in the interior of the polygon.

top All nine examples show that geometry a contains geometry b. — Figure 1. ST_Contains. The dark geometries represent geometry a and the gray geometries represent geometry b. In all cases, geometry a contains geometry b completely.

Example 1

The following code creates and populates these tables.


SET CURRENT FUNCTION PATH = CURRENT FUNCTION 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)),
    (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) ),
    (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