ST_Contains

Determines if a spatial object is entirely inside another spatial object without existing only on its boundary.

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

Immutable

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)

See also