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


12.17.13 空間の便利な関数

このセクションの関数は、ジオメトリ値に対する便利な操作を提供します。

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

  • いずれかの引数が NULL の場合、戻り値は NULL です。

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

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

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

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

次の便利な関数を使用できます:

  • ST_Distance_Sphere(g1, g2 [, radius])

    スフィア上の Point または MultiPoint 引数間の最小球面距離をメートル単位で返します。 (汎用の距離計算については、ST_Distance() 関数を参照してください。) オプションの radius 引数はメートル単位で指定する必要があります。

    両方のジオメトリパラメータが SRID 0 の有効なデカルト Point 値または MultiPoint 値である場合、戻り値は指定された半径を持つ球上の 2 つのジオメトリ間の最短距離です。 省略すると、デフォルトの半径は 6,370,986 メートル、点 X および Y 座標はそれぞれ経度および緯度 (度) として解釈されます。

    地理空間参照システム (SRS) で両方のジオメトリパラメータが有効な Point 値または MultiPoint 値である場合、戻り値は球上の 2 つのジオメトリ間の最短距離となり、半径が指定されます。 省略した場合、デフォルトの半径は (2a+b)/3,として定義された平均半径と等しくなります。a は半主軸、b は SRS の半最小軸です。

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

    • サポートされているジオメトリ引数の組合せは、PointPoint、または PointMultiPoint (任意の引数の順序) です。 少なくともいずれかのジオメトリが Point でも MultiPoint でもなく、SRID が 0 の場合、ER_NOT_IMPLEMENTED_FOR_CARTESIAN_SRS エラーが発生します。 少なくともいずれかのジオメトリが Point でも MultiPoint でもなく、SRID が地理 SRS を参照している場合は、ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS エラーが発生します。 ジオメトリが投影 SRS を参照している場合、ER_NOT_IMPLEMENTED_FOR_PROJECTED_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 で別の単位が使用されている場合、範囲ではその単位に対応する値が使用されます。 浮動小数点演算のため、正確な範囲制限はわずかに偏差します。

    • radius 引数が存在するが正でない場合は、ER_NONPOSITIVE_RADIUS エラーが発生します。

    • 距離が倍精度数値の範囲を超えると、ER_STD_OVERFLOW_ERROR エラーが発生します。

    mysql> SET @pt1 = ST_GeomFromText('POINT(0 0)');
    mysql> SET @pt2 = ST_GeomFromText('POINT(180 0)');
    mysql> SELECT ST_Distance_Sphere(@pt1, @pt2);
    +--------------------------------+
    | ST_Distance_Sphere(@pt1, @pt2) |
    +--------------------------------+
    |             20015042.813723423 |
    +--------------------------------+
  • ST_IsValid(g)

    引数がジオメトリ学的に有効な場合は 1 を返し、ジオメトリ学的に有効でない場合は 0 を返します。 ジオメトリの有効性は OGC 仕様で定義されます。

    有効な空のジオメトリのみが、空のジオメトリコレクション値の形式で表されます。 この場合、ST_IsValid() は 1 を返します。 MySQL は、POINT EMPTY などの GIS の EMPTY 値をサポートしていません。

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

    • ジオメトリに経度または緯度が範囲外の地理 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 で別の単位が使用されている場合、範囲ではその単位に対応する値が使用されます。 浮動小数点演算のため、正確な範囲制限はわずかに偏差します。

    mysql> SET @ls1 = ST_GeomFromText('LINESTRING(0 0,-0.00 0,0.0 0)');
    mysql> SET @ls2 = ST_GeomFromText('LINESTRING(0 0, 1 1)');
    mysql> SELECT ST_IsValid(@ls1);
    +------------------+
    | ST_IsValid(@ls1) |
    +------------------+
    |                0 |
    +------------------+
    mysql> SELECT ST_IsValid(@ls2);
    +------------------+
    | ST_IsValid(@ls2) |
    +------------------+
    |                1 |
    +------------------+
  • ST_MakeEnvelope(pt1, pt2)

    PointLineString または Polygon として、2 つの点を中心にエンベロープを形成する矩形を返します。

    計算は、球、回転楕円体、または地球でではなくデカルト座標系を使用して行われます。

    pt1pt2 の 2 つの点を指定すると、ST_MakeEnvelope() は次のような抽象平面上に結果ジオメトリを作成します:

    • pt1pt2 が等しい場合、結果はポイント pt1 になります。

    • それ以外の場合、(pt1, pt2) が垂直または水平線セグメントの場合、結果は線セグメント (pt1, pt2) になります。

    • それ以外の場合、結果は pt1 および pt2 を対角ポイントとして使用するポリゴンになります。

    結果のジオメトリの SRID は 0 です。

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

    • 引数が Point 値でない場合は、ER_WRONG_ARGUMENTS エラーが発生します。

    • 2 つの点の座標値が無限または NaN であるという追加条件で、ER_GIS_INVALID_DATA エラーが発生します。

    • 地理空間参照システム (SRS) の SRID 値を持つジオメトリがある場合、ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS エラーが発生します。

    mysql> SET @pt1 = ST_GeomFromText('POINT(0 0)');
    mysql> SET @pt2 = ST_GeomFromText('POINT(1 1)');
    mysql> SELECT ST_AsText(ST_MakeEnvelope(@pt1, @pt2));
    +----------------------------------------+
    | ST_AsText(ST_MakeEnvelope(@pt1, @pt2)) |
    +----------------------------------------+
    | POLYGON((0 0,1 0,1 1,0 1,0 0))         |
    +----------------------------------------+
  • ST_Simplify(g, max_distance)

    Douglas-Peucker アルゴリズムを使用してジオメトリを簡略化し、同じタイプの簡略化された値を返します。

    ジオメトリは任意のジオメトリタイプにできますが、Douglas-Peucker アルゴリズムは実際にはすべてのタイプを処理するわけではありません。 ジオメトリコレクションは、そのコンポーネントに 1 つずつ簡略化アルゴリズムを指定することで処理され、戻されたジオメトリは結果としてジオメトリコレクションに格納されます。

    max_distance 引数は、削除する頂点から他のセグメントまでの距離 (入力座標の単位) です。 簡略化された線ストリングのこの距離内の頂点が削除されます。

    Boost.Geometry によると、ジオメトリは簡略化プロセスの結果として無効になり、プロセスによって自己交差が作成される可能性があります。 結果の妥当性をチェックするには、ST_IsValid() に渡します。

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

    • max_distance 引数が正でないか、NaN である場合、ER_WRONG_ARGUMENTS エラーが発生します。

    mysql> SET @g = ST_GeomFromText('LINESTRING(0 0,0 1,1 1,1 2,2 2,2 3,3 3)');
    mysql> SELECT ST_AsText(ST_Simplify(@g, 0.5));
    +---------------------------------+
    | ST_AsText(ST_Simplify(@g, 0.5)) |
    +---------------------------------+
    | LINESTRING(0 0,0 1,1 1,2 3,3 3) |
    +---------------------------------+
    mysql> SELECT ST_AsText(ST_Simplify(@g, 1.0));
    +---------------------------------+
    | ST_AsText(ST_Simplify(@g, 1.0)) |
    +---------------------------------+
    | LINESTRING(0 0,3 3)             |
    +---------------------------------+
  • ST_Validate(g)

    OGC 仕様に従ってジオメトリを検証します。 ジオメトリは構文的に整形式 (WKB 値と SRID) にすることができますが、ジオメトリ学的には無効です。 たとえば、このポリゴンはジオメトリ学的に無効です: POLYGON((0 0, 0 0, 0 0, 0 0, 0 0))

    ST_Validate() は、ジオメトリが構文的に整形式でジオメトリが有効な場合はジオメトリを戻し、引数が構文的に整形式でないか、形状的に有効でないか、または NULL である場合は NULL を戻します。

    ST_Validate() を使用すると、コストがかかりますが、無効なジオメトリデータをフィルタ処理で除外できます。 無効なデータによって保持されないより正確な結果を必要とするアプリケーションの場合、このペナルティは価値がある可能性があります。

    ジオメトリ引数が有効な場合、入力 Polygon または MultiPolygon に時計回りのリングがある場合を除き、それらのリングは有効性をチェックする前に逆になります。 ジオメトリが有効な場合は、反転リングの値が返されます。

    有効な空のジオメトリのみが、空のジオメトリコレクション値の形式で表されます。 この場合、ST_Validate() はそれを直接返し、それ以上のチェックは行いません。

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

    • ジオメトリに経度または緯度が範囲外の地理 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)。

      表示される範囲は度数です。 浮動小数点演算のため、正確な範囲制限はわずかに偏差します。

    MySQL 8.0.13 より前では、ST_Validate() はこのセクションの概要で説明されているように引数を処理しますが、次の例外があります:

    • ジオメトリが構文的に整形式でない場合、戻り値は NULL です。 ER_GIS_INVALID_DATA エラーは発生しません。

    • ジオメトリに地理空間参照システム (SRS) の SRID 値がある場合、ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS エラーが発生します。

    mysql> SET @ls1 = ST_GeomFromText('LINESTRING(0 0)');
    mysql> SET @ls2 = ST_GeomFromText('LINESTRING(0 0, 1 1)');
    mysql> SELECT ST_AsText(ST_Validate(@ls1));
    +------------------------------+
    | ST_AsText(ST_Validate(@ls1)) |
    +------------------------------+
    | NULL                         |
    +------------------------------+
    mysql> SELECT ST_AsText(ST_Validate(@ls2));
    +------------------------------+
    | ST_AsText(ST_Validate(@ls2)) |
    +------------------------------+
    | LINESTRING(0 0,1 1)          |
    +------------------------------+

関連キーワード:  関数, ジオメトリ, 空間, エラー, 発生, 範囲, 処理, OUT, OF, RANGE