ST_Within
Name
ST_Within — Tests if every point of A lies in B, and their interiors have a point in common
Synopsis
boolean
ST_Within
(
geometry
A
, geometry
B
)
;
Description
Returns TRUE if geometry A is within geometry B. A is within B if and only if all points of A lie inside (i.e. in the interior or boundary of) B (or equivalently, no points of A lie in the exterior of B), and the interiors of A and B have at least one point in common.
For this function to make sense, the source geometries must both be of the same coordinate projection, having the same SRID.
In mathematical terms: ST_Within(A, B) ⇔ (A ⋂ B = A) ∧ (Int(A) ⋂ Int(B) ≠ ∅)
The within relation is reflexive: every geometry is within itself.
The relation is antisymmetric: if
ST_Within(A,B) = true
and
ST_Within(B,A) = true
, then
the two geometries must be topologically equal (
ST_Equals(A,B) = true
).
ST_Within is the converse of
ST_Contains
.
So,
ST_Within(A,B) = ST_Contains(B,A)
.
![[Note]](./images/note.png)
|
|
|
Because the interiors must have a common point, a subtlety of the definition is that lines and points lying fully in the boundary of polygons or lines are not within the geometry. For further details see Subtleties of OGC Covers, Contains, Within . The ST_CoveredBy predicate provides a more inclusive relationship. |
|
|
|
|
This function automatically includes a bounding box comparison that makes use of any spatial indexes that are available on the geometries.
To avoid index use, use the function
|
Performed by the GEOS module
Enhanced: 2.3.0 Enhancement to PIP short-circuit for geometry extended to support MultiPoints with few points. Prior versions only supported point in polygon.
![[Important]](./images/important.png)
|
|
|
Enhanced: 3.0.0 enabled support for
|
|
|
|
|
Do not use this function with invalid geometries. You will get unexpected results. |
NOTE: this is the "allowable" version that returns a boolean, not an integer.
This method implements the
OGC Simple Features
Implementation Specification for SQL 1.1.
s2.1.1.2 // s2.1.13.3 - a.Relate(b, 'T*F**F***')
This method implements the SQL/MM specification.
SQL-MM 3: 5.1.30
Examples
--a circle within a circle
SELECT ST_Within(smallc,smallc) As smallinsmall,
ST_Within(smallc, bigc) As smallinbig,
ST_Within(bigc,smallc) As biginsmall,
ST_Within(ST_Union(smallc, bigc), bigc) as unioninbig,
ST_Within(bigc, ST_Union(smallc, bigc)) as biginunion,
ST_Equals(bigc, ST_Union(smallc, bigc)) as bigisunion
FROM
(
SELECT ST_Buffer(ST_GeomFromText('POINT(50 50)'), 20) As smallc,
ST_Buffer(ST_GeomFromText('POINT(50 50)'), 40) As bigc) As foo;
--Result
smallinsmall | smallinbig | biginsmall | unioninbig | biginunion | bigisunion
--------------+------------+------------+------------+------------+------------
t | t | f | t | t | t
(1 row)
