ST_Contains
Determines if a spatial object is entirely inside another spatial object without existing only on its boundary. Both arguments must be the same spatial data type. Either specify two GEOMETRY objects or two GEOGRAPHY objects.
If an object such as a point or linestring only exists along a spatial object's boundary, then ST_Contains returns false. The interior of a linestring is all the points on the linestring except the start and end points.
ST_Contains(g1, g2) is functionally equivalent to ST_Within(g2, g1).
GEOGRAPHY Polygons with a vertex or border on the International Date Line (IDL) or the North or South pole are not supported.
Behavior Type
Syntax
ST_Contains( g1, g2
[USING PARAMETERS spheroid={true | false}] )
Arguments
g1 |
Spatial object, type GEOMETRY or GEOGRAPHY |
g2
|
Spatial object, type GEOMETRY or GEOGRAPHY |
Parameters
spheroid = {true | false}
|
(Optional) BOOLEAN that specifies whether to use a perfect sphere or WGS84. Default: False |
Returns
BOOLEAN
Supported Data Types
| Data Type | GEOMETRY | GEOGRAPHY (Perfect Sphere) | GEOGRAPHY (WGS84) |
| Point |
Yes |
Yes |
Yes |
| Multipoint |
Yes |
No |
No |
| Linestring |
Yes |
Yes |
No |
| Multilinestring |
Yes |
No |
No |
| Polygon |
Yes |
Yes |
Yes |
| Multipolygon |
Yes |
Yes |
No |
| GeometryCollection |
Yes |
No |
No |
Compatible GEOGRAPHY pairs:
| Data Type | GEOGRAPHY (Perfect Sphere) | GEOGRAPHY (WGS84) |
| Point-Point | Yes | No |
| Linestring-Point | Yes | No |
| Polygon-Point | Yes | Yes |
| Multipolygon-Point | Yes | No |
Examples
The following examples show how to use ST_Contains.
The first polygon does not completely contain the second polygon:
=> SELECT ST_Contains(ST_GeomFromText('POLYGON((0 2,1 1,0 -1,0 2))'),
ST_GeomFromText('POLYGON((-1 3,2 1,0 -3,-1 3))'));
ST_Contains
-------------
f
(1 row)
If a point is on a linestring, but not on an end point:
=> SELECT ST_Contains(ST_GeomFromText('LINESTRING(20 20,30 30)'),
ST_GeomFromText('POINT(25 25)'));
ST_Contains
--------------
t
(1 row)
If a point is on the boundary of a polygon:
=> SELECT ST_Contains(ST_GeographyFromText('POLYGON((20 20,30 30,30 25,20 20))'),
ST_GeographyFromText('POINT(20 20)'));
ST_Contains
--------------
f
(1 row)
Two spatially equivalent polygons:
=> SELECT ST_Contains (ST_GeomFromText('POLYGON((-1 2, 0 3, 0 1, -1 2))'),
ST_GeomFromText('POLYGON((0 3, -1 2, 0 1, 0 3))'));
ST_Contains
--------------
t
(1 row)
