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 specified 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.

Table 1. 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	*	*	*

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.

top Seven of the examples show the first geometry within the second geometry. — 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.


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) = 1

Results:


POINT_ID_WITHIN_POLYGONS
----------------------
                     1

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) = 1

Results:


LINE_ID_WITHIN_POLYGONS
----------------------
                    10