Functions that check whether one geometry contains another

ST_Contains and ST_Within both take two geometries as input and determine whether the interior of one intersects the interior of the other.

In colloquial terms, ST_Contains determines whether the first geometry given to it encloses the second geometry (whether the first contains the second). ST_Within determines whether the first geometry is completely inside the second (whether the first is within the second).

ST_Contains

Use ST_Contains to determine whether one geometry is completely contained by another geometry.

ST_Contains returns a value of 1 (one) if the second geometry is completely contained by the first geometry. The ST_Contains function returns the exact opposite result of the ST_Within function.

Figure 1 shows examples of ST_Contains:
  • A multipoint geometry contains a point or multipoint geometries when all of the points are within the first geometry.
  • A polygon geometry contains a multipoint geometry when all of the points are either on the boundary of the polygon or in the interior of the polygon.
  • A linestring geometry contains a point, multipoint, or linestring geometries when all of the points are within the first geometry.
  • A polygon geometry contains a point, linestring or polygon geometries when the second geometry is in the interior of the polygon.
Figure 1. ST_Contains. The dark geometries represent geometry a and the gray geometries represent geometry b. In all cases, geometry a contains geometry b completely.
Begin figure description. All nine examples show that geometry a contains geometry b. End figure description.
The pattern matrix of the ST_Contains function states that the interiors of both geometries must intersect and that the interior or boundary of the secondary (geometry b ) must not intersect the exterior of the primary (geometry a). The asterisk (*) indicates that it does not matter if an intersection exists between these parts of the geometries.
Table 1. Matrix for ST_Contains
 

Geometry b Interior

Geometry b Boundary

Geometry b Exterior

Geometry a Interior

T

*

*

Geometry a Boundary

*

*

*

Geometry a Exterior

F

F

*

ST_Within

Use ST_Within to determine whether one geometry is completely within another geometry.

ST_Within returns a value of 1 (one) if the first geometry is completely within the second geometry. ST_Within returns the exact opposite result of ST_Contains.
Figure 2. ST_Within
Begin figure description. Seven of the examples show the first geometry within the second geometry. End figure description.
The ST_Within function pattern matrix states that the interiors of both geometries must intersect, and that the interior or boundary of the primary geometry (geometry a ) must not intersect the exterior of the secondary (geometry b ). The asterisk (*) indicates that all other intersections do not matter.
Table 2. Matrix for ST_Within
 

Geometry b Interior

Geometry b Boundary

Geometry b Exterior

Geometry a Interior

T

*

F

Geometry a Boundary

*

*

F

Geometry a Exterior

*

*

*
Figure 2 shows examples of ST_Within:
  • A point geometry is within a multipoint geometry when its interior intersects one of the points in the second geometry.
  • A multipoint geometry is within a multipoint geometry when the interiors of all points intersect the second geometry.
  • A multipoint geometry is within a polygon geometry when all of the points are either on the boundary of the polygon or in the interior of the polygon.
  • A point geometry is within a linestring geometry when all of the points are within the second geometry. In Figure 2, the point is not within the linestring because its interior does not intersect the linestring; however, the multipoint geometry is within the linestring because all of its points intersect the interior of the linestring.
  • A linestring geometry is within another linestring geometries when all of its points intersect the second geometry.
  • A point geometry is not within a polygon geometry because its interior does not intersect the boundary or interior of the polygon.
  • A linestring geometry is within a polygon geometry when all of its points intersect either the boundary or interior of the polygon.
  • A polygon geometry is within a polygon geometry when all of its points intersect either the boundary or interior of the polygon.