ST_Within function
Use the ST_Within function to determine whether one geometry is completely within another geometry.
Syntax
Parameters
- geometry1
- A value of type ST_Geometry or one of its subtypes that is to be tested to be fully within geometry2.
- geometry2
- A value of type ST_Geometry or one of its subtypes that is to be tested to be fully within geometry1.
Return type
INTEGER
Usage
ST_Within takes two geometries as input parameters and returns 1 if the first geometry is completely within the second geometry. Otherwise, 0 (zero) is returned.
If any of the given geometries is null or is empty, null is returned.
If the second geometry is not represented in the same spatial reference system as the first geometry and uses the same underlying datum, it will be converted to the other spatial reference system.
ST_Within performs the same logical operation that ST_Contains performs with the parameters reversed. ST_Within returns the exact opposite result of ST_Contains.
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.
Geometry b Interior | Geometry b Boundary | Geometry b Exterior | |
---|---|---|---|
Geometry a Interior | T | * | F |
Geometry a Boundary | * | * | F |
Geometry a Exterior | * | * | * |
Examples
Figure 1 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 1, 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.