ST_Within

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

Syntax

Parameters

geometry1: A value of one of the seven distinct spatial data types that is to be tested to be fully within geometry2.
geometry2: A value of one of the seven distinct spatial data types that is to be tested to be fully within geometry1.

Return type

INTEGER

Examples

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 PATH = CURRENT 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) );

INSERT INTO sample_points (id, geometry)
  VALUES (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) );

INSERT INTO sample_lines (id, line)
  VALUES (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( a.geometry, b.geometry) = 1;

Results:


POINT_ID_WITHIN_POLYGONS
----------------------
1
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( a.line, b.geometry) = 1;

Results:


LINE_ID_WITHIN_POLYGONS
----------------------
10
20