地理関数

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

BigQuery 向けの GoogleSQL は、地理関数をサポートしています。地理関数は GoogleSQL の GEOGRAPHY 値を処理または生成します。ほとんどの地理関数のシグネチャは、ST_ で始まります。BigQuery 向けの GoogleSQL は、以下の関数をサポートしています。これらの関数を使用して、地理データの分析、地理フィーチャー間の空間関係の特定、GEOGRAPHY の作成または操作を実施できます。

GoogleSQL の地理関数はすべて、入力引数のいずれかに NULL があると、NULL を返します。

カテゴリ

地理関数は、それぞれの動作に基づいて次のカテゴリに分類されます。

カテゴリ 関数 説明
コンストラクタ ST_GEOGPOINT
ST_MAKELINE
ST_MAKEPOLYGON
ST_MAKEPOLYGONORIENTED 		座標または既存の地理表現から新しい地理表現を作成する関数。
パーサー ST_GEOGFROM
ST_GEOGFROMGEOJSON
ST_GEOGFROMTEXT
ST_GEOGFROMWKB
ST_GEOGPOINTFROMGEOHASH
 WKT、GeoJSON などの外部形式から地理表現を作成する関数。
フォーマッタ ST_ASBINARY
ST_ASGEOJSON
ST_ASTEXT
ST_GEOHASH 		地理表現を WKT などの外部形式にエクスポートする関数。
変換 ST_BOUNDARY
ST_BUFFER
ST_BUFFERWITHTOLERANCE
ST_CENTROID
ST_CENTROID_AGG（集計）
ST_CLOSESTPOINT
ST_CONVEXHULL
ST_DIFFERENCE
ST_EXTERIORRING
ST_INTERIORRINGS
ST_INTERSECTION
ST_SIMPLIFY
ST_SNAPTOGRID
ST_UNION
ST_UNION_AGG（集計）
 入力に基づいて新しい地理表現を生成する関数。
アクセサー ST_DIMENSION
ST_DUMP
ST_ENDPOINT
ST_GEOMETRYTYPE
ST_ISCLOSED
ST_ISCOLLECTION
ST_ISEMPTY
ST_ISRING
ST_NPOINTS
ST_NUMGEOMETRIES
ST_NUMPOINTS
ST_POINTN
ST_STARTPOINT
ST_X
ST_Y
 副次的影響を生じることなく、地理上のプロパティにアクセスできるようにする関数。
述語 ST_CONTAINS
ST_COVEREDBY
ST_COVERS
ST_DISJOINT
ST_DWITHIN
ST_EQUALS
ST_INTERSECTS
ST_INTERSECTSBOX
ST_TOUCHES
ST_WITHIN
 2 つの地理表現の空間関係、または地理上のなんらかのプロパティに対して TRUE または FALSE を返す関数。この関数は、一般にフィルタ句で使用されます。
測定 ST_ANGLE
ST_AREA
ST_AZIMUTH
ST_BOUNDINGBOX
ST_DISTANCE
ST_EXTENT（集計）
ST_LENGTH
ST_MAXDISTANCE
ST_PERIMETER
 1 つ以上の地理的測定値を計算する関数。
クラスタリング ST_CLUSTERDBSCAN 地理的なクラスタ化を行う関数。
S2 関数 S2_CELLIDFROMPOINT
S2_COVERINGCELLIDS
 GEOGRAPHY をカバーする S2 セルを操作する関数。

S2_CELLIDFROMPOINT

S2_CELLIDFROMPOINT(point_geography[, level => cell_level])

説明

ポイント GEOGRAPHY をカバーする S2 セル ID を返します。

  • オプションの INT64 パラメータの level に、返されるセルの S2 セルレベルを指定します。この引数の指定は省略できます。

これは、S2 Geometry Library を利用するシステムと相互運用するための高度な機能です。

制約

  • セル ID を符号なし 64 ビット整数表現と同等の符号付き INT64 ビットとして返します。
  • 負のセル ID を返す場合があります。
  • 有効な S2 セルレベルは 0～30 です。
  • 明示的に指定しない場合、level はデフォルトで 30 に設定されます。
  • この関数は、単一点の GEOGRAPHY のみをサポートしています。入力がマルチポイント、LineString、ポリゴン、または空の GEOGRAPHY の場合は、SAFE 接頭辞を使用します。
  • 複雑な GEOGRAPHY のカバレッジを計算するには、S2_COVERINGCELLIDS を使用します。

戻り値の型

INT64

例

WITH data AS (
  SELECT 1 AS id, ST_GEOGPOINT(-122, 47) AS geo
  UNION ALL
  -- empty geography is not supported
  SELECT 2 AS id, ST_GEOGFROMTEXT('POINT EMPTY') AS geo
  UNION ALL
  -- only points are supported
  SELECT 3 AS id, ST_GEOGFROMTEXT('LINESTRING(1 2, 3 4)') AS geo
)
SELECT id,
       SAFE.S2_CELLIDFROMPOINT(geo) cell30,
       SAFE.S2_CELLIDFROMPOINT(geo, level => 10) cell10
FROM data;

+----+---------------------+---------------------+
| id | cell30              | cell10              |
+----+---------------------+---------------------+
| 1  | 6093613931972369317 | 6093613287902019584 |
| 2  | NULL                | NULL                |
| 3  | NULL                | NULL                |
+----+---------------------+---------------------+

S2_COVERINGCELLIDS

S2_COVERINGCELLIDS(
    geography
    [, min_level => cell_level]
    [, max_level => cell_level]
    [, max_cells => max_cells]
    [, buffer => buffer])

説明

入力 GEOGRAPHY をカバーする S2 セル ID の配列を返します。この関数は、最大で max_cells 個のセルを返します。オプションの引数 min_level と max_level には、返される S2 セルの最小レベルと最大レベルを指定します。配列のサイズはオプションの max_cells 引数によって制限されます。オプションの buffer 引数には、バッファリング係数をメートル単位で指定します。対象リージョンで、この分が入力地理範囲から拡張されます。

これは、S2 Geometry Library を利用するシステムと相互運用するための高度な機能です。

制約

  • セル ID を符号なし 64 ビット整数表現と同等の符号付き INT64 ビットとして返します。
  • 負のセル ID を返す場合があります。
  • 有効な S2 セルレベルは 0～30 です。
  • 明示的に指定しない場合、max_cells はデフォルトで 8 に設定されます。
  • buffer は、負以外にする必要があります。明示的に指定しない場合、デフォルトで 0.0 メートルに設定されます。

戻り値の型

ARRAY<INT64>

例

WITH data AS (
  SELECT 1 AS id, ST_GEOGPOINT(-122, 47) AS geo
  UNION ALL
  SELECT 2 AS id, ST_GEOGFROMTEXT('POINT EMPTY') AS geo
  UNION ALL
  SELECT 3 AS id, ST_GEOGFROMTEXT('LINESTRING(-122.12 47.67, -122.19 47.69)') AS geo
)
SELECT id, S2_COVERINGCELLIDS(geo, min_level => 12) cells
FROM data;

+----+--------------------------------------------------------------------------------------+
| id | cells                                                                                |
+----+--------------------------------------------------------------------------------------+
| 1  | [6093613931972369317]                                                                |
| 2  | []                                                                                   |
| 3  | [6093384954555662336, 6093390709811838976, 6093390735581642752, 6093390740145045504, |
|    |  6093390791416217600, 6093390812891054080, 6093390817187069952, 6093496378892222464] |
+----+--------------------------------------------------------------------------------------+

ST_ANGLE

ST_ANGLE(point_geography_1, point_geography_2, point_geography_3)

説明

3 つのポイント GEOGRAPHY 値を取ります。これは、2 つの交差するラインを表します。これらの線の間の角度を返します。ポイント 2 とポイント 1 は最初のラインを表し、ポイント 2 とポイント 3 は 2 番目のラインを表します。これらのライン間の角度はラジアンで、[0, 2pi) の範囲になります。角度は最初のラインから 2 番目のラインまで時計回りで測定されます。

ST_ANGLE には、次のエッジケースがあります。

  • ポイント 2 とポイント 3 が同じ場合は NULL を返します。
  • ポイント 2 とポイント 1 が同じ場合は NULL を返します。
  • ポイント 2 とポイント 3 が正反対の場合は NULL を返します。
  • ポイント 2 とポイント 1 が正反対の場合は NULL を返します。
  • 入力された geography のいずれかが単一点ではないか、空の geography である場合は、エラーがスローされます。

戻り値の型

FLOAT64

例

WITH geos AS (
  SELECT 1 id, ST_GEOGPOINT(1, 0) geo1, ST_GEOGPOINT(0, 0) geo2, ST_GEOGPOINT(0, 1) geo3 UNION ALL
  SELECT 2 id, ST_GEOGPOINT(0, 0), ST_GEOGPOINT(1, 0), ST_GEOGPOINT(0, 1) UNION ALL
  SELECT 3 id, ST_GEOGPOINT(1, 0), ST_GEOGPOINT(0, 0), ST_GEOGPOINT(1, 0) UNION ALL
  SELECT 4 id, ST_GEOGPOINT(1, 0) geo1, ST_GEOGPOINT(0, 0) geo2, ST_GEOGPOINT(0, 0) geo3 UNION ALL
  SELECT 5 id, ST_GEOGPOINT(0, 0), ST_GEOGPOINT(-30, 0), ST_GEOGPOINT(150, 0) UNION ALL
  SELECT 6 id, ST_GEOGPOINT(0, 0), NULL, NULL UNION ALL
  SELECT 7 id, NULL, ST_GEOGPOINT(0, 0), NULL UNION ALL
  SELECT 8 id, NULL, NULL, ST_GEOGPOINT(0, 0))
SELECT ST_ANGLE(geo1,geo2,geo3) AS angle FROM geos ORDER BY id;

+---------------------+
| angle               |
+---------------------+
| 4.71238898038469    |
| 0.78547432161873854 |
| 0                   |
| NULL                |
| NULL                |
| NULL                |
| NULL                |
| NULL                |
+---------------------+

ST_AREA

ST_AREA(geography_expression[, use_spheroid])

説明

入力 GEOGRAPHY に含まれるポリゴンでカバーされている面積を平方メートル単位で返します。

geography_expression がポイントまたはラインの場合は、ゼロを返します。geography_expression が集合の場合、その集合に含まれるポリゴンの面積を返します。集合にポリゴンが含まれていない場合はゼロを返します。

任意の use_spheroid パラメータは、この関数で距離が測定される方法を決定します。use_spheroid が FALSE の場合、完全な球体の表面上の距離が測定されます。

use_spheroid パラメータで現在サポートされている値は FALSE だけです。use_spheroid のデフォルト値は FALSE です。

戻り値の型

FLOAT64

ST_ASBINARY

ST_ASBINARY(geography_expression)

説明

入力された GEOGRAPHY の WKB 表現を返します。

WKB から GEOGRAPHY を作成する場合には、ST_GEOGFROMWKB をご覧ください。

戻り値の型

BYTES

ST_ASGEOJSON

ST_ASGEOJSON(geography_expression)

説明

入力された GEOGRAPHY を、RFC 7946 準拠の GeoJSON 表現で返します。

GoogleSQL の GEOGRAPHY には球状の測地線エッジがありますが、GeoJSON の Geometry オブジェクトには明確な平面エッジがあります。この 2 種類のエッジ間の変換を行う目的で、GoogleSQL では必要に応じてラインにポイントを追加し、結果として得られるエッジのシーケンスが元のエッジの 10 m 以内に収まるようにします。

GeoJSON から GEOGRAPHY を作成する場合には、ST_GEOGFROMGEOJSON をご覧ください。

戻り値の型

STRING

ST_ASTEXT

ST_ASTEXT(geography_expression)

説明

入力された GEOGRAPHY の WKT 表現を返します。

WKT から GEOGRAPHY を作成する場合には、ST_GEOGFROMTEXT をご覧ください。

戻り値の型

STRING

ST_AZIMUTH

ST_AZIMUTH(point_geography_1, point_geography_2)

説明

2 つのポイントの GEOGRAPHY 値を取り、ポイント 1 と 2 で形成されたライン セグメントの方位角を返します。方位角は、真北を向くポイント 1 と、ポイント 1 からポイント 2 までのライン セグメントとの間を測定したラジアンです。

正の角度は、球面上で時計回りに測定されます。たとえば、ライン セグメントの方位角は、次のようになります。

  • 北を指す場合は 0 です。
  • 東を指す場合は PI/2 です。
  • 南を指す場合は PI です。
  • 西を指す場合は 3PI/2 です。

ST_AZIMUTH には、次のエッジケースがあります。

  • 2 つの入力ポイントが同じである場合は、NULL を返します。
  • 2 つの入力ポイントが正反対の場合は、NULL を返します。
  • 入力された geography のいずれかが単一点ではないか、空の geography である場合は、エラーがスローされます。

戻り値の型

FLOAT64

例

WITH geos AS (
  SELECT 1 id, ST_GEOGPOINT(1, 0) AS geo1, ST_GEOGPOINT(0, 0) AS geo2 UNION ALL
  SELECT 2, ST_GEOGPOINT(0, 0), ST_GEOGPOINT(1, 0) UNION ALL
  SELECT 3, ST_GEOGPOINT(0, 0), ST_GEOGPOINT(0, 1) UNION ALL
  -- identical
  SELECT 4, ST_GEOGPOINT(0, 0), ST_GEOGPOINT(0, 0) UNION ALL
  -- antipode
  SELECT 5, ST_GEOGPOINT(-30, 0), ST_GEOGPOINT(150, 0) UNION ALL
  -- nulls
  SELECT 6, ST_GEOGPOINT(0, 0), NULL UNION ALL
  SELECT 7, NULL, ST_GEOGPOINT(0, 0))
SELECT ST_AZIMUTH(geo1, geo2) AS azimuth FROM geos ORDER BY id;

+--------------------+
| azimuth            |
+--------------------+
| 4.71238898038469   |
| 1.5707963267948966 |
| 0                  |
| NULL               |
| NULL               |
| NULL               |
| NULL               |
+--------------------+

ST_BOUNDARY

ST_BOUNDARY(geography_expression)

説明

指定された入力 GEOGRAPHY 内の各コンポーネントの境界のユニオンを格納する、単一の GEOGRAPHY を返します。

GEOGRAPHY を構成する各コンポーネントの境界は、次のように定義されます。

  • ポイントの境界は空です。
  • LineString の境界は、その LineString の端点で構成されます。
  • ポリゴンの境界は、ポリゴンシェルと各ポリゴンホールを形成する LineString で構成されます。

戻り値の型

GEOGRAPHY

ST_BOUNDINGBOX

ST_BOUNDINGBOX(geography_expression)

説明

指定された geography の境界ボックスを表す STRUCT を返します。境界ボックスは geography を囲む最小の矩形です。矩形のエッジは経度と緯度の実線に沿っています。

注意点:

  • 入力が NULL または空の geography である場合、NULL を返します。
  • 境界ボックスは、より小さい矩形を許容する場合、経度 180 度線と交差する可能性があります。この場合、境界ボックスは経度の境界の一つが [-180, 180] の範囲外であるため、xmin は最東端の値 xmax よりも小さくなります。

戻り値の型

STRUCT<xmin FLOAT64, ymin FLOAT64, xmax FLOAT64, ymax FLOAT64>。

境界ボックスのパーツ:

  • xmin: 矩形の境界を形成する最西端の経度の実線（X 座標）。
  • xmax: 矩形の境界を形成する最東端の経度の実線（X 座標）。
  • ymin: 矩形の境界を形成する最小緯度の実線（Y 座標）。
  • ymax: 矩形の境界を形成する最大緯度の実線（Y 座標）。

例

WITH data AS (
  SELECT 1 id, ST_GEOGFROMTEXT('POLYGON((-125 48, -124 46, -117 46, -117 49, -125 48))') g
  UNION ALL
  SELECT 2 id, ST_GEOGFROMTEXT('POLYGON((172 53, -130 55, -141 70, 172 53))') g
  UNION ALL
  SELECT 3 id, ST_GEOGFROMTEXT('POINT EMPTY') g
  UNION ALL
  SELECT 4 id, ST_GEOGFROMTEXT('POLYGON((172 53, -141 70, -130 55, 172 53))', oriented => TRUE)
)
SELECT id, ST_BOUNDINGBOX(g) AS box
FROM data

+----+------------------------------------------+
| id | box                                      |
+----+------------------------------------------+
| 1  | {xmin:-125, ymin:46, xmax:-117, ymax:49} |
| 2  | {xmin:172, ymin:53, xmax:230, ymax:70}   |
| 3  | NULL                                     |
| 4  | {xmin:-180, ymin:-90, xmax:180, ymax:90} |
+----+------------------------------------------+

ST_BOUNDINGBOX の集計バージョンについては、ST_EXTENT をご覧ください。

ST_BUFFER

ST_BUFFER(
    geography,
    buffer_radius
    [, num_seg_quarter_circle => num_segments]
    [, use_spheroid => boolean_expression]
    [, endcap => endcap_style]
    [, side => line_side])

説明

入力 GEOGRAPHY を囲むバッファを表す GEOGRAPHY を返します。この関数は ST_BUFFERWITHTOLERANCE と似ていますが、作成される geography が理想的なバッファ半径からどの程度逸脱できるかを決めるための許容範囲を示すのではなく、セグメントの数を示します。

  • geography: バッファ半径で囲む入力 GEOGRAPHY。
  • buffer_radius: 入力地理の周囲にあるバッファの半径を表す DOUBLE。半径はメートル単位です。ポリゴンは、負の buffer_radius でバッファリングされるときに縮小されます。ある時点で縮小されるポリゴンのシェルとホールは破棄されます。
  • num_seg_quarter_circle: （省略可）DOUBLE は、四半円の近似に使用されるセグメントの数を指定します。デフォルト値は 8.0 です。この引数の指定は省略できます。
  • endcap: （省略可）STRING には、ROUND と FLAT のいずれかのエンドキャップ スタイルを指定できます。デフォルト値は ROUND です。このオプションは、バッファリングされた LineString のエンドキャップにのみ影響します。
  • side: （省略可）STRING には、BOTH、LEFT、RIGHT の 3 つの取り得る線のいずれかを指定できます。デフォルトは BOTH です。このオプションは、LineString がどのようにバッファされるかということにのみ影響します。
  • use_spheroid: （省略可）BOOL は、この関数で距離を測定する方法を決定します。use_spheroid が FALSE の場合、完全な球体の表面上の距離が測定されます。use_spheroid パラメータで現在サポートされている値は FALSE だけです。use_spheroid のデフォルト値は FALSE です。

戻り値の型

Polygon GEOGRAPHY

例

次の例では、あるポイントにおける ST_BUFFER の結果を示します。バッファリングされたポイントは近似的な円です。num_seg_quarter_circle = 2 の場合、2 本の線分が四半円の中に存在し、バッファリングされた円は 8 辺になり、ST_NUMPOINTS によって 9 個の頂点が返されます。num_seg_quarter_circle = 8 の場合、8 本の線分が四半円の中に存在し、バッファリングされた円は 32 辺になり、ST_NUMPOINTS によって 33 個の頂点が返されます。

SELECT
  -- num_seg_quarter_circle=2
  ST_NUMPOINTS(ST_BUFFER(ST_GEOGFROMTEXT('POINT(1 2)'), 50, 2)) AS eight_sides,
  -- num_seg_quarter_circle=8, since 8 is the default
  ST_NUMPOINTS(ST_BUFFER(ST_GEOGFROMTEXT('POINT(100 2)'), 50)) AS thirty_two_sides;

+-------------+------------------+
| eight_sides | thirty_two_sides |
+-------------+------------------+
| 9           | 33               |
+-------------+------------------+

ST_BUFFERWITHTOLERANCE

ST_BUFFERWITHTOLERANCE(
    geography,
    buffer_radius,
    tolerance_meters => tolernace
    [, use_spheroid => boolean_expression]
    [, endcap => endcap_style]
    [, side => line_side])

入力 GEOGRAPHY を囲むバッファを表す GEOGRAPHY を返します。この関数は ST_BUFFER に似ていますが、作成される geography が理想的なバッファ半径からどの程度逸脱できるかを決めるためのセグメント数を示すのではなく、許容範囲を示します。

  • geography: バッファ半径で囲む入力 GEOGRAPHY。
  • buffer_radius: 入力地理の周囲にあるバッファの半径を表す DOUBLE。半径はメートル単位です。ポリゴンは、負の buffer_radius でバッファリングされるときに縮小されます。ある時点で縮小されるポリゴンのシェルとホールは破棄されます。
  • tolerance_meters: DOUBLE は、形状が近似する許容範囲をメートル単位で指定します。許容値により、ポリゴンが理想的な半径からどの程度逸脱できるかが決まります。この引数の指定は省略できます。
  • endcap: （省略可）STRING には、ROUND と FLAT のいずれかのエンドキャップ スタイルを指定できます。デフォルト値は ROUND です。このオプションは、バッファリングされた LineString のエンドキャップにのみ影響します。
  • side: （省略可）STRING には、BOTH、LEFT、RIGHT の 3 つの線のスタイルのいずれかを指定できます。デフォルトは BOTH です。このオプションは、バッファリングされた LineString のエンドキャップにのみ影響します。
  • use_spheroid: （省略可）BOOL は、この関数で距離を測定する方法を決定します。use_spheroid が FALSE の場合、完全な球体の表面上の距離が測定されます。use_spheroid パラメータで現在サポートされている値は FALSE だけです。use_spheroid のデフォルト値は FALSE です。

戻り値の型

Polygon GEOGRAPHY

例

次の例は、あるポイントの ST_BUFFERWITHTOLERANCE の結果を示し、トレランスの 2 つの異なる値が指定されますが、バッファ半径 100 は同じです。バッファリングされたポイントは近似的な円です。tolerance_meters=25 の場合、トレランスはバッファ半径のかなりの割合であるため、入力ポイントを中心とした円を近似するには、5 つのセグメントのみが使用されます。tolerance_meters=1 の場合、トレランスはバッファ半径のはるかに小さい割合であるため、入力ポイントを中心とした円を近似するために 24 のエッジが使用されます。

SELECT
  -- tolerance_meters=25, or 25% of the buffer radius.
  ST_NumPoints(ST_BUFFERWITHTOLERANCE(ST_GEOGFROMTEXT('POINT(1 2)'), 100, 25)) AS five_sides,
  -- tolerance_meters=1, or 1% of the buffer radius.
  st_NumPoints(ST_BUFFERWITHTOLERANCE(ST_GEOGFROMTEXT('POINT(100 2)'), 100, 1)) AS twenty_four_sides;

+------------+-------------------+
| five_sides | twenty_four_sides |
+------------+-------------------+
| 6          | 24                |
+------------+-------------------+

ST_CENTROID

ST_CENTROID(geography_expression)

説明

入力 GEOGRAPHY のセントロイドを単一点の GEOGRAPHY として返します。

GEOGRAPHY のセントロイドとは、その GEOGRAPHY 内にある最高次元のコンポーネントのセントロイドを加重平均したものです。各次元のコンポーネントのセントロイドは次のように定義されます。

  • ポイントのセントロイドは、入力された座標の算術平均です。
  • LineString のセントロイドは、長さによって重み付けされたすべてのエッジのセントロイドです。各エッジのセントロイドは、そのエッジの測地線の中間点です。
  • ポリゴンのセントロイドはその質量の中心です。

入力された GEOGRAPHY が空の場合、空の GEOGRAPHY が返されます。

制約

まれに GEOGRAPHY のセントロイドを地球表面の単一点によって定義できないことがあり、その場合は、決定性である以外は任意のポイントが返されます。これが該当するのはセントロイドが正確に地球の中心にある場合（例: 対せき点のペアのセントロイドの場合）に限られるため、こうしたケースは非常にまれです。

戻り値の型

ポイントの GEOGRAPHY

ST_CENTROID_AGG

ST_CENTROID_AGG(geography)

説明

入力された GEOGRAPHY セットのセントロイドを単一点の GEOGRAPHY として計算します。

各 GEOGRAPHY のセントロイドの加重平均値が、入力 GEOGRAPHY のセットとしてのセントロイドになります。その入力内に存在する最高次元の GEOGRAPHY だけが、セット全体のセントロイドの計算に使用されます。たとえば、ラインを含む GEOGRAPHY とポイントだけを含む GEOGRAPHY の両方が入力に含まれている場合、ST_CENTROID_AGG では、ラインを含む GEOGRAPHY の加重平均値が返されます。ラインの次元が最高であるためです。この例の場合、ST_CENTROID_AGG では、セントロイド集計の計算時にポイントだけを含む GEOGRAPHY は無視されます。

ST_CENTROID_AGG は、NULL 入力の GEOGRAPHY 値を無視します。

ST_CENTROID_AGG の非集計バージョンと、個々の GEOGRAPHY 値のセントロイドの定義については、ST_CENTROID をご覧ください。

戻り値の型

ポイントの GEOGRAPHY

例

次のクエリでは、GEOGRAPHY 値セットに対する集計セントロイドが計算されます。最初のクエリへの入力はポイントだけを含んでいるので、それぞれの値が集計セントロイドに反映されます。また、ST_CENTROID_AGG は、ST_UNION_AGG の結果に対して ST_CENTROID を呼び出す場合とは異なります。つまり ST_CENTROID_AGG とは異なり、重複がユニオンによって削除されます。2 番目のクエリへの入力は複数の異なる次元を含み、セット内の最高次元の値（つまりラインを含む値）だけが集計セントロイドに反映されます。

SELECT ST_CENTROID_AGG(points) AS st_centroid_agg,
ST_CENTROID(ST_UNION_AGG(points)) AS centroid_of_union
FROM UNNEST([ST_GEOGPOINT(1, 5),
             ST_GEOGPOINT(1, 2),
             ST_GEOGPOINT(1, -1),
             ST_GEOGPOINT(1, -1)]) points;

+---------------------------+-------------------+
| st_centroid_agg           | centroid_of_union |
+---------------------------+-------------------+
| POINT(1 1.24961422620969) | POINT(1 2)        |
+---------------------------+-------------------+

SELECT ST_CENTROID_AGG(points) AS st_centroid_agg
FROM UNNEST([ST_GEOGPOINT(50, 26),
             ST_GEOGPOINT(34, 33.3),
             ST_GEOGFROMTEXT('LINESTRING(0 -1, 0 1)'),
             ST_GEOGFROMTEXT('LINESTRING(0 1, 0 3)')]) points;

+-----------------+
| st_centroid_agg |
+-----------------+
| POINT(0 1)      |
+-----------------+

ST_CLOSESTPOINT

ST_CLOSESTPOINT(geography_1, geography_2[, use_spheroid])

説明

geography_2 との距離を可能な限り小さくした geography_1 上のポイントを含む GEOGRAPHY を返します。これは、ST_CLOSESTPOINT によって返されたポイントと geography_2 との間の距離が、geography_1 上の他のあらゆるポイントと geography_2 との間の距離以下であることを暗黙的に示します。

入力された GEOGRAPHY のいずれかが空の場合、ST_CLOSESTPOINT から NULL が返されます。

任意の use_spheroid パラメータは、この関数で距離が測定される方法を決定します。use_spheroid が FALSE の場合、完全な球体の表面上の距離が測定されます。

use_spheroid パラメータで現在サポートされている値は FALSE だけです。use_spheroid のデフォルト値は FALSE です。

戻り値の型

ポイントの GEOGRAPHY

ST_CLUSTERDBSCAN

ST_CLUSTERDBSCAN(geography_column, epsilon, minimum_geographies)
OVER over_clause

over_clause:
  { named_window | ( [ window_specification ] ) }

window_specification:
  [ named_window ]
  [ PARTITION BY partition_expression [, ...] ]
  [ ORDER BY expression [ { ASC | DESC }  ] [, ...] ]

geography の列で DBSCAN クラスタリングを実行します。0 ベースのクラスタ番号を返します。

OVER 句とその使用方法について詳しくは、ウィンドウ関数の呼び出しをご覧ください。

入力パラメータ

  • geography_column: クラスタ化されている GEOGRAPHY の列。
  • epsilon: 中心値の半径（メートル単位）を指定するイプシロン。非負の FLOAT64 値です。
  • minimum_geographies: 単一クラスタ内の geography の最小数を指定します。密集した入力のみがクラスタを形成し、それ以外はノイズに分類されます。非負の INT64 値です。

geography 型と DBSCAN アルゴリズム

DBSCAN アルゴリズムは、データの高密度クラスタを識別し、ノイズの低密度領域の外れ値をマークします。geography_column を介して渡された geography は、DBSCAN アルゴリズムによって次の 3 つのいずれかの方法で分類されます。

  • 中心値: minimum_geographies geography から epsilon の範囲内にある geography が中心値になります。この中心値が、新しいクラスタの起点となるか、epsilon の範囲内にある中心値として、同じクラスタに追加されます。中心値は、epsilon の範囲内にある他の中心値と境界値とともに、クラスタ内でグループ化されます。
  • 境界値: 中心値からイプシロンの範囲内にある geography が境界値になります。epsilon の範囲内にある中心値として同じクラスタに追加されます。境界値は、複数のクラスタから epsilon の範囲内に存在する場合があります。この場合、境界値はいずれかのクラスタに任意に割り当てられ、後続の呼び出しで同じ結果が生成されます。
  • ノイズ: 中心値と境界値のいずれでもない geography はノイズに分類されます。ノイズ値は NULL クラスタに割り当てられます。空の GEOGRAPHY は常にノイズに分類されます。

制約

  • 引数 minimum_geographies は、負でない INT64 です。epsilon は負でない FLOAT64 です。
  • 空の geography はどのクラスタにも参加できません。
  • 境界値に対して複数のクラスタリング割り当てを行うことができます。境界値の geography は、ST_CLUSTERDBSCAN で任意の有効なクラスタに割り当てられます。

戻り値の型

geography 列の geography ごとに INT64 が戻ります。

例

この例では、minimum_geographies 引数を 1 に指定し、半径 100,000 メートルの DBSCAN クラスタリングを実行します。分析対象の geography は、ポイント、ライン、ポリゴンの組み合わせです。

WITH Geos as
  (SELECT 1 as row_id, ST_GEOGFROMTEXT('POINT EMPTY') as geo UNION ALL
    SELECT 2, ST_GEOGFROMTEXT('MULTIPOINT(1 1, 2 2, 4 4, 5 2)') UNION ALL
    SELECT 3, ST_GEOGFROMTEXT('POINT(14 15)') UNION ALL
    SELECT 4, ST_GEOGFROMTEXT('LINESTRING(40 1, 42 34, 44 39)') UNION ALL
    SELECT 5, ST_GEOGFROMTEXT('POLYGON((40 2, 40 1, 41 2, 40 2))'))
SELECT row_id, geo, ST_CLUSTERDBSCAN(geo, 1e5, 1) OVER () AS cluster_num FROM
Geos ORDER BY row_id

+--------+-----------------------------------+-------------+
| row_id |                geo                | cluster_num |
+--------+-----------------------------------+-------------+
|1       | GEOMETRYCOLLECTION EMPTY          |NULL         |
|2       | MULTIPOINT(1 1, 2 2, 5 2, 4 4)    |0            |
|3       | POINT(14 15)                      |1            |
|4       | LINESTRING(40 1, 42 34, 44 39)    |2            |
|5       | POLYGON((40 2, 40 1, 41 2, 40 2)) |2            |
+--------+-----------------------------------+-------------+

ST_CONTAINS

ST_CONTAINS(geography_1, geography_2)

説明

geography_2 のどのポイントも geography_1 の外部になく、内部が交差している場合は TRUE を返し、それ以外の場合は FALSE を返します。

注: GEOGRAPHY には、それ自体の境界は含まれません。ST_COVERS と比較してください。

戻り値の型

BOOL

例

次のクエリでは、ポリゴン POLYGON((1 1, 20 1, 10 20, 1 1)) に 3 つのポイント (0, 0)、(1, 1)、(10, 10)（それぞれこのポリゴンの外部、境界上、内部のポイント）が含まれているかどうかをポイントごとに検証します。

SELECT
  ST_GEOGPOINT(i, i) AS p,
  ST_CONTAINS(ST_GEOGFROMTEXT('POLYGON((1 1, 20 1, 10 20, 1 1))'),
              ST_GEOGPOINT(i, i)) AS `contains`
FROM UNNEST([0, 1, 10]) AS i;

+--------------+----------+
| p            | contains |
+--------------+----------+
| POINT(0 0)   | FALSE    |
| POINT(1 1)   | FALSE    |
| POINT(10 10) | TRUE     |
+--------------+----------+

ST_CONVEXHULL

ST_CONVEXHULL(geography_expression)

説明

入力 GEOGRAPHY の凸包を返します。凸包は、入力を含む GEOGRAPHY の最小の凸集合です。GEOGRAPHY 内のどのポイントのペアでも、そのポイントを結んだ測地線エッジも同じ GEOGRAPHY に含まれる場合、GEOGRAPHY は凸集合です。

ほとんどの場合、凸包は単一のポリゴンで構成されます。典型的なエッジの例には、次のものがあります。

  • 単一のポイントの凸包もポイントです。
  • 同一線上の 2 つ以上のポイントの凸包は、その LineString が凸包である限り LineString です。
  • 入力 GEOGRAPHY が半球を超える範囲に及ぶ場合、凸包は球全体になります。これには、正反対のポイントのペアを含む入力も含まれます。
  • ST_CONVEXHULL は、入力が NULL または空の GEOGRAPHY である場合、NULL を返します。

戻り値の型

GEOGRAPHY

例

ST_CONVEXHULL によって返される凸包は、入力に応じてポイント、LineString、またはポリゴンになります。

WITH Geographies AS
 (SELECT ST_GEOGFROMTEXT('POINT(1 1)') AS g UNION ALL
  SELECT ST_GEOGFROMTEXT('LINESTRING(1 1, 2 2)') AS g UNION ALL
  SELECT ST_GEOGFROMTEXT('MULTIPOINT(2 11, 4 12, 0 15, 1 9, 1 12)') AS g)
SELECT
  g AS input_geography,
  ST_CONVEXHULL(g) AS convex_hull
FROM Geographies;

+-----------------------------------------+--------------------------------------------------------+
|             input_geography             |                      convex_hull                       |
+-----------------------------------------+--------------------------------------------------------+
| POINT(1 1)                              | POINT(0.999999999999943 1)                             |
| LINESTRING(1 1, 2 2)                    | LINESTRING(2 2, 1.49988573656168 1.5000570914792, 1 1) |
| MULTIPOINT(1 9, 4 12, 2 11, 1 12, 0 15) | POLYGON((1 9, 4 12, 0 15, 1 9))                        |
+-----------------------------------------+--------------------------------------------------------+

ST_COVEREDBY

ST_COVEREDBY(geography_1, geography_2)

説明

geography_1 または geography_2 が空の場合、FALSE を返します。geography_1 に geography_2 の外部のポイントがない場合、TRUE を返します。

a と b の 2 つの GEOGRAPHY がある場合、ST_COVEREDBY(a, b) は同じ結果を ST_COVERS(b, a) として返します。引数の順序が逆になっている点に注意してください。

戻り値の型

BOOL

ST_COVERS

ST_COVERS(geography_1, geography_2)

説明

geography_1 または geography_2 が空の場合、FALSE を返します。geography_2 に geography_1 の外部のポイントがない場合、TRUE を返します。

戻り値の型

BOOL

例

次のクエリでは、ポリゴン POLYGON((1 1, 20 1, 10 20, 1 1)) に 3 つのポイント (0, 0)、(1, 1)、(10, 10)（それぞれこのポリゴンの外部、境界上、内部のポイント）が含まれているかどうかをポイントごとに検証します。

SELECT
  ST_GEOGPOINT(i, i) AS p,
  ST_COVERS(ST_GEOGFROMTEXT('POLYGON((1 1, 20 1, 10 20, 1 1))'),
            ST_GEOGPOINT(i, i)) AS `covers`
FROM UNNEST([0, 1, 10]) AS i;

+--------------+--------+
| p            | covers |
+--------------+--------+
| POINT(0 0)   | FALSE  |
| POINT(1 1)   | TRUE   |
| POINT(10 10) | TRUE   |
+--------------+--------+

ST_DIFFERENCE

ST_DIFFERENCE(geography_1, geography_2)

説明

geography_1 と geography_2 のポイントセットの相違部分を表す GEOGRAPHY を返します。したがって、結果は geography_2 と交差しない geography_1 の部分で構成されます。

geometry_1 が geometry_2 内に完全に包含されている場合、ST_DIFFERENCE から空の GEOGRAPHY が返されます。

制約

GoogleSQL の GEOGRAPHY で表される基本のジオメトリ オブジェクトは、閉じられたポイントセットに対応します。したがって ST_DIFFERENCE は、geography_1 と geography_2 のポイントセットの相違部分のクロージャです。これは、geography_1 と geography_2 が交差する場合、geography_2 の境界の一部がその相違部分に含まれる可能性があることを暗黙的に示唆します。

戻り値の型

GEOGRAPHY

例

次のクエリでは、geog1（大きいポリゴン POLYGON((0 0, 10 0, 10 10, 0 0))）と geog1（geog1 と交差する小さいポリゴン POLYGON((4 2, 6 2, 8 6, 4 2))）の違いを示します。結果は、geog2 と交差する箇所に穴がある geog1 になります。

SELECT
  ST_DIFFERENCE(
      ST_GEOGFROMTEXT('POLYGON((0 0, 10 0, 10 10, 0 0))'),
      ST_GEOGFROMTEXT('POLYGON((4 2, 6 2, 8 6, 4 2))')
  );

+--------------------------------------------------------+
| difference_of_geog1_and_geog2                          |
+--------------------------------------------------------+
| POLYGON((0 0, 10 0, 10 10, 0 0), (8 6, 6 2, 4 2, 8 6)) |
+--------------------------------------------------------+

ST_DIMENSION

ST_DIMENSION(geography_expression)

説明

入力された GEOGRAPHY に含まれる要素のうち、最高次元の要素の次元を返します。

各要素の次元は次のとおりです。

  • ポイントの次元は 0 です。
  • LineString の次元は 1 です。
  • ポリゴンの次元は 2 です。

入力された GEOGRAPHY が空の場合、ST_DIMENSION から -1 が返されます。

戻り値の型

INT64

ST_DISJOINT

ST_DISJOINT(geography_1, geography_2)

説明

geography_1 と geography_2 の交差が空の場合、つまり geography_1 に、geography_2 にも存在するポイントがない場合、TRUE を返します。

ST_DISJOINT は ST_INTERSECTS の論理否定です。

戻り値の型

BOOL

ST_DISTANCE

ST_DISTANCE(geography_1, geography_2[, use_spheroid])

説明

空でない 2 つの GEOGRAPHY の間の最短距離をメートル単位で返します。

入力された GEOGRAPHY のいずれかが空の場合、ST_DISTANCE から NULL が返されます。

任意の use_spheroid パラメータは、この関数で距離が測定される方法を決定します。use_spheroid が FALSE の場合、完全な球体の表面上の距離が測定されます。

use_spheroid パラメータで現在サポートされている値は FALSE だけです。use_spheroid のデフォルト値は FALSE です。

戻り値の型

FLOAT64

ST_DUMP

ST_DUMP(geography[, dimension])

説明

各要素が入力 GEOGRAPHY のコンポーネントである単純な GEOGRAPHY の ARRAY を返します。単純な GEOGRAPHY は、単一のポイント、LineString、またはポリゴンで構成されます。入力 GEOGRAPHY が単純な場合、結果は 1 つの要素になります。入力 GEOGRAPHY がコレクションの場合、ST_DUMP は、コレクション内の各コンポーネントに対して 1 つの単純な GEOGRAPHY を含む ARRAY を返します。

dimension を指定すると、この関数は、対応するディメンションの GEOGRAPHY のみを返します。ディメンションで -1 を指定することは、dimension を省略することと同じです。

戻り値の型

ARRAY<GEOGRAPHY>

例

次の例は、ST_DUMP が複雑な geography 内の単純な geography を返す方法を示しています。

WITH example AS (
  SELECT ST_GEOGFROMTEXT('POINT(0 0)') AS geography
  UNION ALL
  SELECT ST_GEOGFROMTEXT('MULTIPOINT(0 0, 1 1)') AS geography
  UNION ALL
  SELECT ST_GEOGFROMTEXT('GEOMETRYCOLLECTION(POINT(0 0), LINESTRING(1 2, 2 1))'))
SELECT
  geography AS original_geography,
  ST_DUMP(geography) AS dumped_geographies
FROM example

+-------------------------------------+------------------------------------+
|         original_geographies        |      dumped_geographies            |
+-------------------------------------+------------------------------------+
| POINT(0 0)                          | [POINT(0 0)]                       |
| MULTIPOINT(0 0, 1 1)                | [POINT(0 0), POINT(1 1)]           |
| GEOMETRYCOLLECTION(POINT(0 0),      | [POINT(0 0), LINESTRING(1 2, 2 1)] |
|   LINESTRING(1 2, 2 1))             |                                    |
+-------------------------------------+------------------------------------+

次の例は、ディメンション引数を含む ST_DUMP が、指定されたディメンションの単純な geography のみを返す方法を示しています。

WITH example AS (
  SELECT ST_GEOGFROMTEXT('GEOMETRYCOLLECTION(POINT(0 0), LINESTRING(1 2, 2 1))') AS geography)
SELECT
  geography AS original_geography,
  ST_DUMP(geography, 1) AS dumped_geographies
FROM example

+-------------------------------------+------------------------------+
|         original_geographies        |      dumped_geographies      |
+-------------------------------------+------------------------------+
| GEOMETRYCOLLECTION(POINT(0 0),      | [LINESTRING(1 2, 2 1)]       |
|   LINESTRING(1 2, 2 1))             |                              |
+-------------------------------------+------------------------------+

ST_DWITHIN

ST_DWITHIN(geography_1, geography_2, distance[, use_spheroid])

説明

geography_1 の少なくとも 1 つのポイントと geography_2 のいずれかのポイントとの間の距離が、distance 引数で指定された距離以下の場合は TRUE を返し、それ以外の場合は FALSE を返します。入力された GEOGRAPHY のいずれかが空の場合、ST_DWithin から FALSE が返されます。distance は、地球表面上でのメートル数で指定します。

任意の use_spheroid パラメータは、この関数で距離が測定される方法を決定します。use_spheroid が FALSE の場合、完全な球体の表面上の距離が測定されます。

use_spheroid パラメータで現在サポートされている値は FALSE だけです。use_spheroid のデフォルト値は FALSE です。

戻り値の型

BOOL

ST_ENDPOINT

ST_ENDPOINT(linestring_geography)

説明

LineString の geography の終点をポイントの geography として返します。入力が LineString でないか、入力が空の場合、エラーを返します。無効な入力の場合に、エラーの代わりに NULL を取得するには、SAFE 接頭辞を使用します。

戻り値の型

ポイントの GEOGRAPHY

例

SELECT ST_ENDPOINT(ST_GEOGFROMTEXT('LINESTRING(1 1, 2 1, 3 2, 3 3)')) last

+--------------+
| last         |
+--------------+
| POINT(3 3)   |
+--------------+

ST_EQUALS

ST_EQUALS(geography_1, geography_2)

説明

次の場合は TRUE 返します。geography_1 と geography_2 が同じ

GEOGRAPHY 値を表す場合。厳密には、次の条件が満たされていることを意味します。ST_COVERS(geography_1, geography_2) = TRUE かつ ST_COVERS(geography_2, geography_1) = TRUE、または、geography_1 と geography_2 が両方とも空である。

そのため、この 2 つの GEOGRAPHY は、同じジオメトリ構造を表している限り、ポイントや頂点の順序が異なっていても等しいと判断されます。

制約

ST_EQUALS は必ずしも推移的関数であるとは限りません。

戻り値の型

BOOL

ST_EXTENT

ST_EXTENT(geography_expression)

説明

一連の入力された GEOGRAPHY 値の境界ボックスを表す STRUCT を返します。境界ボックスは geography を囲む最小の矩形です。矩形のエッジは経度と緯度の実線に沿っています。

注意点:

  • すべての入力が NULL または空の geography である場合、NULL を返します。
  • 境界ボックスは、より小さい矩形を許容する場合、経度 180 度線と交差する可能性があります。この場合、境界ボックスは経度の境界の一つが [-180, 180] の範囲外であるため、xmin は最東端の値 xmax よりも小さくなります。
  • 境界ボックスの経度スパンが 180 度またはそれ以上である場合、この関数は経度範囲が [-180, 180] の境界ボックスを返します。

戻り値の型

STRUCT<xmin FLOAT64, ymin FLOAT64, xmax FLOAT64, ymax FLOAT64>。

境界ボックスのパーツ:

  • xmin: 矩形の境界を形成する最西端の経度の実線（X 座標）。
  • xmax: 矩形の境界を形成する最東端の経度の実線（X 座標）。
  • ymin: 矩形の境界を形成する最小緯度の実線（Y 座標）。
  • ymax: 矩形の境界を形成する最大緯度の実線（Y 座標）。

例

WITH data AS (
  SELECT 1 id, ST_GEOGFROMTEXT('POLYGON((-125 48, -124 46, -117 46, -117 49, -125 48))') g
  UNION ALL
  SELECT 2 id, ST_GEOGFROMTEXT('POLYGON((172 53, -130 55, -141 70, 172 53))') g
  UNION ALL
  SELECT 3 id, ST_GEOGFROMTEXT('POINT EMPTY') g
)
SELECT ST_EXTENT(g) AS box
FROM data

+----------------------------------------------+
| box                                          |
+----------------------------------------------+
| {xmin:172, ymin:46, xmax:243, ymax:70}       |
+----------------------------------------------+

ST_EXTENT の非集計バージョンについては、ST_BOUNDINGBOX をご覧ください。

ST_EXTERIORRING

ST_EXTERIORRING(polygon_geography)

説明

ポリゴン geography の最も外側のリングに対応する LineString の geography を返します。

  • 入力 geography がポリゴンの場合は、そのポリゴンの最も外側のリングを取得し、対応する LineString を返します。
  • 入力が完全な GEOGRAPHY の場合は、空の geography を返します。
  • 入力が単一のポリゴンでない場合は、エラーを返します。

無効な入力に対して、エラーではなく NULL を返すには、SAFE 接頭辞を使用します。

戻り値の型

  • LineString GEOGRAPHY
  • GEOGRAPHY を空にしてください

例

WITH geo as
 (SELECT ST_GEOGFROMTEXT('POLYGON((0 0, 1 4, 2 2, 0 0))') AS g UNION ALL
  SELECT ST_GEOGFROMTEXT('''POLYGON((1 1, 1 10, 5 10, 5 1, 1 1),
                                  (2 2, 3 4, 2 4, 2 2))''') as g)
SELECT ST_EXTERIORRING(g) AS ring FROM geo;

+---------------------------------------+
| ring                                  |
+---------------------------------------+
| LINESTRING(2 2, 1 4, 0 0, 2 2)        |
| LINESTRING(5 1, 5 10, 1 10, 1 1, 5 1) |
+---------------------------------------+

ST_GEOGFROM

ST_GEOGFROM(expression)

説明

STRING または BYTES の値の式を GEOGRAPHY の値に変換します。

expression が STRING 値を表す場合は、次のいずれかの形式の GEOGRAPHY 表現にする必要があります。

  • WKT 形式。この形式と使用要件の詳細については、ST_GEOGFROMTEXT をご覧ください。
  • 16 進数のテキスト形式の WKB。この形式と使用要件の詳細については、ST_GEOGFROMWKB をご覧ください。
  • GeoJSON 形式。この形式と使用要件の詳細については、ST_GEOGFROMGEOJSON をご覧ください。

expression が BYTES 値を表す場合は、WKB 形式の有効な GEOGRAPHY バイナリ式にする要があります。この形式と使用要件の詳細については、ST_GEOGFROMWKB をご覧ください。

expression が NULL の場合、出力は NULL です。

戻り値の型

GEOGRAPHY

例

WKT 形式の文字列を取得し、GEOGRAPHY ポリゴンを返します。

SELECT ST_GEOGFROM('POLYGON((0 0, 0 2, 2 2, 2 0, 0 0))') AS WKT_format

+------------------------------------+
| WKT_format                         |
+------------------------------------+
| POLYGON((2 0, 2 2, 0 2, 0 0, 2 0)) |
+------------------------------------+

WKB 形式の 16 進数でエンコードされた文字列を取得し、GEOGRAPHY ポイントを返します。

SELECT ST_GEOGFROM(FROM_HEX('010100000000000000000000400000000000001040')) AS WKB_format

+----------------+
| WKB_format     |
+----------------+
| POINT(2 4)     |
+----------------+

WKB 形式のバイトを取得し、GEOGRAPHY ポイントを返します。

SELECT ST_GEOGFROM('010100000000000000000000400000000000001040')-AS WKB_format

+----------------+
| WKB_format     |
+----------------+
| POINT(2 4)     |
+----------------+

GeoJSON 形式の文字列を取得し、GEOGRAPHY ポリゴンを返します。

SELECT ST_GEOGFROM(
  '{ "type": "Polygon", "coordinates": [ [ [2, 0], [2, 2], [1, 2], [0, 2], [0, 0], [2, 0] ] ] }'
) AS GEOJSON_format

+-----------------------------------------+
| GEOJSON_format                          |
+-----------------------------------------+
| POLYGON((2 0, 2 2, 1 2, 0 2, 0 0, 2 0)) |
+-----------------------------------------+

ST_GEOGFROMGEOJSON

ST_GEOGFROMGEOJSON(geojson_string [, make_valid => constant_expression])

説明

入力された GeoJSON 表現に対応する GEOGRAPHY 値を返します。

ST_GEOGFROMGEOJSON では、RFC 7946 を遵守した入力が受け入れられます。

パラメータ make_valid が TRUE に設定されている場合、この関数は、Open Geospatial Consortium セマンティクスに準拠していないポリゴンを修復しようとします。このパラメータは、名前付き引数の構文を使用します。make_valid => argument_value 構文を使用して指定する必要があります。

GoogleSQL の GEOGRAPHY には球状の測地線エッジがありますが、GeoJSON の Geometry オブジェクトには明確な平面エッジがあります。この 2 種類のエッジ間の変換を行う目的で、GoogleSQL では必要に応じてラインにポイントを追加し、結果として得られるエッジのシーケンスが元のエッジの 10 m 以内に収まるようにします。

GEOGRAPHY を GeoJSON としてフォーマットする場合には、ST_ASGEOJSON をご覧ください。

制約

JSON 入力には次の制約があります。

  • ST_GEOGFROMGEOJSON は JSON ジオメトリ フラグメントだけを受け入れるため、JSON ドキュメント全体の取り込みには使用できません。
  • 入力された JSON フラグメントは GeoJSON ジオメトリ型（Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection など）で構成されている必要があります。その他の GeoJSON 型（Feature や FeatureCollection など）を使用すると、エラーが発生します。
  • GeoJSON ジオメトリ型の coordinates メンバー内の位置は、2 つの要素で構成されている必要があります。その 1 つ目は経度、2 つ目は緯度です。したがって、ST_GEOGFROMGEOJSON では、coordinates メンバー内の位置として任意指定の 3 つ目の要素はサポートされません。

戻り値の型

GEOGRAPHY

ST_GEOGFROMTEXT

署名 1

ST_GEOGFROMTEXT(wkt_string[, oriented])

説明

入力された WKT 表現に対応する GEOGRAPHY 値を返します。

この関数は、BOOL 型の省略可能なパラメータ oriented をサポートします。このパラメータが TRUE に設定されると、入力に含まれるポリゴンは次のように方向付けられていると想定されます。すなわち、入力された頂点の順序でポリゴンの境界に沿って進んだ場合、ポリゴンの内部は左側になります。これにより、WKT で半球よりも大きいポリゴンを表現できます。oriented が FALSE であるか指定されていない場合、この関数はより小さい領域のポリゴンを返します。ST_MAKEPOLYGONORIENTED もご覧ください。これは、oriented=TRUE が指定された ST_GEOGFROMTEXT と類似しています。

GEOGRAPHY を WKT としてフォーマットするには、ST_ASTEXT を使用します。

制約

  • 入力エッジはすべて、平面の直線ではなく、球状の測地線であると想定されます。平面投影でデータを読み取る場合は、ST_GEOGFROMGEOJSON の使用を検討してください。球状の測地線と平面の直線の違いの詳細については、座標系とエッジをご覧ください。
  • この関数は、Z 接尾辞を持つ 3 次元ジオメトリと、M 接尾辞を持つ線形参照システム ジオメトリには対応していません。
  • ジオメトリ プリミティブとマルチパート ジオメトリのみに対応しています。具体的には Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection のみに対応しています。

戻り値の型

GEOGRAPHY

例

次のクエリでは、WKT 文字列 POLYGON((0 0, 0 2, 2 2, 2 0, 0 0)) を、方向付けされていないポリゴンと方向付けされたポリゴンの両方として読み取り、それぞれの結果にポイント (1, 1) が含まれているかどうかを確認します。

WITH polygon AS (SELECT 'POLYGON((0 0, 0 2, 2 2, 2 0, 0 0))' AS p)
SELECT
  ST_CONTAINS(ST_GEOGFROMTEXT(p), ST_GEOGPOINT(1, 1)) AS fromtext_default,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, FALSE), ST_GEOGPOINT(1, 1)) AS non_oriented,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, TRUE),  ST_GEOGPOINT(1, 1)) AS oriented
FROM polygon;

+-------------------+---------------+-----------+
| fromtext_default  | non_oriented  | oriented  |
+-------------------+---------------+-----------+
| TRUE              | TRUE          | FALSE     |
+-------------------+---------------+-----------+

署名 2

ST_GEOGFROMTEXT(wkt_string[, oriented => boolean_constant_1]
    [, planar => boolean_constant_2] [, make_valid => boolean_constant_3])

説明

入力された WKT 表現に対応する GEOGRAPHY 値を返します。

この関数は、BOOL 型の 3 つの省略可能なパラメータ（oriented、planar