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


12.17.8 空間演算子関数

OpenGIS では、ジオメトリを生成できる関数がいくつか提案されています。 これらは、空間演算子を実装するように設計されています。 これらの関数は、Open Geospatial Consortium 仕様に従って適用できないものを除き、すべての引数タイプの組合せをサポートします。

MySQL は、関数の説明に記載されているように、OpenGIS の拡張機能である特定の関数も実装します。

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

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

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

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

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

  • ジオメトリ引数に地理 SRS の SRID 値があり、関数が地理ジオメトリを処理しない場合は、ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS エラーが発生します。

  • 地理 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 以外です。

次の空間演算子関数を使用できます:

  • ST_Buffer(g, d [, strategy1 [, strategy2 [, strategy3]]])

    ジオメトリ値 g からの距離が d の距離以下であるすべての点を表すジオメトリを返します。

    ジオメトリ引数が空の場合、ST_Buffer() は空のジオメトリを戻します。

    距離が 0 の場合、ST_Buffer() はジオメトリ引数を変更せずに戻します:

    mysql> SET @pt = ST_GeomFromText('POINT(0 0)');
    mysql> SELECT ST_AsText(ST_Buffer(@pt, 0));
    +------------------------------+
    | ST_AsText(ST_Buffer(@pt, 0)) |
    +------------------------------+
    | POINT(0 0)                   |
    +------------------------------+

    ST_Buffer() では、Polygon 値と MultiPolygon 値、および Polygon 値または MultiPolygon 値を含むジオメトリコレクションに対して負の距離がサポートされています。 結果は空のジオメトリである可能性があります。

    ST_Buffer() では、distance 引数の後に最大 3 つのオプションの戦略引数を指定できます。 戦略はバッファ計算に影響します。 これらの引数は、ST_Buffer_Strategy() 関数によって生成されるバイト文字列値で、点、結合および終了方針に使用されます:

    • 点方針は、Point および MultiPoint ジオメトリに適用されます。 点ストラテジが指定されていない場合、デフォルトは ST_Buffer_Strategy('point_circle', 32) です。

    • 結合方法は、LineString, MultiLineString, Polygon および MultiPolygon ジオメトリに適用されます。 結合方針が指定されていない場合、デフォルトは ST_Buffer_Strategy('join_round', 32) です。

    • 終了方針は、LineString および MultiLineString ジオメトリに適用されます。 終了方針が指定されていない場合、デフォルトは ST_Buffer_Strategy('end_round', 32) です。

    各タイプの最大 1 つの戦略を指定でき、任意の順序で指定できます。

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

    • Point, MultiPoint, LineString の負の距離と MultiLineString 値、および Polygon または MultiPolygon 値を含まないジオメトリコレクションでは、ER_WRONG_ARGUMENTS エラーが発生します。

    • 特定のタイプの戦略が複数指定されている場合は、ER_WRONG_ARGUMENTS エラーが発生します。

    mysql> SET @pt = ST_GeomFromText('POINT(0 0)');
    mysql> SET @pt_strategy = ST_Buffer_Strategy('point_square');
    mysql> SELECT ST_AsText(ST_Buffer(@pt, 2, @pt_strategy));
    +--------------------------------------------+
    | ST_AsText(ST_Buffer(@pt, 2, @pt_strategy)) |
    +--------------------------------------------+
    | POLYGON((-2 -2,2 -2,2 2,-2 2,-2 -2))       |
    +--------------------------------------------+
    mysql> SET @ls = ST_GeomFromText('LINESTRING(0 0,0 5,5 5)');
    mysql> SET @end_strategy = ST_Buffer_Strategy('end_flat');
    mysql> SET @join_strategy = ST_Buffer_Strategy('join_round', 10);
    mysql> SELECT ST_AsText(ST_Buffer(@ls, 5, @end_strategy, @join_strategy))
    +---------------------------------------------------------------+
    | ST_AsText(ST_Buffer(@ls, 5, @end_strategy, @join_strategy))   |
    +---------------------------------------------------------------+
    | POLYGON((5 5,5 10,0 10,-3.5355339059327373 8.535533905932738, |
    | -5 5,-5 0,0 0,5 0,5 5))                                       |
    +---------------------------------------------------------------+
  • ST_Buffer_Strategy(strategy [, points_per_circle])

    この関数は、バッファの計算に影響を与えるために ST_Buffer() で使用する戦略バイト文字列を戻します。

    戦略に関する情報は、Boost.org で入手できます。

    最初の引数は、戦略オプションを示す文字列である必要があります:

    • ポイント戦略の場合、許可される値は'point_circle'および'point_square'です。

    • 結合方針の場合、許可される値は'join_round'および'join_miter'です。

    • 終了戦略の場合、許可される値は'end_round'および'end_flat'です。

    最初の引数が'point_circle', 'join_round', 'join_miter'または'end_round'の場合、points_per_circle 引数は正の数値で指定する必要があります。 points_per_circle の最大値は、max_points_in_geometry システム変数の値です。

    例については、ST_Buffer() の説明を参照してください。

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

    • 無効な引数があると、ER_WRONG_ARGUMENTS エラーが発生します。

    • 最初の引数が'point_square'または'end_flat'の場合、points_per_circle 引数を指定しないでください。指定すると、ER_WRONG_ARGUMENTS エラーが発生します。

  • ST_ConvexHull(g)

    ジオメトリ値 g の凸型ハルを表すジオメトリを戻します。

    この関数は、まず頂点ポイントが同一直線かどうかをチェックして、ジオメトリ凸型を計算します。 その場合は線形ハルを返し、それ以外の場合はポリゴンハルを返します。 この関数は、コレクションのすべてのコンポーネントのすべての頂点ポイントを抽出し、そこから MultiPoint 値を作成して凸型を計算することで、ジオメトリコレクションを処理します。

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

    • 引数が空のジオメトリコレクションであるという追加条件では、戻り値は NULL です。

    mysql> SET @g = 'MULTIPOINT(5 0,25 0,15 10,15 25)';
    mysql> SELECT ST_AsText(ST_ConvexHull(ST_GeomFromText(@g)));
    +-----------------------------------------------+
    | ST_AsText(ST_ConvexHull(ST_GeomFromText(@g))) |
    +-----------------------------------------------+
    | POLYGON((5 0,25 0,15 25,5 0))                 |
    +-----------------------------------------------+
  • ST_Difference(g1, g2)

    ジオメトリ値 g1g2 の点集合の差集合を表すジオメトリを返します。

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

    mysql> SET @g1 = Point(1,1), @g2 = Point(2,2);
    mysql> SELECT ST_AsText(ST_Difference(@g1, @g2));
    +------------------------------------+
    | ST_AsText(ST_Difference(@g1, @g2)) |
    +------------------------------------+
    | POINT(1 1)                         |
    +------------------------------------+
  • ST_Intersection(g1, g2)

    ジオメトリ値 g1g2 の点集合の共通集合を表すジオメトリを返します。

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

    mysql> SET @g1 = ST_GeomFromText('LineString(1 1, 3 3)');
    mysql> SET @g2 = ST_GeomFromText('LineString(1 3, 3 1)');
    mysql> SELECT ST_AsText(ST_Intersection(@g1, @g2));
    +--------------------------------------+
    | ST_AsText(ST_Intersection(@g1, @g2)) |
    +--------------------------------------+
    | POINT(2 2)                           |
    +--------------------------------------+
  • ST_LineInterpolatePoint(ls, fractional_distance)

    この関数は、範囲[0.0, 1.0]内の LineString ジオメトリと小数距離を取得し、LineString に沿って、始点から終点までの指定された距離分の Point を戻します。 これを使用すると、ジオメトリ引数で記述された道路の途中に Point があるかどうかなどの質問に回答できます。

    この関数は、すべての空間参照システム (デカルトと地理の両方) の LineString ジオメトリに対して実装されます。

    fractional_distance 引数が 1.0 の場合、近似値の計算で数値が不正確になるため、結果は LineString 引数の正確な最後のポイントではなく、その近くのポイントになる可能性があります。

    関連する関数 ST_LineInterpolatePoints() は同様の引数を取りますが、開始点からそのエンドポイントまでの距離の各部分の LineString に沿った Point 値で構成される MultiPoint を返します。 両方の関数の例については、ST_LineInterpolatePoints() の説明を参照してください。

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

    • ジオメトリ引数が LineString でない場合は、ER_UNEXPECTED_GEOMETRY_TYPE エラーが発生します。

    • 分数距離引数が[0.0, 1.0]の範囲外の場合、ER_DATA_OUT_OF_RANGE エラーが発生します。

    ST_LineInterpolatePoint() は、OpenGIS の MySQL 拡張機能です。 この関数は、MySQL 8.0.24 で追加されました。

  • ST_LineInterpolatePoints(ls, fractional_distance)

    この関数は、範囲 (0.0、1.0) 内の LineString ジオメトリおよび小数距離を取得し、LineString の開始点と、その開始点からエンドポイントまでの距離の各部分の LineString に沿った Point 値で構成される MultiPoint を戻します。 これを使用すると、ジオメトリ引数で記述された道路に沿って 10% ずつどの Point 値があるかなどの質問に答えることができます。

    この関数は、すべての空間参照システム (デカルトと地理の両方) の LineString ジオメトリに対して実装されます。

    fractional_distance 引数がゼロの余りで 1.0 を除算する場合、結果には LineString 引数の最後のポイントが含まれず、近似値の計算における数値の不正確のためにその近くのポイントが含まれる可能性があります。

    関連する関数である ST_LineInterpolatePoint() は、同様の引数を取りますが、開始点からエンドポイントまでの指定された距離で、LineString に沿って Point を返します。

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

    • ジオメトリ引数が LineString でない場合は、ER_UNEXPECTED_GEOMETRY_TYPE エラーが発生します。

    • 分数距離引数が[0.0, 1.0]の範囲外の場合、ER_DATA_OUT_OF_RANGE エラーが発生します。

    mysql> SET @ls1 = ST_GeomFromText('LINESTRING(0 0,0 5,5 5)');
    mysql> SELECT ST_AsText(ST_LineInterpolatePoint(@ls1, .5));
    +----------------------------------------------+
    | ST_AsText(ST_LineInterpolatePoint(@ls1, .5)) |
    +----------------------------------------------+
    | POINT(0 5)                                   |
    +----------------------------------------------+
    mysql> SELECT ST_AsText(ST_LineInterpolatePoint(@ls1, .75));
    +-----------------------------------------------+
    | ST_AsText(ST_LineInterpolatePoint(@ls1, .75)) |
    +-----------------------------------------------+
    | POINT(2.5 5)                                  |
    +-----------------------------------------------+
    mysql> SELECT ST_AsText(ST_LineInterpolatePoint(@ls1, 1));
    +---------------------------------------------+
    | ST_AsText(ST_LineInterpolatePoint(@ls1, 1)) |
    +---------------------------------------------+
    | POINT(5 5)                                  |
    +---------------------------------------------+
    mysql> SELECT ST_AsText(ST_LineInterpolatePoints(@ls1, .25));
    +------------------------------------------------+
    | ST_AsText(ST_LineInterpolatePoints(@ls1, .25)) |
    +------------------------------------------------+
    | MULTIPOINT((0 2.5),(0 5),(2.5 5),(5 5))        |
    +------------------------------------------------+

    ST_LineInterpolatePoints() は、OpenGIS の MySQL 拡張機能です。 この関数は、MySQL 8.0.24 で追加されました。

  • ST_PointAtDistance(ls, distance)

    この関数は、LineString ジオメトリと、LineString の空間参照システム (SRS) の単位で測定された[0.0, ST_Length(ls)]の範囲内の距離を取得し、開始点からその距離にある LineString に沿って Point を戻します。 geometry 引数で記述された道路の始点から 400 メートルの Point 値などの質問に答えるために使用できます。

    この関数は、すべての空間参照システム (デカルトと地理の両方) の LineString ジオメトリに対して実装されます。

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

    • ジオメトリ引数が LineString でない場合は、ER_UNEXPECTED_GEOMETRY_TYPE エラーが発生します。

    • 分数距離引数が[0.0, ST_Length(ls)]の範囲外の場合、ER_DATA_OUT_OF_RANGE エラーが発生します。

    ST_PointAtDistance() は、OpenGIS の MySQL 拡張機能です。 この関数は、MySQL 8.0.24 で追加されました。

  • ST_SymDifference(g1, g2)

    ジオメトリ値 g1g2 の点集合の対称差を表すジオメトリを返します。これは、次のように定義されます。

    g1 symdifference g2 := (g1 union g2) difference (g1 intersection g2)

    または、関数呼び出しの表記では次のようになります。

    ST_SymDifference(g1, g2) = ST_Difference(ST_Union(g1, g2), ST_Intersection(g1, g2))

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

    mysql> SET @g1 = Point(1,1), @g2 = Point(2,2);
    mysql> SELECT ST_AsText(ST_SymDifference(@g1, @g2));
    +---------------------------------------+
    | ST_AsText(ST_SymDifference(@g1, @g2)) |
    +---------------------------------------+
    | MULTIPOINT((1 1),(2 2))               |
    +---------------------------------------+
  • ST_Transform(g, target_srid)

    ジオメトリをある空間参照システム (SRS) から別の空間参照システムに変換します。 戻り値は、すべての座標がターゲット SRID (target_srid) に変換された入力ジオメトリと同じタイプのジオメトリです。 ジオメトリ引数の SRID がターゲット SRID 値と同じでないかぎり、変換のサポートは地理的 SRS に制限されます。この場合、戻り値は有効な SRS の入力ジオメトリです。

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

    • 地理 SRS の SRID 値を持つジオメトリ引数では、エラーは発生しません。

    • ジオメトリまたはターゲット SRID 引数に、未定義の空間参照システム (SRS) を参照する SRID 値がある場合、ER_SRS_NOT_FOUND エラーが発生します。

    • ジオメトリが ST_Transform() で変換できない SRS 内にある場合は、ER_TRANSFORM_SOURCE_SRS_NOT_SUPPORTED エラーが発生します。

    • ターゲット SRID が ST_Transform() が変換できない SRS 内にある場合は、ER_TRANSFORM_TARGET_SRS_NOT_SUPPORTED エラーが発生します。

    • ジオメトリが WGS 84 以外の SRS にあり、TOWGS84 句がない場合は、ER_TRANSFORM_SOURCE_SRS_MISSING_TOWGS84 エラーが発生します。

    • ターゲット SRID が WGS 84 以外の SRS にあり、TOWGS84 句がない場合は、ER_TRANSFORM_TARGET_SRS_MISSING_TOWGS84 エラーが発生します。

    ST_SRID(g, target_srid)ST_Transform(g, target_srid) は、次の点で異なります:

    • ST_SRID() は、座標を変換せずにジオメトリ SRID 値を変更します。

    • ST_Transform() は、SRID 値の変更に加えてジオメトリ座標を変換します。

    mysql> SET @p = ST_GeomFromText('POINT(52.381389 13.064444)', 4326);
    mysql> SELECT ST_AsText(@p);
    +----------------------------+
    | ST_AsText(@p)              |
    +----------------------------+
    | POINT(52.381389 13.064444) |
    +----------------------------+
    mysql> SET @p = ST_Transform(@p, 4230);
    mysql> SELECT ST_AsText(@p);
    +---------------------------------------------+
    | ST_AsText(@p)                               |
    +---------------------------------------------+
    | POINT(52.38208611407426 13.065520672345304) |
    +---------------------------------------------+
  • ST_Union(g1, g2)

    ジオメトリ値 g1g2 の点集合の和集合を表すジオメトリを返します。

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

    mysql> SET @g1 = ST_GeomFromText('LineString(1 1, 3 3)');
    mysql> SET @g2 = ST_GeomFromText('LineString(1 3, 3 1)');
    mysql> SELECT ST_AsText(ST_Union(@g1, @g2));
    +--------------------------------------+
    | ST_AsText(ST_Union(@g1, @g2))        |
    +--------------------------------------+
    | MULTILINESTRING((1 1,3 3),(1 3,3 1)) |
    +--------------------------------------+

さらに、セクション12.17.7「ジオメトリプロパティー関数」では、既存のジオメトリから新しいジオメトリを構築するいくつかの関数について説明しています。 これらの関数の説明については、そのセクションを参照してください。

  • ST_Envelope(g)

  • ST_StartPoint(ls)

  • ST_EndPoint(ls)

  • ST_PointN(ls, N)

  • ST_ExteriorRing(poly)

  • ST_InteriorRingN(poly, N)

  • ST_GeometryN(gc, N)


関連キーワード:  関数, ジオメトリ, 空間, AsText, エラー, 発生, Buffer, 処理, 距離, Point