Name

ST_Contains — Bの点がAの外部に無く、かつBの内部の少なくとも一つの点がAの内部にある場合に限って、TRUEを返します。

Synopsis

boolean ST_Contains(geometry geomA, geometry geomB);

説明

ジオメトリAがジオメトリBを含むのは、Bの点がAの外部に無く、かつBの内部の少なくとも一つの点がAの内部にある場合に限ります。この定義の重要で微妙なところは、AはAの境界を含まないと判断するのに、AはA自身を含むと判断することです。ジオメトリAはA自身を含まないと判断をするST_ContainsProperlyと対照的です。

ジオメトリBが完全にジオメトリAの内側になる場合はTRUEを返します。この関数が意味のあるものにするためには、元のジオメトリは同じ投影座標である、同じSRIDを持っている必要があります。ST_ContainsはST_Withinの逆のものです。ST_Contains(A,B)はST_Within(B,A)を意味します。ただし、結果が常にFALSEになる、不用意な、または定義されていない不正なジオメトリの場合を除きます。

GEOSモジュールによって実現しています。

Enhanced: 2.3.0 Enhancement to PIP short-circuit extended to support MultiPoints with few points. Prior versions only supported point in polygon.

[Important]

GEOMETRYCOLLECTIONを引数として呼ばないでください。

[Important]

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

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

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

This method implements the OpenGIS Simple Features Implementation Specification for SQL 1.1. s2.1.1.2 // s2.1.13.3 - within(geometry B, geometry A)と同じ

This method implements the SQL/MM specification. SQL-MM 3: 5.1.31

直感的に分かりにくいST_ContainsとST_Withinの微妙な違いがあります。詳細については、Subtleties of OGC Covers, Contains, Withinをご覧ください。

次に示す図全てで、ST_ContainsTRUEを返します。

LINESTRING / MULTIPOINT

POLYGON / POINT

POLYGON / LINESTRING

POLYGON / POLYGON

次に示す図全てで、ST_ContainsFALSEを返します。

POLYGON / MULTIPOINT

POLYGON / LINESTRING

-- 円の中にある円
SELECT ST_Contains(smallc, bigc) As smallcontainsbig,
           ST_Contains(bigc,smallc) As bigcontainssmall,
           ST_Contains(bigc, ST_Union(smallc, bigc)) as bigcontainsunion,
           ST_Equals(bigc, ST_Union(smallc, bigc)) as bigisunion,
           ST_Covers(bigc, ST_ExteriorRing(bigc)) As bigcoversexterior,
           ST_Contains(bigc, ST_ExteriorRing(bigc)) As bigcontainsexterior
FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10) As smallc,
                         ST_Buffer(ST_GeomFromText('POINT(1 2)'), 20) As bigc) As foo;

-- 結果
  smallcontainsbig | bigcontainssmall | bigcontainsunion | bigisunion | bigcoversexterior | bigcontainsexterior
------------------+------------------+------------------+------------+-------------------+---------------------
 f                | t                | t                | t          | t        | f

-- ST_ContainsとST_ContainsProperlyとの違いを示す例
SELECT ST_GeometryType(geomA) As geomtype, ST_Contains(geomA,geomA) AS acontainsa, ST_ContainsProperly(geomA, geomA) AS acontainspropa,
   ST_Contains(geomA, ST_Boundary(geomA)) As acontainsba, ST_ContainsProperly(geomA, ST_Boundary(geomA)) As acontainspropba
FROM (VALUES ( ST_Buffer(ST_Point(1,1), 5,1) ),
                         ( ST_MakeLine(ST_Point(1,1), ST_Point(-1,-1) ) ),
                         ( ST_Point(1,1) )
          ) As foo(geomA);

  geomtype    | acontainsa | acontainspropa | acontainsba | acontainspropba
--------------+------------+----------------+-------------+-----------------
ST_Polygon    | t          | f              | f           | f
ST_LineString | t          | f              | f           | f
ST_Point      | t          | t              | f           | f

 

関連情報

ST_Boundary, ST_ContainsProperly, ST_Covers, ST_CoveredBy, ST_Equals, ST_Within