ST_Within method

Tests if a geometry value is spatially contained within another geometry value.

Syntax

geometry-expression.ST_Within(geo2)

Parameters

Name	Type	Description
geo2	ST_Geometry	The other geometry value that is to be compared to the `geometry-expression`.

Returns

BIT
Returns 1 if the geometry-expression is within geo2, otherwise 0.

Remarks

The ST_Within method tests if the geometry-expression is completely within geo2 and there is one or more interior points of geo2 that lies in the interior of the geometry-expression.

geometry-expression.ST_Within( geo2 ) is equivalent to geo2.ST_Contains( geometry-expression ).

The ST_Within and ST_CoveredBy methods are similar. The difference is that ST_CoveredBy does not require intersecting interior points.

Note If the geometry-expression contains circularstrings, then these are interpolated to line strings.

Note This method cannot be used with geometries in round-Earth spatial reference systems.

Standards

SQL/MM (ISO/IEC 13249-3: 2006)
5.1.30

Example

The following example tests if a point is within a polygon. The point is completely within the polygon, and the interior of the point (the point itself) intersects the interior of the polygon, so the example returns 1.

SELECT NEW ST_Point( 1, 1 )
	.ST_Within( NEW ST_Polygon( 'Polygon(( 0 0, 2 0, 1 2, 0 0 ))' ) )

The following example tests if a line is within a polygon. The line is completely within the polygon, but the interior of the line and the interior of the polygon do not intersect (the line only intersects the polygon on the polygon's boundary, and the boundary is not part of the interior), so the example returns 0. If ST_CoveredBy was used in place of ST_Within, ST_CoveredBy would return 1.

SELECT NEW ST_LineString( 'LineString( 0 0, 1 0 )' )
	.ST_Within( NEW ST_Polygon( 'Polygon(( 0 0, 2 0, 1 2, 0 0 ))' ) )

The following example lists the ShapeIDs where the given point is within the Shape geometry. This example returns the result 3,5. ShapeID 6 is not listed because the point intersects that row's Shape polygon at the polygon's boundary.

SELECT LIST( ShapeID ORDER BY ShapeID )
FROM SpatialShapes
WHERE NEW ST_Point( 1, 4 ).ST_Within( Shape ) = 1