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.
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.
Figure 1. ST_Within function
Example 1
This example illustrates use of the ST_Within function. Geometries are created and inserted into
three tables, SAMPLE_POINTS, SAMPLE_LINES, and SAMPLE_POLYGONS.
SET CURRENT FUNCTION PATH = CURRENT FUNCTION PATH, db2gse
CREATE TABLE sample_points (id INTEGER, geometry ST_Point)
CREATE TABLE sample_lines (id INTEGER, line ST_LineString)
CREATE TABLE sample_polygons (id INTEGER, geometry ST_Polygon)
INSERT INTO sample_points (id, geometry)
VALUES (1, ST_Point (10, 20, 1) ),
(2, ST_Point ('point (41 41)', 1) )
INSERT INTO sample_lines (id, line)
VALUES (10, ST_LineString ('linestring (1 10, 3 12, 10 10)', 1) ),
(20, ST_LineString ('linestring (50 10, 50 12, 45 10)', 1) )
INSERT INTO sample_polygons (id, geometry)
VALUES (100, ST_Polygon ('polygon (( 0 0, 0 40, 40 40, 40 0, 0 0))', 1) )
Example 2
This example finds points from the SAMPLE_POINTS table that are in the polygons in the
SAMPLE_POLYGONS table.
SELECT a.id POINT_ID_WITHIN_POLYGONS
FROM sample_points a, sample_polygons b
WHERE ST_Within( b.geometry, a.geometry) = 0
Results:
POINT_ID_WITHIN_POLYGONS
----------------------
2
Example 3
This example finds linestrings from the SAMPLE_LINES table that are in the polygons in the
SAMPLE_POLYGONS table.
SELECT a.id LINE_ID_WITHIN_POLYGONS
FROM sample_lines a, sample_polygons b
WHERE ST_Within( b.geometry, a.geometry) = 0
