ST_Contains
Name
ST_Contains — Tests if every point of B lies in A, and their interiors have a point in common
Synopsis
boolean
ST_Contains
(
geometry
geomA
, geometry
geomB
)
;
Description
Returns TRUE if geometry A contains geometry B. A contains B if and only if all points of B lie inside (i.e. in the interior or boundary of) A (or equivalently, no points of B lie in the exterior of A), and the interiors of A and B have at least one point in common.
In mathematical terms: ST_Contains(A, B) ⇔ (A ⋂ B = B) ∧ (Int(A) ⋂ Int(B) ≠ ∅)
The contains relationship is reflexive: every geometry contains itself.
(In contrast, in the
ST_ContainsProperly
predicate a geometry does
not
properly contain itself.)
The relationship is antisymmetric: if
ST_Contains(A,B) = true
and
ST_Contains(B,A) = true
, then
the two geometries must be topologically equal (
ST_Equals(A,B) = true
).
ST_Contains is the converse of
ST_Within
.
So,
ST_Contains(A,B) = ST_Within(B,A)
.
|
|
|
Because the interiors must have a common point, a subtlety of the definition is that polygons and lines do not contain lines and points lying fully in their boundary. For further details see Subtleties of OGC Covers, Contains, Within . The ST_Covers predicate provides a more inclusive relationship. |
|
|
|
This function automatically includes a bounding box comparison
that makes use of any spatial indexes that are available on the geometries.
To avoid index use, use the function
|
Performed by the GEOS module
Enhanced: 2.3.0 Enhancement to PIP short-circuit extended to support MultiPoints with few points. Prior versions only supported point in polygon.
Enhanced: 3.0.0 enabled support for
GEOMETRYCOLLECTION
|
|
|
Do not use this function with invalid geometries. You will get unexpected results. |
NOTE: this is the "allowable" version that returns a boolean, not an integer.
This method implements the
OGC Simple Features
Implementation Specification for SQL 1.1.
s2.1.1.2 // s2.1.13.3
- same as within(geometry B, geometry A)
This method implements the SQL/MM specification.
SQL-MM 3: 5.1.31
Examples
ST_Contains
returns
TRUE
in the following situations:
A LineString contains a MultiPoint whose points lie in its interior or boundary.
SELECT ST_Contains(a, b) FROM (SELECT 'LINESTRING (10 190,60 80,130 120,190 10)'::geometry AS a, 'MULTIPOINT (60 80,190 10)'::geometry AS b ) AS example;
t
A Polygon contains a Point in its interior.
SELECT ST_Contains(a, b) FROM (SELECT 'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130))'::geometry AS a, 'POINT (99 130)'::geometry AS b ) AS example;
t
A Polygon contains a LineString with interior points inside the Polygon.
SELECT ST_Contains(a, b) FROM (SELECT 'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130))'::geometry AS a, 'LINESTRING (50 190,110 190,99 130)'::geometry AS b ) AS example;
t
A Polygon contains another Polygon in its interior.
SELECT ST_Contains(a, b) FROM (SELECT 'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130))'::geometry AS a, 'POLYGON ((70 40,100 50,120 80,80 110,50 90,70 40))'::geometry AS b ) AS example;
t
ST_Contains
returns
FALSE
in the following situations:
A Polygon does not contain a MultiPoint when one point lies in a hole.
SELECT ST_Contains(a, b) FROM (SELECT 'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130),(70 40,100 50,120 80,80 110,50 90,70 40))'::geometry AS a, 'MULTIPOINT (99 130,87 70)'::geometry AS b ) AS example;
f
A Polygon does not contain a LineString extending outside it.
SELECT ST_Contains(a, b) FROM (SELECT 'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130))'::geometry AS a, 'LINESTRING (99 130,170 131)'::geometry AS b ) AS example;
f
Due to the interior intersection condition
ST_Contains
returns
FALSE
in the following situations
(whereas
ST_Covers
returns
TRUE
):
A LineString does not contain a Point lying only on its boundary.
SELECT ST_Contains(a, b), ST_Covers(a, b) FROM (SELECT 'LINESTRING (10 190,60 80,130 120,190 10)'::geometry AS a, 'POINT (190 10)'::geometry AS b ) AS example;
f | t
A Polygon does not contain a LineString lying entirely on its boundary.
SELECT ST_Contains(a, b), ST_Covers(a, b) FROM (SELECT 'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130))'::geometry AS a, 'LINESTRING (80 190,110 190,140 150,150 80)'::geometry AS b ) AS example;
f | t
This example tests a circle within another circle.
WITH circles AS (
SELECT ST_Buffer(center, 10) AS smallc,
ST_Buffer(center, 20) AS bigc
FROM (SELECT 'POINT(1 2)'::geometry AS center) AS p
)
SELECT
ST_Contains(smallc, bigc) AS smallcontainsbig,
ST_Contains(bigc, smallc) AS bigcontainssmall,
ST_Contains(bigc, ST_Union(smallc, bigc)) AS bigcontainsunion,
ST_Equals(bigc, ST_Union(smallc, bigc)) AS bigisunion,
ST_Covers(bigc, ST_ExteriorRing(bigc)) AS bigcoversexterior,
ST_Contains(bigc, ST_ExteriorRing(bigc)) AS bigcontainsexterior
FROM circles;
-[ RECORD 1 ]----- smallcontainsbig | f bigcontainssmall | t bigcontainsunion | t bigisunion | t bigcoversexterior | t bigcontainsexterior | f
This example demonstrates the difference between contains and contains-properly predicates.
SELECT
ST_GeometryType(geom_a) AS geomtype,
ST_Contains(geom_a, geom_a) AS acontainsa,
ST_ContainsProperly(geom_a, geom_a) AS acontainspropa,
ST_Contains(geom_a, ST_Boundary(geom_a)) AS acontainsba,
ST_ContainsProperly(geom_a, ST_Boundary(geom_a)) AS acontainspropba
FROM (VALUES
(ST_Buffer(ST_Point(1, 1), 5, 1)),
(ST_MakeLine(ST_Point(1, 1), ST_Point(-1, -1))),
(ST_Point(1, 1))
) AS foo(geom_a);
geomtype | acontainsa | acontainspropa | acontainsba | acontainspropba --------------+------------+----------------+-------------+----------------- ST_Polygon | t | f | f | f ST_LineString | t | f | f | f ST_Point | t | t | f | f
See Also
ST_Boundary , ST_ContainsProperly , ST_Covers , ST_CoveredBy , ST_Equals , ST_Within