ST_Within

If spatial object g1 is completely inside of spatial object g2, then ST_Within returns true.

If spatial object g1 is completely inside of spatial object g2, then ST_Within returns true. Both parameters must be the same spatial data type. Either specify two GEOMETRY objects or two GEOGRAPHY objects.

If an object such as a point or linestring only exists along a polygon's boundary, then ST_Within returns false. The interior of a linestring is all the points along the linestring except the start and end points.

ST_Within(g1,``g2) is functionally equivalent to ST_Contains(g2,``g1).

GEOGRAPHY Polygons with a vertex or border on the International Date Line (IDL) or the North or South pole are not supported.

Behavior type

Immutable

Syntax

ST_Within( g1, g2
                      [USING PARAMETERS spheroid={true | false}] )

Arguments

g1
Spatial object, type GEOMETRY or GEOGRAPHY
g2
Spatial object, type GEOMETRY or GEOGRAPHY

Parameters

spheroid = {true | false}

(Optional) BOOLEAN that specifies whether to use a perfect sphere or WGS84.

Default: False

Returns

BOOLEAN

Supported data types

Data Type GEOMETRY GEOGRAPHY (Perfect Sphere) GEOGRAPHY (WGS84)
Point Yes Yes Yes
Multipoint Yes No No
Linestring Yes Yes No
Multilinestring Yes No No
Polygon Yes Yes Yes
Multipolygon Yes Yes No
GeometryCollection Yes No No

Compatible GEOGRAPHY pairs:

Data Type GEOGRAPHY (Perfect Sphere) GEOGRAPHY (WGS84)
Point-Point Yes No
Point-Linestring Yes No
Point-Polygon Yes Yes
Point-Multipolygon Yes No

Examples

The following examples show how to use ST_Within.

The first polygon is completely contained within the second polygon:

=> SELECT ST_Within(ST_GeomFromText('POLYGON((0 2,1 1,0 -1,0 2))'),
   ST_GeomFromText('POLYGON((-1 3,2 1,0 -3,-1 3))'));
 ST_Within
-----------
 t
(1 row)

The point is on a vertex of the polygon, but not in its interior:

=> SELECT ST_Within (ST_GeographyFromText('POINT(30 25)'),
   ST_GeographyFromText('POLYGON((25 25,25 35,32.2 35,30 25,25 25))'));
 ST_Within
-----------
 f
(1 row)

Two polygons are spatially equivalent:

=> SELECT ST_Within (ST_GeomFromText('POLYGON((-1 2, 0 3, 0 1, -1 2))'),
   ST_GeomFromText('POLYGON((0 3, -1 2, 0 1, 0 3))'));
 ST_Within
-----------
 t
(1 row)

See also