Documentation Home
MySQL 8.0 参考手册

12.17.9.1 使用对象形状的空间关系函数

OpenGIS 规范定义了以下函数，使用精确的对象形状来测试两个几何值g1和 之间的关系 。g2返回值 1 和 0 分别表示 true 和 false，除了距离函数返回距离值。

本节中的函数检测笛卡尔或地理空间参考系统 (SRS) 中的参数，并返回适合 SRS 的结果。

除非另有说明，本节中的函数按如下方式处理它们的几何参数：

  • 如果任何参数是NULL或任何几何参数是空几何，则返回值为 NULL。

  • 如果任何几何参数不是语法上格式正确的几何， ER_GIS_INVALID_DATA则会发生错误。

  • 如果任何几何参数是未定义空间参考系统 (SRS) 中语法上格式正确的几何， ER_SRS_NOT_FOUND则会发生错误。

  • 对于采用多个几何参数的函数，如果这些参数不在同一个 SRS 中， ER_GIS_DIFFERENT_SRIDS则会发生错误。

  • 如果任何几何参数在几何上无效，则结果为真或假（未定义哪个），或者发生错误。

  • 对于地理 SRS 几何参数，如果任何参数的经度或纬度超出范围，则会发生错误：

    显示的范围以度为单位。如果 SRS 使用另一个单位，则范围使用其单位中的相应值。由于浮点运算，确切的范围限制略有偏差。

  • 否则，返回值为非NULL。

本节中的某些函数允许使用单位参数来指定返回值的长度单位。除非另有说明，否则函数按如下方式处理它们的单位参数：

这些对象形状函数可用于测试几何关系：

  • ST_Contains(g1, g2)

    返回 1 或 0 表示是否 g1完全包含 g2. 这测试相反的关系作为ST_Within()。

    ST_Contains()如本节介绍中所述处理其参数。

  • ST_Crosses(g1, g2)

    如果两个几何图形的空间关系具有以下属性，则它们在空间 上交叉：

    • 除非g1和 g2都是维度 1： 如果 的内部 与 的内部有共同点，但 不覆盖 的整个内部，则g1交叉 。 g2g2g1g2g1

    • 如果g1和 g2都是维度 1：如果直线在有限数量的点上相互交叉（即没有公共线段，只有单个公共点）。

    此函数返回 1 或 0 以指示是否在 g1空间上交叉 g2。

    ST_Crosses()如本节介绍中所述处理其参数，但返回值NULL用于这些附加条件：

    • g1维度为 2（Polygon或 MultiPolygon）。

    • g2维度为 1（Point或 MultiPoint）。

  • ST_Disjoint(g1, g2)

    返回 1 或 0 以指示 g1在空间上是否与（不相交）不相交g2。

    ST_Disjoint()如本节介绍中所述处理其参数。

  • ST_Distance(g1, g2 [, unit])

    g1 返回和 之间的距离g2，以几何参数的空间参考系统 (SRS) 的长度单位测量，或者以 unit指定的可选参数的单位测量。

    此函数通过返回两个几何参数的组件的所有组合之间的最短距离来处理几何集合。

    ST_Distance()如本节介绍中所述处理其几何参数，但有以下例外：

    • ST_Distance()检测地理（椭圆体）空间参考系统中的参数并返回椭圆体上的大地距离。从 MySQL 8.0.18 开始， ST_Distance()支持所有几何类型的地理 SRS 参数的距离计算。在 MySQL 8.0.18 之前，唯一允许的地理参数类型是 Pointand Point，或Pointand MultiPoint（以任何参数顺序）。如果在地理 SRS 中使用其他几何类型参数组合调用， ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS 则会发生错误。

    • 如果任何参数在几何上无效，则结果要么是未定义的距离（即，它可以是任何数字），要么会发生错误。

    • 如果中间或最终结果产生 NaN或为负数， ER_GIS_INVALID_DATA 则会发生错误。

    从 MySQL 8.0.14 开始， ST_Distance()允许一个可选unit参数指定返回距离值的线性单位。 如本节介绍中所述 ST_Distance()处理其 参数。unit

    mysql> SET @g1 = ST_GeomFromText('POINT(1 1)');
mysql> SET @g2 = ST_GeomFromText('POINT(2 2)');
mysql> SELECT ST_Distance(@g1, @g2);
+-----------------------+
| ST_Distance(@g1, @g2) |
+-----------------------+
|    1.4142135623730951 |
+-----------------------+

mysql> SET @g1 = ST_GeomFromText('POINT(1 1)', 4326);
mysql> SET @g2 = ST_GeomFromText('POINT(2 2)', 4326);
mysql> SELECT ST_Distance(@g1, @g2);
+-----------------------+
| ST_Distance(@g1, @g2) |
+-----------------------+
|     156874.3859490455 |
+-----------------------+
mysql> SELECT ST_Distance(@g1, @g2, 'metre');
+--------------------------------+
| ST_Distance(@g1, @g2, 'metre') |
+--------------------------------+
|              156874.3859490455 |
+--------------------------------+
mysql> SELECT ST_Distance(@g1, @g2, 'foot');
+-------------------------------+
| ST_Distance(@g1, @g2, 'foot') |
+-------------------------------+
|             514679.7439273146 |
+-------------------------------+

    对于球体上距离计算的特殊情况，请参见ST_Distance_Sphere() 函数。

  • ST_Equals(g1, g2)

    返回 1 或 0 以指示 g1在空间上是否等于 g2.

    ST_Equals()如本节介绍中所述处理其参数，除了它不返回NULL空几何参数。 

    mysql> SET @g1 = Point(1,1), @g2 = Point(2,2);
mysql> SELECT ST_Equals(@g1, @g1), ST_Equals(@g1, @g2);
+---------------------+---------------------+
| ST_Equals(@g1, @g1) | ST_Equals(@g1, @g2) |
+---------------------+---------------------+
|                   1 |                   0 |
+---------------------+---------------------+

  • ST_FrechetDistance(g1, g2 [, unit])

    返回两个几何之间的离散 Fréchet 距离，反映几何的相似程度。结果是一个双精度数字，以几何参数的空间参考系统 (SRS) 的长度单位测量，或者以参数的长度单位测量（ unit如果给定了该参数）。

    此函数实现离散 Fréchet 距离，这意味着它仅限于几何点之间的距离。例如，给定两个 LineString参数，仅考虑几何中明确提及的点。不考虑这些点之间的线段上的点。

    ST_FrechetDistance()如本节介绍中所述处理其几何参数，但有以下例外：

    ST_FrechetDistance()unit如本节介绍中所述 处理其可选参数。

    mysql> SET @ls1 = ST_GeomFromText('LINESTRING(0 0,0 5,5 5)');
mysql> SET @ls2 = ST_GeomFromText('LINESTRING(0 1,0 6,3 3,5 6)');
mysql> SELECT ST_FrechetDistance(@ls1, @ls2);
+--------------------------------+
| ST_FrechetDistance(@ls1, @ls2) |
+--------------------------------+
|             2.8284271247461903 |
+--------------------------------+

mysql> SET @ls1 = ST_GeomFromText('LINESTRING(0 0,0 5,5 5)', 4326);
mysql> SET @ls2 = ST_GeomFromText('LINESTRING(0 1,0 6,3 3,5 6)', 4326);
mysql> SELECT ST_FrechetDistance(@ls1, @ls2);
+--------------------------------+
| ST_FrechetDistance(@ls1, @ls2) |
+--------------------------------+
|              313421.1999416798 |
+--------------------------------+
mysql> SELECT ST_FrechetDistance(@ls1, @ls2, 'foot');
+----------------------------------------+
| ST_FrechetDistance(@ls1, @ls2, 'foot') |
+----------------------------------------+
|                     1028284.7767115477 |
+----------------------------------------+

    MySQL 8.0.23 新增此功能。

  • ST_HausdorffDistance(g1, g2 [, unit])

    返回两个几何之间的离散 Hausdorff 距离，反映几何的相似程度。结果是一个双精度数字，以几何参数的空间参考系统 (SRS) 的长度单位测量，或者以参数的长度单位测量（ unit如果给定了该参数）。

    此函数实现离散 Hausdorff 距离，这意味着它仅限于几何点之间的距离。例如，给定两个 LineString参数，仅考虑几何中明确提及的点。不考虑这些点之间的线段上的点。

    ST_HausdorffDistance() 如本节介绍中所述处理其几何参数，但有以下例外：

    • 如果几何参数在相同的笛卡尔或地理 SRS 中，但不在受支持的组合中， 则会发生ER_NOT_IMPLEMENTED_FOR_CARTESIAN_SRS 或 ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS 错误，具体取决于 SRS 类型。支持这些组合：

      • LineString和 LineString

      • Point和 MultiPoint

      • LineString和 MultiLineString

      • MultiPoint和 MultiPoint

      • MultiLineString和 MultiLineString

    ST_HausdorffDistance()unit 如本节介绍中所述 处理其可选参数。

    mysql> SET @ls1 = ST_GeomFromText('LINESTRING(0 0,0 5,5 5)');
mysql> SET @ls2 = ST_GeomFromText('LINESTRING(0 1,0 6,3 3,5 6)');
mysql> SELECT ST_HausdorffDistance(@ls1, @ls2);
+----------------------------------+
| ST_HausdorffDistance(@ls1, @ls2) |
+----------------------------------+
|                                1 |
+----------------------------------+

mysql> SET @ls1 = ST_GeomFromText('LINESTRING(0 0,0 5,5 5)', 4326);
mysql> SET @ls2 = ST_GeomFromText('LINESTRING(0 1,0 6,3 3,5 6)', 4326);
mysql> SELECT ST_HausdorffDistance(@ls1, @ls2);
+----------------------------------+
| ST_HausdorffDistance(@ls1, @ls2) |
+----------------------------------+
|               111319.49079326246 |
+----------------------------------+
mysql> SELECT ST_HausdorffDistance(@ls1, @ls2, 'foot');
+------------------------------------------+
| ST_HausdorffDistance(@ls1, @ls2, 'foot') |
+------------------------------------------+
|                        365221.4264870815 |
+------------------------------------------+

    MySQL 8.0.23 新增此功能。

  • ST_Intersects(g1, g2)

    返回 1 或 0 以指示是否在 g1空间上相交 g2。

    ST_Intersects()如本节介绍中所述处理其参数。

  • ST_Overlaps(g1, g2)

    如果两个几何图形相交并且它们的相交导致具有相同维度但不等于任何给定几何图形的几何图形，则它们在 空间上重叠。

    此函数返回 1 或 0 以指示是否在 g1空间上重叠 g2。

    ST_Overlaps()如本节介绍中所述处理其参数，但返回值是NULL针对两个几何尺寸不相等的附加条件。

  • ST_Touches(g1, g2)

    如果两个几何体的内部不相交，但其中一个几何体的边界与另一个几何体的边界或内部相交，则 两个几何体在空间上接触。

    此函数返回 1 或 0 以指示是否在 g1空间上接触 g2。

    ST_Touches()按照本节介绍中的描述处理其参数，除了返回值是NULL针对两个几何图形均为 0 维（Point或 MultiPoint）的附加条件。

  • ST_Within(g1, g2)

    返回 1 或 0 以指示是否 g1在空间范围内 g2。这测试相反的关系作为 ST_Contains()。

    ST_Within()如本节介绍中所述处理其参数。