説明

ジオメトリAがジオメトリB内にある場合にTRUEを返します。Aの全ての点がBの内側 (内部または境界)にあり、Aの内部とBの内部に少なくとも一つの共有点がある場合に限って、AはB内にあると言います。

渡すジオメトリが両方とも同じSRIDでなければ、この関数は意味がありません。

数学用語では: ST_Within(A, B) ⇔ (A ⋂ B = A) ∧ (Int(A) ⋂ Int(B) ≠ ∅)

内にある、という関係性には反射性があります。全てのジオメトリは、自分の内にあると言えます。また、非対称性を持ちます。ST_Within(A,B) = trueかつST_Within(B,A) = trueの場合には、二つのジオメトリは必ずトポロジ的に等価 (ST_Equals(A,B) = true)になります。

ST_WithinはST_Containsの反対です。ST_Within(A,B) = ST_Contains(B,A)となります。

	内部が必ず共有点を持つので、定義は、ポリゴンまたはラインの境界上にあるラインまたはポイントはジオメトリの内にないという微妙なものになります。詳細については、Subtleties of OGC Covers, Contains, Withinをご覧下さい。ST_CoveredBy述語はより包括的な関係を提供します。

	この関数の呼び出しによって、ジオメトリで使用可能なインデックスを使用するバウンディングボックスの比較が自動的に行われます。 インデックスの使用を避けるには_ST_Within関数を使います。

GEOSモジュールで実現しています。

Enhanced: 2.3.0 ジオメトリについて、PIP short-circuit (ポリゴンとポイントに限定した高速判定)を少ないポイントからなるマルチポイントに対応することができるよう拡張しました。以前の版ではポリゴンとポイントの組み合わせにだけ対応していました。

	Enhanced: 3.0.0 GEOMETRYCOLLECTIONへの対応が可能となりました

	この関数を不正なジオメトリで呼ばないでください。予期しない結果が返されます。

ご注意: これは論理値を返して整数を返さないのが「許される」版です。

このメソッドはOGC Simple Features Implementation Specification for SQL 1.1の実装です。

s2.1.1.2 // s2.1.13.3 - a.Relate(b, 'T*F**F***')

このメソッドはSQL/MM仕様の実装です。

SQL-MM 3: 5.1.30

例

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

関連情報

ST_Contains, ST_CoveredBy, ST_Equals, ST_IsValid