ST_Contains
Zurück  7.11.1. Topologische Beziehungen  Weiter

Name

ST_Contains — Tests, wenn jeder Punkt von B in A liegt und ihre Innenräume einen gemeinsamen Punkt haben

Übersicht

boolean ST_Contains(geometry geomA, geometry geomB);

Beschreibung

Gibt TRUE zurück, wenn die Geometrie A die Geometrie B enthält. A enthält B nur dann, wenn alle Punkte von B innerhalb von A liegen (d. h. im Inneren oder am Rand von A) (oder gleichwertig, wenn keine Punkte von B im Äußeren von A liegen) und die Innenräume von A und B mindestens einen Punkt gemeinsam haben.

Mathematisch ausgedrückt: ST_Contains(A, B) ⇔ (A ⋂ B = B) ∧ (Int(A) ⋂ Int(B) ≠ ∅)

Die Enthält-Beziehung ist reflexiv: Jede Geometrie enthält sich selbst. (Im Gegensatz dazu enthält im Prädikat ST_ContainsProperly eine Geometrie nicht sich selbst.) Die Beziehung ist antisymmetrisch: Wenn ST_Contains(A,B) = true und ST_Contains(B,A) = true, dann müssen die beiden Geometrien topologisch gleich sein (ST_Equals(A,B) = true).

ST_Contains ist die Umkehrung von ST_Within. ST_Contains(A,B) = ST_Within(B,A).

[Anmerkung]

Da die Innenräume einen gemeinsamen Punkt haben müssen, besteht eine Feinheit der Definition darin, dass Polygone und Linien nicht Linien und Punkte enthalten, die vollständig in ihrer Begrenzung liegen. Für weitere Details siehe Subtleties of OGC Covers, Contains, Within. Das Prädikat ST_Covers bietet eine umfassendere Beziehung.

[Anmerkung]

Diese Funktion beinhaltet automatisch einen Bounding-Box-Vergleich, der alle räumlichen Indizes verwendet, die für die Geometrien verfügbar sind. Um die Verwendung eines Indices zu vermeiden, kann die Funktion _ST_Contains verwendet werden.

Wird durch das GEOS Modul ausgeführt

Verbessert: 2.3.0 Verbesserung des PIP-Kurzschlusses erweitert um die Unterstützung von MultiPoints mit wenigen Punkten. Frühere Versionen unterstützten nur Punkte in Polygonen.

Verbessert: 3.0.0 ermöglicht die Unterstützung von GEOMETRYCOLLECTION

[Wichtig]

Verwenden Sie diese Funktion nicht mit ungültigen Geometrien. Sie werden unerwartete Ergebnisse erhalten.

HINWEIS: Dies ist die "zulässige" Version, die einen booleschen Wert und keine ganze Zahl zurückgibt.

Diese Methode implementiert die OGC Simple Features Implementation Specification for SQL 1.1. s2.1.1.2 // s2.1.13.3 - dasselbe wie innerhalb (Geometrie B, Geometrie A)

Diese Methode setzt die SQL/MM-Spezifikation um. SQL-MM 3: 5.1.31

Beispiele

ST_Contains gibt TRUE in den folgenden Situationen zurück:

A LineString contains a MultiPoint whose points lie in its interior or boundary.

Code
SELECT ST_Contains(a, b)
FROM (SELECT
  'LINESTRING (10 190,60 80,130 120,190 10)'::geometry AS a,
  'MULTIPOINT (60 80,190 10)'::geometry AS b
) AS example;
Ausgabe von Rastern
t
Figure
Geometry figure for visual-st-contains-01

A Polygon contains a Point in its interior.

Code
SELECT ST_Contains(a, b)
FROM (SELECT
  'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130))'::geometry AS a,
  'POINT (99 130)'::geometry AS b
) AS example;
Ausgabe von Rastern
t
Figure
Geometry figure for visual-st-contains-02

A Polygon contains a LineString with interior points inside the Polygon.

Code
SELECT ST_Contains(a, b)
FROM (SELECT
  'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130))'::geometry AS a,
  'LINESTRING (50 190,110 190,99 130)'::geometry AS b
) AS example;
Ausgabe von Rastern
t
Figure
Geometry figure for visual-st-contains-03

A Polygon contains another Polygon in its interior.

Code
SELECT ST_Contains(a, b)
FROM (SELECT
  'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130))'::geometry AS a,
  'POLYGON ((70 40,100 50,120 80,80 110,50 90,70 40))'::geometry AS b
) AS example;
Ausgabe von Rastern
t
Figure
Geometry figure for visual-st-contains-04

ST_Contains gibt FALSE in den folgenden Situationen zurück:

A Polygon does not contain a MultiPoint when one point lies in a hole.

Code
SELECT ST_Contains(a, b)
FROM (SELECT
  'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130),(70 40,100 50,120 80,80 110,50 90,70 40))'::geometry AS a,
  'MULTIPOINT (99 130,87 70)'::geometry AS b
) AS example;
Ausgabe von Rastern
f
Figure
Geometry figure for visual-st-contains-05

A Polygon does not contain a LineString extending outside it.

Code
SELECT ST_Contains(a, b)
FROM (SELECT
  'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130))'::geometry AS a,
  'LINESTRING (99 130,170 131)'::geometry AS b
) AS example;
Ausgabe von Rastern
f
Figure
Geometry figure for visual-st-contains-06

Aufgrund der inneren Schnittpunktbedingung ST_Contains liefert FALSE in den folgenden Situationen (während ST_Covers TRUE liefert):

A LineString does not contain a Point lying only on its boundary.

Code
SELECT ST_Contains(a, b), ST_Covers(a, b)
FROM (SELECT
  'LINESTRING (10 190,60 80,130 120,190 10)'::geometry AS a,
  'POINT (190 10)'::geometry AS b
) AS example;
Ausgabe von Rastern
f | t
Figure
Geometry figure for visual-st-contains-07

A Polygon does not contain a LineString lying entirely on its boundary.

Code
SELECT ST_Contains(a, b), ST_Covers(a, b)
FROM (SELECT
  'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130))'::geometry AS a,
  'LINESTRING (80 190,110 190,140 150,150 80)'::geometry AS b
) AS example;
Ausgabe von Rastern
f | t
Figure
Geometry figure for visual-st-contains-08

This example tests a circle within another circle.

Code
WITH circles AS (
  SELECT ST_Buffer(center, 10) AS smallc,
         ST_Buffer(center, 20) AS bigc
  FROM (SELECT 'POINT(1 2)'::geometry AS center) AS p
)
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 circles;
Ausgabe von Rastern
-[ RECORD 1 ]-----
smallcontainsbig   | f
bigcontainssmall   | t
bigcontainsunion   | t
bigisunion         | t
bigcoversexterior  | t
bigcontainsexterior | f
Figure
Geometry figure for visual-st-contains-09

This example demonstrates the difference between contains and contains-properly predicates.

Code
SELECT
  ST_GeometryType(geom_a) AS geomtype,
  ST_Contains(geom_a, geom_a) AS acontainsa,
  ST_ContainsProperly(geom_a, geom_a) AS acontainspropa,
  ST_Contains(geom_a, ST_Boundary(geom_a)) AS acontainsba,
  ST_ContainsProperly(geom_a, ST_Boundary(geom_a)) 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(geom_a);
Ausgabe von Rastern
geomtype    | acontainsa | acontainspropa | acontainsba | acontainspropba
--------------+------------+----------------+-------------+-----------------
ST_Polygon    | t          | f              | f           | f
ST_LineString | t          | f              | f           | f
ST_Point      | t          | t              | f           | f
Figure
Geometry figure for visual-st-contains-10