12.17.7.3 LineString および MultiLineString のプロパティー関数

LineString は、Point 値で構成されます。 LineString の特定の点を抽出したり、そこに含まれている点の数をカウントしたり、その長さを取得したりできます。

このセクションの一部の関数は、MultiLineString 値に対しても機能します。

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

引数が NULL の場合、またはジオメトリ引数が空のジオメトリの場合、戻り値は NULL です。
ジオメトリ引数が構文的に整形式のジオメトリでない場合は、ER_GIS_INVALID_DATA エラーが発生します。
未定義の空間参照システム (SRS) でジオメトリ引数が構文的に整形式のジオメトリである場合、ER_SRS_NOT_FOUND エラーが発生します。
それ以外の場合、戻り値は NULL 以外です。

linestring プロパティーを取得するには、次の関数を使用できます:

ST_EndPoint(ls)

LineString 値 ls の終点である Point を返します。

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

mysql> SET @ls = 'LineString(1 1,2 2,3 3)';
mysql> SELECT ST_AsText(ST_EndPoint(ST_GeomFromText(@ls)));
+----------------------------------------------+
| ST_AsText(ST_EndPoint(ST_GeomFromText(@ls))) |
+----------------------------------------------+
| POINT(3 3)                                   |
+----------------------------------------------+

ST_IsClosed(ls)

LineString 値が ls の場合、ls がクローズされると、ST_IsClosed() は 1 を返します (つまり、ST_StartPoint() と ST_EndPoint() の値が同じです)。

MultiLineString 値が ls の場合、ls がクローズされると、ST_IsClosed() は 1 を返します (つまり、ST_StartPoint() と ST_EndPoint() の値は ls の LineString ごとに同じです)。

ST_IsClosed() は、ls がクローズされていない場合は 0 を返し、ls が NULL の場合は NULL を返します。

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

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

mysql> SET @ls1 = 'LineString(1 1,2 2,3 3,2 2)';
mysql> SET @ls2 = 'LineString(1 1,2 2,3 3,1 1)';

mysql> SELECT ST_IsClosed(ST_GeomFromText(@ls1));
+------------------------------------+
| ST_IsClosed(ST_GeomFromText(@ls1)) |
+------------------------------------+
|                                  0 |
+------------------------------------+

mysql> SELECT ST_IsClosed(ST_GeomFromText(@ls2));
+------------------------------------+
| ST_IsClosed(ST_GeomFromText(@ls2)) |
+------------------------------------+
|                                  1 |
+------------------------------------+

mysql> SET @ls3 = 'MultiLineString((1 1,2 2,3 3),(4 4,5 5))';

mysql> SELECT ST_IsClosed(ST_GeomFromText(@ls3));
+------------------------------------+
| ST_IsClosed(ST_GeomFromText(@ls3)) |
+------------------------------------+
|                                  0 |
+------------------------------------+

ST_Length(ls [, unit])
関連付けられた空間参照システムにおける LineString または MultiLineString 値 ls の長さを示す倍精度数値を戻します。 MultiLineString 値の長さは、その要素の長さの合計と等しくなります。
ST_Length() では、次のように結果が計算されます:
- ジオメトリがデカルト SRS の有効な LineString である場合、戻り値はジオメトリのデカルト長です。
- ジオメトリがデカルト SRS 内の有効な MultiLineString である場合、戻り値はその要素のデカルト長の合計です。
- ジオメトリが地理 SRS 内の有効な LineString である場合、戻り値はその SRS 内のジオメトリの測地長 (メートル) です。
- ジオメトリが地理 SRS 内の有効な MultiLineString である場合、戻り値は SRS 内の要素の測地長の合計 (メートル) です。
ST_Length() は、このセクションの概要で説明されているように、引数を処理しますが、次の例外があります:
- ジオメトリが LineString または MultiLineString でない場合、戻り値は NULL です。
- ジオメトリがジオメトリ学的に無効な場合は、結果の長さが未定義 (任意の数値) であるか、エラーが発生します。
- 長さの計算結果が +inf の場合、ER_DATA_OUT_OF_RANGE エラーが発生します。
- ジオメトリに経度または緯度が範囲外の地理 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.16 以降、ST_Length() では、戻される長さの値の線形単位を指定するオプションの unit 引数が許可されます。次のルールが適用されます:
- ユニットが指定されているが、MySQL でサポートされていない場合は、ER_UNIT_NOT_FOUND エラーが発生します。
- サポートされている線形単位が指定され、SRID が 0 の場合、ER_GEOMETRY_IN_UNKNOWN_LENGTH_UNIT エラーが発生します。
- サポートされている線形単位が指定され、SRID が 0 でない場合、結果はその単位になります。
- 単位が指定されていない場合、結果はデカルトか地理的かにかかわらず、ジオメトリの SRS の単位になります。現在、すべての MySQL SRS はメーターで表されます。
ユニットは、INFORMATION_SCHEMA ST_UNITS_OF_MEASURE テーブルで見つかった場合にサポートされます。セクション26.37「INFORMATION_SCHEMA ST_UNITS_OF_MEASURE テーブル」を参照してください。
```
mysql> SET @ls = ST_GeomFromText('LineString(1 1,2 2,3 3)');
mysql> SELECT ST_Length(@ls);
+--------------------+
| ST_Length(@ls)     |
+--------------------+
| 2.8284271247461903 |
+--------------------+

mysql> SET @mls = ST_GeomFromText('MultiLineString((1 1,2 2,3 3),(4 4,5 5))');
mysql> SELECT ST_Length(@mls);
+-------------------+
| ST_Length(@mls)   |
+-------------------+
| 4.242640687119286 |
+-------------------+

mysql> SET @ls = ST_GeomFromText('LineString(1 1,2 2,3 3)', 4326);
mysql> SELECT ST_Length(@ls);
+-------------------+
| ST_Length(@ls)    |
+-------------------+
| 313701.9623204328 |
+-------------------+
mysql> SELECT ST_Length(@ls, 'metre');
+-------------------------+
| ST_Length(@ls, 'metre') |
+-------------------------+
|       313701.9623204328 |
+-------------------------+
mysql> SELECT ST_Length(@ls, 'foot');
+------------------------+
| ST_Length(@ls, 'foot') |
+------------------------+
|     1029205.9131247795 |
+------------------------+
```

ST_NumPoints(ls)

LineString 値 ls 内の Point オブジェクトの数を返します。

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

mysql> SET @ls = 'LineString(1 1,2 2,3 3)';
mysql> SELECT ST_NumPoints(ST_GeomFromText(@ls));
+------------------------------------+
| ST_NumPoints(ST_GeomFromText(@ls)) |
+------------------------------------+
|                                  3 |
+------------------------------------+

ST_PointN(ls, N)

Linestring 値 ls 内の N 番目の Point を返します。点の番号は 1 から始まります。

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

mysql> SET @ls = 'LineString(1 1,2 2,3 3)';
mysql> SELECT ST_AsText(ST_PointN(ST_GeomFromText(@ls),2));
+----------------------------------------------+
| ST_AsText(ST_PointN(ST_GeomFromText(@ls),2)) |
+----------------------------------------------+
| POINT(2 2)                                   |
+----------------------------------------------+

ST_StartPoint(ls)

LineString 値 ls の始点である Point を返します。

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

mysql> SET @ls = 'LineString(1 1,2 2,3 3)';
mysql> SELECT ST_AsText(ST_StartPoint(ST_GeomFromText(@ls)));
+------------------------------------------------+
| ST_AsText(ST_StartPoint(ST_GeomFromText(@ls))) |
+------------------------------------------------+
| POINT(1 1)                                     |
+------------------------------------------------+