The ST_Contains() function

The ST_Contains() function takes two geometry objects and returns t (TRUE) if the first object completely contains the second; otherwise, it returns f (FALSE).

Syntax

ST_Contains(g1 geometry, g2 geometry)

Usage

To return TRUE, the boundary and interior of the second geometry cannot intersect the exterior of the first geometry. ST_Contains() returns the opposite result of ST_Within().

This graphic shows various geometric objects where one object is completely contains by the other. — Figure 1: Contained geometries

The results of the spatial relationship of the ST_Contains() function can be understood or verified by comparing the results with a pattern matrix that represents the acceptable values for the DE-9IM. The pattern matrix of the ST_Contains() function states that the interiors of both geometries must intersect. It also states that the interior and boundary of the secondary (geometry b) must not intersect the exterior of the primary (geometry a).

Table 1. Pattern matrix for the ST_Contains() function
The table is a matrix. The top row and first column identify the geometry.
		b
		Interior	Boundary	Exterior
	Interior	T	*	*
a	Boundary	*	*	*
	Exterior	F	F	*

Return type

BOOLEAN

Example

In the example below, two tables are created: buildingfootprints contains a city's building footprints, and lots contains its lots. The city engineer wants to ensure that all building footprints are completely inside their lots.

In both tables, the ST_MultiPolygon data type stores the geometry of the building footprints and the lots. The database designer selected multipolygons for both features because lots can be separated by natural features such as rivers, and building footprints can comprise several buildings:

CREATE TABLE buildingfootprints (building_id  integer,
                                 lot_id       integer,
                                 footprint    ST_MultiPolygon);

CREATE TABLE lots (lot_id  integer,
                   lot     ST_MultiPolygon);

The city engineer first selects the buildings that are not contained within one lot:

SELECT building_id
   FROM buildingfootprints, lots
   WHERE NOT ST_Contains(lot,footprint);

Although the first query provides a list of all building IDs that have footprints outside a lot polygon, it does not determine whether the rest are assigned the correct lot_id. The city engineer runs a second query to check the data integrity on the lot_id column of the buildingfootprints table:

SELECT bf.building_id, bf.lot_id, lots.lot_id 
   FROM buildingfootprints bf, lots
   WHERE NOT ST_Contains(lot,footprint)
   AND lots.lot_id <> bf.lot_id;

In the following figure, the building footprints are labeled with their building IDs and lie inside their lot lines. The lot lines are illustrated with dotted lines. Although not shown, they extend to the street centerline to completely encompass the lot lines and the building footprints within them.

This graphic is described in the surrounding text. — Figure 2: Building footprints and lot lines.