Functions for spatial relationships - - Alibaba Cloud Documentation Center

Functions for spatial relationships check relationships between two geometry objects, such as whether two geometry objects intersect, overlap, contain each other, or share identical spatial structures. Functions for spatial relationships can be used together with other spatio-temporal functions, such as constructor functions and output functions. This topic describes spatio-temporal relationship functions supported by the Lindorm streaming engine.

Functions

Function	Description
ST_Contains	Checks whether the first geometry object that you specify contains the second geometry object that you specify. If the first geometry object contains the second geometry object, this function returns true.
ST_DWithin	Checks whether the 2D distance between two geometry objects is within the specified range. If the 2D distance between the objects is within the specified range, this function returns true.
ST_DWithinSphere	Checks whether the spherical distance between two geometry objects is within the specified range. If the spherical distance between the objects is within the specified range, this function returns true.
ST_Intersects	Checks whether two geometry objects intersect. If the two geometry objects have any shared spatial space, this function determines that the two objects intersect and returns true.
ST_Overlaps	Checks whether two geometry objects spatially overlap but one is not contained in the other. If the two geometry objects spatially overlap but one is not contained in the other, this function returns true.
ST_Within	Checks whether the second geometry object that you specify is completely within the first geometry object that you specify. If the second geometry object is completely within the first geometry object, this function returns true.
ST_Equals	Checks whether two geometry objects are spatially equal. If the two geometry objects are spatially equal, this function returns true.

ST_Contains

You can call the ST_Contains function to check whether the first geometry object that you specify contains the second geometry object that you specify. If the first geometry object contains the second geometry object, this function returns true.

Syntax

Check whether the first geometry object that you specify contains the second geometry object that you specify.
```
boolean ST_Contains(geometry geomA,geometry geomB)
```
Check whether the specified geometry object contains a specific point defined by its coordinates (x, y).
```
boolean ST_Contains(geometry geom,double x,double y)
```

Parameters

Parameter	Description
geomA	The first geometry object that you want to specify.
geomB	The second geometry object that you want to specify.
geom	The geometry object that you want to specify.
x	The longitude of the point object.
y	The latitude of the point object.

Note

If all points of geomB are contained in the interior or on the boundary of geomA, geomA contains geomB.
ST_Contains is the inverse function of ST_Within. The returned results of ST_Contains(A,B) and ST_Within(B,A) are the same.

Examples

Example 1:

SELECT ST_Contains(ST_GeomFromText('POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))'), ST_GeomFromText('POINT(5 5)')) AS iscontain;

The following result is returned:

+-----------+
| iscontain |
+-----------+
| true      |
+-----------+

Example 2:

SELECT ST_Contains(ST_GeomFromText('POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))'),5,5) AS iscontain;

The following result is returned:

+-----------+
| iscontain |
+-----------+
| true      |
+-----------+

Example 3:

SELECT ST_Contains(ST_GeomFromText('POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))'), ST_GeomFromText('POINT(180 23)')) AS iscontain;

The following result is returned:

+-----------+
| iscontain |
+-----------+
| false     |
+-----------+

Example 4:

SELECT ST_Contains(ST_GeomFromText('POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))'),180,23) AS iscontain;

The following result is returned:

+-----------+
| iscontain |
+-----------+
| false     |
+-----------+

ST_DWithin

You can call the ST_DWithin function to check whether the 2D distance between two geometry objects is within the specified range. If the 2D distance between the objects is within the specified range, this function returns true.

Syntax

Check whether the 2D distance between two geometry objects is within the specified range.
```
boolean ST_DWithin(geometry geomA, geometry geomB, double distanceOfSrid)
```
Check whether the 2D distance between a geometry object and the specified point object is within the specified range.
```
boolean ST_DWithin(geometry geom, double x, double y, double distanceOfSrid)
```

Parameters

Parameter	Description
geomA	The first geometry object that you want to specify.
geomB	The second geometry object that you want to specify.
distanceOfSrid	The distance in Spatial Reference System Identifier (SRID) 4326. Unit: degree.
geom	The geometry object that you want to specify.
x	The longitude of the point object.
y	The latitude of the point object.

Note

You can specify a geometry object of the following types: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection.

Examples

Example 1:

SELECT ST_DWithin(ST_GeomFromText('POINT(5 5)'), ST_GeomFromText('POINT(6 6)'), 10) AS iswithin;

The following result is returned:

+----------+
| iswithin |
+----------+
| true     |
+----------+

Example 2:

SELECT ST_DWithin(ST_GeomFromText('POINT(5 5)'),6,6,10) AS iswithin;

The following result is returned:

+----------+
| iswithin |
+----------+
| true     |
+----------+

ST_DWithinSphere

You can call the ST_DWithinSphere function to check whether the spherical distance between two geometry objects is within the specified range. If the spherical distance between the objects is within the specified range, this function returns true.

Syntax

Check whether the spherical distance between two geometry objects is within the specified range.
```
boolean ST_DWithinSphere(geometry geomA, geometry geomB, double distance)
```
Check whether the spherical distance between a geometry object and the specified point object is within the specified range.
```
boolean ST_DWithinSPhere(geometry geom, double x, double y, double distance)
```

Parameters

Parameter	Description
geomA	The first geometry object that you want to specify.
geomB	The second geometry object that you want to specify.
distance	The distance that you want to specify. Unit: meters. The function may have an error of centimeters when it determines the spherical distance.
geom	The geometry object that you want to specify.
x	The longitude of the point object.
y	The latitude of the point object.

Note

You can specify a geometry object of the following types: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection.

Examples

Example 1:
```
SELECT ST_DWithinSphere(ST_GeomFromText('POINT(120 36)'), ST_GeomFromText('POINT(116 40)'), 570000) AS iswithin;
```
In this example, the spherical distance between the point (120,36) and the point (116,40) is 566034.7930717631 meters, which falls within the specified range. Therefore, the ST_DWithinSphere function returns true, as shown in the following result:
```
+----------+
| iswithin |
+----------+
| true     |
+----------+
```

Example 2:

SELECT ST_DWithinSphere(ST_GeomFromText('POINT(120 36)'),116,40,570000) AS iswithin;

The following result is returned:

+----------+
| iswithin |
+----------+
| true     |
+----------+

ST_Intersects

You can call the ST_Intersects function to check whether two geometry objects intersect. If the two geometry objects have any shared spatial space, ST_Intersects determines that the two objects intersect and returns true.

Syntax

Check whether two geometry objects intersect.

boolean ST_ Intersects(geometry geomA, geometry geomB)

Check whether a geometry object and the specified point object intersect.
```
boolean ST_ Intersects(geometry geom, double x, double y)
```

Parameters

Parameter	Description
geomA	The first geometry object that you want to specify.
geomB	The second geometry object that you want to specify.
geom	The geometry object that you want to specify.
x	The longitude of the point object.
y	The latitude of the point object.

Note

You can specify a geometry object of the following types: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection.

Examples

Example 1:

SELECT ST_Intersects(ST_GeomFromText('POINT(0 0)'), ST_GeomFromText('LINESTRING ( 2 0, 0 2 )')) AS isinter;

The following result is returned:

+---------+
| isinter |
+---------+
| false   |
+---------+

Example 2:

SELECT ST_Intersects(ST_GeomFromText('LINESTRING ( 2 0, 0 2 )'), 0, 0) AS isinter;

The following result is returned:

+---------+
| isinter |
+---------+
| false   |
+---------+

Example 3:

SELECT ST_Intersects(ST_GeomFromText('POINT(0 0)'), ST_GeomFromText('LINESTRING ( 0 0, 0 2 )')) AS isinter;

The following result is returned:

+---------+
| isinter |
+---------+
| true    |
+---------+

Example 4:

SELECT ST_Intersects(ST_GeomFromText('LINESTRING ( 0 0, 0 2 )'), 0, 0) AS isinter;

The following result is returned:

+---------+
| isinter |
+---------+
| true    |
+---------+

ST_Overlaps

You can call the ST_Overlaps object to check whether two geometry objects spatially overlap but one is not contained in the other. If the two geometry objects spatially overlap but one is not contained in the other, this function returns true.

Syntax

Check whether two geometry objects spatially overlap.
```
boolean ST_Overlaps(geometry geomA, geometry geomB)
```
Check whether a geometry object and the specified point object overlap.
```
boolean ST_Overlaps(geometry geom, double x, double y)
```

Parameters

Parameter	Description
geomA	The first geometry object that you want to specify.
geomB	The second geometry object that you want to specify.
geom	The geometry object that you want to specify.
x	The longitude of the point object.
y	The latitude of the point object.

Note

You can specify a geometry object of the following types: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection.

Examples

Example 1:

SELECT ST_Overlaps(ST_GeomFromText('LINESTRING(0 0,0 2)'),ST_GeomFromText('LINESTRING(0 1,0 3)')) as overlaps;

The following result is returned:

+----------+
| overlaps |
+----------+
| true     |
+----------+

Example 2:

SELECT ST_Overlaps(ST_GeomFromText('LINESTRING(0 0,0 2)'),ST_GeomFromText('POINT(0 1)')) as overlaps;

The following result is returned:

+----------+
| overlaps |
+----------+
| false    |
+----------+

Example 3:

SELECT ST_Overlaps(ST_GeomFromText('LINESTRING(0 0,0 2)'), 0, 1) as overlaps;

The following result is returned:

+----------+
| overlaps |
+----------+
| false    |
+----------+

ST_Within

You can call the ST_Within function to check whether the second geometry object that you specify is completely within the first geometry object that you specify. If the second geometry object is completely within the first geometry object, this function returns true.

Syntax

Check whether a geometry object is completely within another geometry object.
```
boolean ST_Within(geometry geomA, geometry geomB)
```
Check whether the specified point object is completely within a geometry object .
```
bboolean ST_Within(double x, double y, geometry geom)
```

Parameters

Parameter	Description
geomA	The first geometry object that you want to specify.
geomB	The second geometry object that you want to specify.
geom	The geometry object that you want to specify.
x	The longitude of the point object.
y	The latitude of the point object.

Note

You can specify a geometry object of the following types: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection.
If true is returned by both ST_Within(A,B) and ST_Within(B,A), A and B are geometry objects that are spatially equal.

Examples

Example 1:

SELECT ST_Within(ST_GeomFromText('POINT(5 5)'), ST_GeomFromText('POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))')) AS iswithin;

The following result is returned:

+----------+
| iswithin |
+----------+
| true     |
+----------+

Example 2:

SELECT ST_Within(5, 5, ST_GeomFromText('POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))')) AS iswithin;

The following result is returned:

+----------+
| iswithin |
+----------+
| true     |
+----------+

ST_Equals

You can call this function to check whether two geometry objects are spatially equal. If the two geometry objects are spatially equal, this function returns true.

Syntax

boolean ST_Equals(geometry geomA, geometry geomB);

Parameters

Parameter	Description
geomA	The first geometry object that you want to specify.
geomB	The second geometry object that you want to specify.

Note

If both the ST_Within(A,B) and ST_Within(B,A) functions return true, the two geometry objects are spatially equal. The order of points in the two geometry objects may vary, but the spatial structures are the same.
The function returns false if one of the two geometry objects is invalid.

Examples

Example 1: Check whether the spatial structures of two geometry objects namedLINESTRING(0 0, 10 10) and LINESTRING(0 0, 10 10) are the same.
```
SELECT ST_Equals(ST_GeomFromText('LINESTRING(0 0, 10 10)'),
    ST_GeomFromText('LINESTRING(0 0, 5 5, 10 10)'));
```
The returned result is true.

Example 2

SELECT ST_Equals(ST_GeomFromText('LINESTRING(0 0, 5 5)'),
    ST_GeomFromText('POINT(0 0)'));

The returned result is false.