ST_Within

ST_Within
Prev	7.11.1. Topological Relationships	Next

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


	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 `_ST_Within`.

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.

Enhanced: 3.0.0 enabled support for GEOMETRYCOLLECTION


	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

This example defines two concentric circles once in a CTE so the same inputs can be rendered and then reused in related predicate checks.

Code

WITH circles AS (
  SELECT ST_Buffer(center, 20) AS smallc,
         ST_Buffer(center, 40) AS bigc
  FROM (SELECT 'POINT(50 50)'::geometry AS center) AS p
)
SELECT smallc AS small_circle,
       bigc AS big_circle
FROM circles;

Output

POLYGON((70 50,69.616 46.098,68.478 42.346,66.629 38.889,64.142 35.858,61.111 33.371,57.654 31.522,53.902 30.384,50 30,46.098 30.384,42.346 31.522,38.889 33.371,35.858 35.858,33.371 38.889,31.522 42.346,30.384 46.098,30 50,30.384 53.902,31.522 57.654,33.371 61.111,35.858 64.142,38.889 66.629,42.346 68.478,46.098 69.616,50 70,53.902 69.616,57.654 68.478,61.111 66.629,64.142 64.142,66.629 61.111,68.478 57.654,69.616 53.902,70 50)) | POLYGON((90 50,89.231 42.196,86.955 34.693,83.259 27.777,78.284 21.716,72.223 16.741,65.307 13.045,57.804 10.769,50 10,42.196 10.769,34.693 13.045,27.777 16.741,21.716 21.716,16.741 27.777,13.045 34.693,10.769 42.196,10 50,10.769 57.804,13.045 65.307,16.741 72.223,21.716 78.284,27.777 83.259,34.693 86.955,42.196 89.231,50 90,57.804 89.231,65.307 86.955,72.223 83.259,78.284 78.284,83.259 72.223,86.955 65.307,89.231 57.804,90 50))

01030000000100000021000000000000000080514000000000000049407CA67EB86767514007BF479B910C474013E65FD8901E514088B5F495542C454042496AF647A85040427FF97DBD71434058E103C018095040503DF87FCEED4140BF800682428E4E407D6D2B1370AF4040784A0B6AABD34C40B467809EBC853F40F940B8646EF34A401266051E61623E4000000000000049400000000000003E4007BF479B910C47401266051E61623E4089B5F495542C4540B467809EBC853F40427FF97DBD7143407C6D2B1370AF4040503DF87FCEED4140503DF87FCEED41407D6D2B1370AF4040427FF97DBD714340B467809EBC853F4088B5F495542C45401266051E61623E4006BF479B910C47400000000000003E4000000000000049401266051E61623E40F940B8646EF34A40B467809EBC853F40774A0B6AABD34C407C6D2B1370AF4040BE800682428E4E40503DF87FCEED414058E103C018095040427FF97DBD71434042496AF647A8504087B5F495542C454012E65FD8901E514006BF479B910C47407BA67EB86767514000000000000049400000000000805140F940B8646EF34A407CA67EB867675140784A0B6AABD34C4013E65FD8901E5140BE800682428E4E4042496AF647A8504058E103C01809504058E103C01809504042496AF647A85040BE800682428E4E4012E65FD8901E5140794A0B6AABD34C407BA67EB867675140FA40B8646EF34A4000000000008051400000000000004940 | 0103000000010000002100000000000000008056400000000000004940F74CFD70CF4E56400E7E8F362319454026CCBFB021BD5540116BE92BA95841408392D4EC8FD0544006FDE5F7F5C63B40B0C207803192534041F5E0FF39B73540BF800682420E5240F4B5AD4CC0BD3040784A0B6AAB535040D09E017AF2162A40F28170C9DCE64C404898157884892540000000000000494000000000000024400F7E8F36231945404898157884892540126BE92BA9584140D09E017AF2162A4008FDE5F7F5C63B40F2B5AD4CC0BD304041F5E0FF39B7354040F5E0FF39B73540F4B5AD4CC0BD304006FDE5F7F5C63B40D09E017AF2162A40106BE92BA958414048981578848925400C7E8F3623194540000000000000244000000000000049404898157884892540F28170C9DCE64C40D09E017AF2162A40774A0B6AAB535040F2B5AD4CC0BD3040BE800682420E52403EF5E0FF39B73540B0C207803192534006FDE5F7F5C63B408392D4EC8FD054400E6BE92BA958414025CCBFB021BD55400C7E8F3623194540F64CFD70CF4E564000000000000049400000000000805640F28170C9DCE64C40F74CFD70CF4E5640784A0B6AAB53504026CCBFB021BD5540BE800682420E52408492D4EC8FD05440B0C2078031925340B0C20780319253408392D4EC8FD05440BE800682420E524025CCBFB021BD5540794A0B6AAB535040F64CFD70CF4E5640F48170C9DCE64C4000000000008056400000000000004940

Figure

Using the same circles, ST_Within is reflexive on each circle, false from the larger circle into the smaller one, and true for ST_Union only when the union does not extend beyond the larger circle.