12.18.5.4. Functions for Testing Spatial Relations Between Geometric Objects

The functions described in these sections take two geometries as input parameters and return a qualitative or quantitative relation between them.

12.18.5.4.1. Relations on Geometry Minimal Bounding Rectangles (MBRs)

MySQL provides several functions that test relations between minimal bounding rectangles of two geometries g1 and g2. The return values 1 and 0 indicate true and false, respectively.

MBRContains(g1,g2)

Returns 1 or 0 to indicate whether the Minimum Bounding Rectangle of g1 contains the Minimum Bounding Rectangle of g2. This tests the opposite relationship as MBRWithin().

mysql> SET @g1 =
                        GeomFromText('Polygon((0 0,0 3,3 3,3 0,0 0))');mysql> SET @g2 = GeomFromText('Point(1
                        1)');mysql> SELECT MBRContains(@g1,@g2),
                        MBRContains(@g2,@g1);----------------------+----------------------+| MBRContains(@g1,@g2) | MBRContains(@g2,@g1) |+----------------------+----------------------+|                    1 |                    0 |+----------------------+----------------------+

MBRDisjoint(g1,g2)

Returns 1 or 0 to indicate whether the Minimum Bounding Rectangles of the two geometries g1 and g2 are disjoint (do not intersect).
MBREqual(g1,g2)

Returns 1 or 0 to indicate whether the Minimum Bounding Rectangles of the two geometries g1 and g2 are the same.
MBRIntersects(g1,g2)

Returns 1 or 0 to indicate whether the Minimum Bounding Rectangles of the two geometries g1 and g2 intersect.
MBROverlaps(g1,g2)

Returns 1 or 0 to indicate whether the Minimum Bounding Rectangles of the two geometries g1 and g2 overlap. The term spatially overlaps is used if two geometries intersect and their intersection results in a geometry of the same dimension but not equal to either of the given geometries.
MBRTouches(g1,g2)

Returns 1 or 0 to indicate whether the Minimum Bounding Rectangles of the two geometries g1 and g2 touch. Two geometries spatially touch if the interiors of the geometries do not intersect, but the boundary of one of the geometries intersects either the boundary or the interior of the other.

MBRWithin(g1,g2)

Returns 1 or 0 to indicate whether the Minimum Bounding Rectangle of g1 is within the Minimum Bounding Rectangle of g2. This tests the opposite relationship as MBRContains().

mysql> SET @g1 =
                        GeomFromText('Polygon((0 0,0 3,3 3,3 0,0 0))');mysql> SET @g2 = GeomFromText('Polygon((0 0,0 5,5 5,5 0,0
                        0))');mysql> SELECT MBRWithin(@g1,@g2),
                        MBRWithin(@g2,@g1);+--------------------+--------------------+| MBRWithin(@g1,@g2) | MBRWithin(@g2,@g1) |+--------------------+--------------------+|                  1 |                  0 |+--------------------+--------------------+

12.18.5.4.2. Functions That Test Spatial Relationships Between Geometries

The OpenGIS specification defines the following functions. They test the relationship between two geometry values g1 and g2.

The return values 1 and 0 indicate true and false, respectively.

Note

MySQL originally implemented these functions such that they used object bounding rectangles and returned the same result as the corresponding MBR-based functions. As of MySQL 5.6.1, corresponding versions are available that use precise object shapes. These versions are named with an ST_ prefix. For example, Contains() uses object bounding rectangles, whereas ST_Contains() uses object shapes.

As of MySQL 5.6.1, there are also ST_ aliases for existing spatial functions that were already exact. For example, ST_IsEmpty() is an alias for IsEmpty()

Functions That Use Object Shapes

ST_Contains(g1,g2)

Returns 1 or 0 to indicate whether g1 completely contains g2. This tests the opposite relationship as ST_Within().
ST_Crosses(g1,g2)

Returns 1 if g1 spatially crosses g2. Returns NULL if g1 is a Polygon or a MultiPolygon, or if g2 is a Point or a MultiPoint. Otherwise, returns 0.

The term spatially crosses denotes a spatial relation between two given geometries that has the following properties:
- The two geometries intersect
- Their intersection results in a geometry that has a dimension that is one less than the maximum dimension of the two given geometries
- Their intersection is not equal to either of the two given geometries
ST_Disjoint(g1,g2)

Returns 1 or 0 to indicate whether g1 is spatially disjoint from (does not intersect) g2.
ST_Equals(g1,g2)

Returns 1 or 0 to indicate whether g1 is spatially equal to g2.
ST_Intersects(g1,g2)

Returns 1 or 0 to indicate whether g1 spatially intersects g2.
ST_Overlaps(g1,g2)

Returns 1 or 0 to indicate whether g1 spatially overlaps g2. The term spatially overlaps is used if two geometries intersect and their intersection results in a geometry of the same dimension but not equal to either of the given geometries.
ST_Touches(g1,g2)

Returns 1 or 0 to indicate whether g1 spatially touches g2. Two geometries spatially touch if the interiors of the geometries do not intersect, but the boundary of one of the geometries intersects either the boundary or the interior of the other.
ST_Within(g1,g2)

Returns 1 or 0 to indicate whether g1 is spatially within g2. This tests the opposite relationship as ST_Contains().

Functions That Use Bounding Rectangles

Contains(g1,g2)

Returns 1 or 0 to indicate whether g1 completely contains g2. This tests the opposite relationship as Within().
Crosses(g1,g2)

Returns 1 if g1 spatially crosses g2. Returns NULL if g1 is a Polygon or a MultiPolygon, or if g2 is a Point or a MultiPoint. Otherwise, returns 0.

The term spatially crosses denotes a spatial relation between two given geometries that has the following properties:
- The two geometries intersect
- Their intersection results in a geometry that has a dimension that is one less than the maximum dimension of the two given geometries
- Their intersection is not equal to either of the two given geometries
Disjoint(g1,g2)

Returns 1 or 0 to indicate whether g1 is spatially disjoint from (does not intersect) g2.
Equals(g1,g2)

Returns 1 or 0 to indicate whether g1 is spatially equal to g2.
Intersects(g1,g2)

Returns 1 or 0 to indicate whether g1 spatially intersects g2.
Overlaps(g1,g2)

Returns 1 or 0 to indicate whether g1 spatially overlaps g2. The term spatially overlaps is used if two geometries intersect and their intersection results in a geometry of the same dimension but not equal to either of the given geometries.
Touches(g1,g2)

Returns 1 or 0 to indicate whether g1 spatially touches g2. Two geometries spatially touch if the interiors of the geometries do not intersect, but the boundary of one of the geometries intersects either the boundary or the interior of the other.
Within(g1,g2)

Returns 1 or 0 to indicate whether g1 is spatially within g2. This tests the opposite relationship as Contains().