ST_ContainsProperly
Prev | 8.11.1. Topological Relationships | Next

## Name

ST_ContainsProperly — Tests if B intersects the interior of A but not the boundary or exterior.

## Synopsis

`boolean ST_ContainsProperly(`geometry geomA, geometry geomB`)`;

## Description

Returns true if B intersects the interior of A but not the boundary or exterior.

A does not properly contain itself, but does contain itself.

Every point of the other geometry is a point of this geometry's interior. The DE-9IM Intersection Matrix for the two geometries matches [T**FF*FF*] used in ST_Relate

An example use case for this predicate is computing the intersections of a set of geometries with a large polygonal geometry. Since intersection is a fairly slow operation, it can be more efficient to use containsProperly to filter out test geometries which lie wholly inside the area. In these cases the intersection is known a priori to be exactly the original test geometry.

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

The advantage of this predicate over ST_Contains and ST_Intersects is that it can be computed more efficiently, with no need to compute topology at individual points.

Performed by the GEOS module.

Availability: 1.4.0

Enhanced: 3.0.0 enabled support for `GEOMETRYCOLLECTION`

Do not use this function with invalid geometries. You will get unexpected results.

## Examples

      --a circle within a circle
      SELECT ST_ContainsProperly(smallc, bigc) As smallcontainspropbig,
      ST_ContainsProperly(bigc,smallc) As bigcontainspropsmall,
      ST_ContainsProperly(bigc, ST_Union(smallc, bigc)) as bigcontainspropunion,
      ST_Equals(bigc, ST_Union(smallc, bigc)) as bigisunion,
      ST_Covers(bigc, ST_ExteriorRing(bigc)) As bigcoversexterior,
      ST_ContainsProperly(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;
      --Result
      smallcontainspropbig | bigcontainspropsmall | bigcontainspropunion | bigisunion | bigcoversexterior | bigcontainsexterior
    ------------------+------------------+------------------+------------+-------------------+---------------------
     f                     | t                    | f                    | t          | t                 | f

     --example demonstrating difference between contains and contains properly
     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

## See Also

ST_GeometryType, ST_Boundary, ST_Contains, ST_Covers, ST_CoveredBy, ST_Equals, ST_Relate, ST_Within

Prev | Up | Next
ST_Contains | Home | ST_CoveredBy