Use spatial functions to test topological relationships between two geometry objects. Each function returns 1 if the specified relationship holds, and 0 otherwise.
The following spatial relationship functions are available:
| Function | Relationship tested |
|---|---|
| ST_Contains | All points of g2 lie inside g1, and their interiors share at least one point |
| ST_Crosses | g1 and g2 share some, but not all, interior points |
| ST_Disjoint | g1 and g2 share no points |
| ST_Equals | g1 and g2 occupy exactly the same set of points |
| ST_Intersects | g1 and g2 share at least one point |
| ST_Overlaps | g1 and g2 have the same dimension and overlap, but neither contains the other |
| ST_Relate | The spatial relationship between g1 and g2 matches a pattern defined by a Dimensionally Extended 9 Intersection Model (DE-9IM) matrix string |
| ST_Touches | g1 and g2 share at least one boundary point but no interior points |
| ST_Within | All points of g1 lie inside g2, and their interiors share at least one point (the converse of ST_Contains) |
ST_Contains
ST_Contains(g1, g2)Returns 1 if g1 completely contains g2—that is, all points of g2 lie inside g1, and the interiors of g1 and g2 share at least one point. Returns 0 otherwise.
The boundary of g1 is not part of its interior. A point that lies exactly on the boundary of g1 is not contained by g1.
Return type: INT
Relationship to ST_Within: ST_Contains(A, B) is the converse of ST_Within(B, A). Both return the same result.
Example:
SELECT ST_Contains(
ST_GeometryFromText('POLYGON ((1 1, 1 4, 4 4, 4 1))'),
ST_GeometryFromText('POINT (2 2)')
);Result:
+-----------------------------------------------------------------------------------------------------+
|ST_Contains(ST_GeometryFromText('POLYGON ((1 1, 1 4, 4 4, 4 1))'), ST_GeometryFromText('POINT (2 2)')) |
+-----------------------------------------------------------------------------------------------------+
| 1 |
+-----------------------------------------------------------------------------------------------------+ST_Crosses
ST_Crosses(g1, g2)Returns 1 if g1 and g2 spatially cross—that is, they share some interior points but not all. Returns 0 otherwise.
Return type: INT
Example:
SELECT ST_Crosses(
ST_GeometryFromText('POINT (20 20)'),
ST_GeometryFromText('POINT (25 25)')
);Result:
+----------------------------------------------------------------------------------------------+
|ST_Crosses(ST_GeometryFromText('POINT (20 20)'), ST_GeometryFromText('POINT (25 25)')) |
+----------------------------------------------------------------------------------------------+
| 0 |
+----------------------------------------------------------------------------------------------+ST_Disjoint
ST_Disjoint(g1, g2)Returns 1 if g1 and g2 are spatially disjoint—that is, they share no points at all. Returns 0 otherwise.
Return type: INT
Example:
SELECT ST_Disjoint(
ST_GeometryFromText('POINT (50 100)'),
ST_GeometryFromText('POINT (150 150)')
);Result:
+--------------------------------------------------------------------------------------------------+
|ST_Disjoint(ST_GeometryFromText('POINT (50 100)'), ST_GeometryFromText('POINT (150 150)')) |
+--------------------------------------------------------------------------------------------------+
| 1 |
+--------------------------------------------------------------------------------------------------+ST_Equals
ST_Equals(g1, g2)Returns 1 if g1 and g2 are spatially equal—that is, they occupy exactly the same set of points. Returns 0 otherwise.
Return type: INT
Example:
SELECT ST_Equals(
ST_GeometryFromText('POINT (50 100)'),
ST_GeometryFromText('POINT (150 150)')
);Result:
+------------------------------------------------------------------------------------------------+
|ST_Equals(ST_GeometryFromText('POINT (50 100)'), ST_GeometryFromText('POINT (150 150)')) |
+------------------------------------------------------------------------------------------------+
| 0 |
+------------------------------------------------------------------------------------------------+ST_Intersects
ST_Intersects(g1, g2)Returns 1 if g1 and g2 spatially intersect—that is, they share at least one point. Returns 0 otherwise.
Return type: INT
Example:
SELECT ST_Intersects(
ST_GeometryFromText('POINT (50 100)'),
ST_GeometryFromText('POINT (150 150)')
);Result:
+----------------------------------------------------------------------------------------------------+
|ST_Intersects(ST_GeometryFromText('POINT (50 100)'), ST_GeometryFromText('POINT (150 150)')) |
+----------------------------------------------------------------------------------------------------+
| 0 |
+----------------------------------------------------------------------------------------------------+ST_Overlaps
ST_Overlaps(g1, g2)Returns 1 if g1 and g2 spatially overlap—that is, they have the same dimension, share some points, but neither completely contains the other. Returns 0 otherwise.
Return type: INT
Example:
SELECT ST_Overlaps(
ST_GeometryFromText('POLYGON ((1 1, 1 4, 4 4, 4 1))'),
ST_GeometryFromText('POLYGON ((3 3, 3 5, 5 5, 5 3))')
);Result:
+---------------------------------------------------------------------------------------------------------------------------------+
|ST_Overlaps(ST_GeometryFromText('POLYGON ((1 1, 1 4, 4 4, 4 1))'), ST_GeometryFromText('POLYGON ((3 3, 3 5, 5 5, 5 3))')) |
+---------------------------------------------------------------------------------------------------------------------------------+
| 1 |
+---------------------------------------------------------------------------------------------------------------------------------+ST_Relate
ST_Relate(g1, g2, s1)Returns 1 if the spatial relationship between g1 and g2 matches the pattern specified by the DE-9IM matrix string s1. Returns 0 otherwise.
The Dimensionally Extended 9 Intersection Model (DE-9IM) describes the relationship between two geometries as a 9-character string using the symbols F, 0, 1, 2, T, and *. Use ST_Relate when no named function (such as ST_Contains or ST_Touches) covers the exact relationship you need to test.
Parameters:
| Parameter | Type | Description |
|---|---|---|
g1 |
geometry | The first geometry |
g2 |
geometry | The second geometry |
s1 |
VARCHAR | A DE-9IM matrix pattern string (for example, 'T*****FF*') |
Return type: INT
Example:
SELECT ST_Relate(
ST_GeometryFromText('LINESTRING (0 0, 3 3)'),
ST_GeometryFromText('LINESTRING (1 1, 4 1)'),
'****T****'
);Result:
+--------------------------------------------------------------------------------------------------------------------------+
|ST_Relate(ST_GeometryFromText('LINESTRING (0 0, 3 3)'), ST_GeometryFromText('LINESTRING (1 1, 4 1)'), '****T****') |
+--------------------------------------------------------------------------------------------------------------------------+
| 0 |
+--------------------------------------------------------------------------------------------------------------------------+ST_Touches
ST_Touches(g1, g2)Returns 1 if g1 and g2 spatially touch—that is, they share at least one boundary point but no interior points. Returns 0 otherwise.
Return type: INT
Example:
SELECT ST_Touches(
ST_GeometryFromText('POINT (50 100)'),
ST_GeometryFromText('POINT (150 150)')
);Result:
+-------------------------------------------------------------------------------------------------+
|ST_Touches(ST_GeometryFromText('POINT (50 100)'), ST_GeometryFromText('POINT (150 150)')) |
+-------------------------------------------------------------------------------------------------+
| 0 |
+-------------------------------------------------------------------------------------------------+ST_Within
ST_Within(g1, g2)Returns 1 if g1 lies entirely within g2—that is, all points of g1 are inside g2, and the interiors of g1 and g2 share at least one point. Returns 0 otherwise.
Return type: BOOLEAN
Relationship to ST_Contains: ST_Within(A, B) is the converse of ST_Contains(B, A). Both return the same result.
Example:
SELECT ST_Within(
ST_GeometryFromText('POINT (50 100)'),
ST_GeometryFromText('POINT (150 150)')
);Result:
+-------------------------------------------------------------------------------------------------+
|ST_Within(ST_GeometryFromText('POINT (50 100)'), ST_GeometryFromText('POINT (150 150)')) |
+-------------------------------------------------------------------------------------------------+
| 0 |
+-------------------------------------------------------------------------------------------------+