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