Description

Returns 1 (TRUE) if no point in Geometry/Geography A is outside Geometry/Geography B

	Enhanced: 3.0.0 enabled support for GEOMETRYCOLLECTION

	Do not use this function with invalid geometries. You will get unexpected results.

Performed by the GEOS module

Availability: 1.2.2

This function call will automatically include a bounding box comparison that will make use of any indexes that are available on the geometries. To avoid index use, use the function _ST_CoveredBy.

NOTE: this is the "allowable" version that returns a boolean, not an integer.

Not an OGC standard, but Oracle has it too.

There are certain subtleties to ST_Contains and ST_Within that are not intuitively obvious. For details check out Subtleties of OGC Covers, Contains, Within

Examples

	--a circle coveredby a circle
SELECT ST_CoveredBy(smallc,smallc) As smallinsmall,
	ST_CoveredBy(smallc, bigc) As smallcoveredbybig,
	ST_CoveredBy(ST_ExteriorRing(bigc), bigc) As exteriorcoveredbybig,
	ST_Within(ST_ExteriorRing(bigc),bigc) As exeriorwithinbig
FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10) As smallc,
	ST_Buffer(ST_GeomFromText('POINT(1 2)'), 20) As bigc) As foo;
	--Result
 smallinsmall | smallcoveredbybig | exteriorcoveredbybig | exeriorwithinbig
--------------+-------------------+----------------------+------------------
 t            | t                 | t                    | f
(1 row)	

See Also

ST_Contains, ST_Covers, ST_ExteriorRing, ST_Within