MySQL 8.0 リファレンスマニュアル


12.17.9.1 オブジェクト形状を使用する空間関係関数

OpenGIS 仕様では、正確なオブジェクト形状を使用して、g1g2 の 2 つのジオメトリ値間の関係をテストする次の関数が定義されています。 戻り値 1 および 0 はそれぞれ true および false を示しますが、距離関数は距離値を返します。

このセクションの関数は、デカルトまたは地理空間参照システム (SRS) の引数を検出し、SRS に適した結果を戻します。

特に指定がないかぎり、このセクションの関数はジオメトリ引数を次のように処理します:

  • 引数が NULL の場合、またはジオメトリ引数が空のジオメトリの場合、戻り値は NULL です。

  • ジオメトリ引数が構文的に整形式のジオメトリでない場合は、ER_GIS_INVALID_DATA エラーが発生します。

  • 未定義の空間参照システム (SRS) でジオメトリ引数が構文的に整形式のジオメトリである場合、ER_SRS_NOT_FOUND エラーが発生します。

  • 複数のジオメトリ引数を取る関数では、それらの引数が同じ SRS 内にない場合、ER_GIS_DIFFERENT_SRIDS エラーが発生します。

  • ジオメトリ学的に無効なジオメトリ引数がある場合は、結果が true または false (どちらでも定義されていない) か、エラーが発生します。

  • 地理 SRS ジオメトリ引数で、範囲外の経度または緯度を持つ引数がある場合、エラーが発生します:

    • 経度の値が (−180, 180]の範囲内にない場合は、ER_GEOMETRY_PARAM_LONGITUDE_OUT_OF_RANGE エラーが発生します (MySQL 8.0.12 より前の ER_LONGITUDE_OUT_OF_RANGE)。

    • 緯度の値が[−90, 90]の範囲内にない場合は、ER_GEOMETRY_PARAM_LATITUDE_OUT_OF_RANGE エラーが発生します (MySQL 8.0.12 より前の ER_LATITUDE_OUT_OF_RANGE)。

    表示される範囲は度数です。 SRS で別の単位が使用されている場合、範囲ではその単位に対応する値が使用されます。 浮動小数点演算のため、正確な範囲制限はわずかに偏差します。

  • それ以外の場合、戻り値は NULL 以外です。

このセクションの一部の関数では、戻り値の長さの単位を指定する unit 引数が許可されます。 特に指定がないかぎり、関数は単位引数を次のように処理します:

  • ユニットは、INFORMATION_SCHEMA ST_UNITS_OF_MEASURE テーブルで見つかった場合にサポートされます。 セクション26.37「INFORMATION_SCHEMA ST_UNITS_OF_MEASURE テーブル」を参照してください。

  • ユニットが指定されているが、MySQL でサポートされていない場合は、ER_UNIT_NOT_FOUND エラーが発生します。

  • サポートされている線形単位が指定され、SRID が 0 の場合、ER_GEOMETRY_IN_UNKNOWN_LENGTH_UNIT エラーが発生します。

  • サポートされている線形単位が指定され、SRID が 0 でない場合、結果はその単位になります。

  • 単位が指定されていない場合、結果はデカルトか地理的かにかかわらず、ジオメトリの SRS の単位になります。 現在、すべての MySQL SRS はメーターで表されます。

ジオメトリ関係のテストには、次のオブジェクト形状関数を使用できます:

  • ST_Contains(g1, g2)

    g1g2 を完全に含んでいるかどうかを示す 1 または 0 を返します。 これは、ST_Within() とは逆の関係をテストします。

    ST_Contains() は、このセクションの概要で説明されているように引数を処理します。

  • ST_Crosses(g1, g2)

    空間リレーションに次のプロパティがある場合、2 つのジオメトリが空間的に交差になります:

    • g1g2 の両方がディメンション 1 でない場合: g2 の内部に g1 の内部と共通の点があるが、g2g1 の内部全体をカバーしていない場合、g1g2 を横断します。

    • g1g2 の両方がディメンション 1 の場合: 有限の数の点で線が相互に交差する場合 (つまり、共通の線セグメントがない場合、共通の単一の点のみ)。

    この関数は、g1g2 を空間的に横断するかどうかを示す 1 または 0 を戻します。

    ST_Crosses() は、次の追加条件で戻り値が NULL であることを除き、このセクションの概要で説明されているように引数を処理します:

    • g1 のディメンションは 2 (Polygon または MultiPolygon) です。

    • g2 のディメンションは 1 (Point または MultiPoint) です。

  • ST_Disjoint(g1, g2)

    g1g2 と空間的に切り離されている (交差していない) かどうかを示す 1 または 0 を返します。

    ST_Disjoint() は、このセクションの概要で説明されているように引数を処理します。

  • ST_Distance(g1, g2 [, unit])

    g1g2 の間の距離を戻します。ジオメトリ引数の空間参照システム (SRS) の長さ単位で測定されるか、オプションの unit 引数 (指定されている場合) の単位で測定されます。

    この関数は、2 つのジオメトリ引数のコンポーネントのすべての組合せ間の最短距離を戻すことで、ジオメトリコレクションを処理します。

    ST_Distance() は、このセクションの概要で説明されているようにジオメトリ引数を処理しますが、次の例外があります:

    • ST_Distance() は、地理的 (楕円体) 空間参照システム内の引数を検出し、楕円体上の測地距離を戻します。 MySQL 8.0.18 では、ST_Distance() はすべてのジオメトリタイプの地理 SRS 引数の距離計算をサポートしています。 MySQL 8.0.18 より前では、許可されている地理的引数の型は、PointPoint、または PointMultiPoint (任意の引数の順序) のみです。 地理 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)

    g1g2 と空間的に等しいかどうかを示す 1 または 0 を返します。

    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])

    ジオメトリがどの程度類似しているかを反映して、2 つのジオメトリ間の離散フレシェ距離を返します。 結果は、ジオメトリ引数の空間参照システム (SRS) の長さ単位、または引数が指定されている場合は unit 引数の長さ単位で測定された倍精度の数値です。

    この関数は、離散フレシェ距離を実装します。つまり、ジオメトリの点間の距離に制限されます。 たとえば、2 つの LineString 引数がある場合、ジオメトリに明示的に記述された点のみが考慮されます。 これらの点の間の線分セグメント上の点は考慮されません。

    ST_FrechetDistance() は、このセクションの概要で説明されているようにジオメトリ引数を処理しますが、次の例外があります:

    • ジオメトリはデカルトまたは地理 SRS を持つことができますが、LineString 値のみがサポートされています。 引数が同一のデカルト SRS または地理 SRS 内にあり、どちらかが LineString でない場合は、SRS タイプに応じて ER_NOT_IMPLEMENTED_FOR_CARTESIAN_SRS または ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS エラーが発生します。

    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])

    ジオメトリがどの程度類似しているかを反映して、2 つのジオメトリ間の離散ハスドルフ距離を返します。 結果は、ジオメトリ引数の空間参照システム (SRS) の長さ単位、または引数が指定されている場合は unit 引数の長さ単位で測定された倍精度の数値です。

    この関数は、離散ハスドルフ距離を実装します。つまり、ジオメトリの点間の距離に制限されます。 たとえば、2 つの LineString 引数がある場合、ジオメトリに明示的に記述された点のみが考慮されます。 これらの点の間の線分セグメント上の点は考慮されません。

    ST_HausdorffDistance() は、このセクションの概要で説明されているようにジオメトリ引数を処理しますが、次の例外があります:

    • ジオメトリ引数が同じデカルト SRS または地理 SRS 内にあるが、サポートされている組合せにない場合は、SRS タイプに応じて ER_NOT_IMPLEMENTED_FOR_CARTESIAN_SRS または ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_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)

    g1g2 と空間的に交差しているかどうかを示す 1 または 0 を返します。

    ST_Intersects() は、このセクションの概要で説明されているように引数を処理します。

  • ST_Overlaps(g1, g2)

    2 つのジオメトリが交差し、その交差によって同じディメンションのジオメトリが生成され、指定されたジオメトリのいずれとも等しくない場合、これらのジオメトリは空間的にオーバーラップになります。

    この関数は、g1g2 と空間的にオーバーラップするかどうかを示す 1 または 0 を戻します。

    ST_Overlaps() は、このセクションの概要で説明されているように引数を処理します。ただし、戻り値は、2 つのジオメトリのディメンションが等しくないという追加条件では NULL です。

  • ST_Touches(g1, g2)

    内部が交差しないが、いずれかのジオメトリの境界が他のジオメトリの境界または内部と交差する場合、2 つのジオメトリは空間的なタッチです。

    この関数は、g1g2 に空間的に接触するかどうかを示す 1 または 0 を戻します。

    ST_Touches() では、両方のジオメトリのディメンションが 0 (Point または MultiPoint) である追加条件の戻り値が NULL であることを除き、このセクションの概要で説明するように引数が処理されます。

  • ST_Within(g1, g2)

    g1 が空間的に g2 の内部にあるかどうかを示す 1 または 0 を返します。 これは、ST_Contains() とは逆の関係をテストします。

    ST_Within() は、このセクションの概要で説明されているように引数を処理します。


関連キーワード:  関数, ジオメトリ, 空間, 処理, セクション, 距離, 単位, エラー, 発生, 概要