地理関数

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

BigQuery の地理関数はすべて、入力引数のいずれかに 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_DUMP` `ST_EXTERIORRING` `ST_INTERIORRINGS` `ST_INTERSECTION` `ST_SIMPLIFY` `ST_SNAPTOGRID` `ST_UNION` `ST_UNION_AGG`（集計）	入力に基づいて新しい地理表現を生成する関数。
アクセサー	`ST_DIMENSION` `ST_DUMP` `ST_ENDPOINT` `ST_GEOMETRYTYPE` `ST_ISCOLLECTION` `ST_ISEMPTY` `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 表現で返します。

BigQuery の GEOGRAPHY には球状の測地線エッジがありますが、GeoJSON の Geometry オブジェクトには明確な平面エッジがあります。この 2 種類のエッジ間の変換を行う目的で、BigQuery では必要に応じてラインにポイントを追加し、結果として得られるエッジのシーケンスが元のエッジの 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) geo1, st_geogpoint(0, 0) 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) geo1, st_geogpoint(0, 0) geo2 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 です。

戻り値の型

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 です。

戻り値の型

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 パラメータで現在サポートされている値は FALSE だけです。use_spheroid のデフォルト値は FALSE です。

戻り値の型

GEOGRAPHY

ST_CLUSTERDBSCAN

ST_CLUSTERDBSCAN(geography_column, epsilon, minimum_geographies) OVER (...)

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

入力パラメータ

geography_column: クラスタ化されている GEOGRAPHY の列。
epsilon: 中心値の半径（メートル単位）を指定するイプシロン。非負の FLOAT64 値です。
minimum_geographies: 単一クラスタ内の geography の最小数を指定します。密集した入力のみがクラスタを形成し、それ以外はノイズに分類されます。非負の INT64 値です。
OVER: ウィンドウを指定します。分析関数をご覧ください。ST_CLUSTERDBSCAN で OVER 句を使用する方法には、以下の対象との互換性があります。
- PARTITION BY: 省略可。
- ORDER BY: 省略可。
- window_frame_clause: 禁止

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

例

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 が返されます。

制約

BigQuery の 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 パラメータで現在サポートされている値は 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

例

次の例は、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 パラメータで現在サポートされている値は 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 構文を使用して指定する必要があります。

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

制約

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

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

署名 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、make_valid）をサポートします。このシグネチャは、名前付き引数の構文を使用し、これらのパラメータは parameter_name => parameter_value 構文を使用して任意の順序で指定する必要があります。

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

パラメータ planar が TRUE に設定されている場合、ライン文字列とポリゴンのエッジは、BigQuery のデフォルトである球状の測地線のセマンティクスではなく、平面地図のセマンティクスを使用することが想定されます。球状の測地線と平面の直線の違いの詳細については、座標系とエッジをご覧ください。

パラメータ make_valid が TRUE に設定されている場合、この関数は、Open Geospatial Consortium セマンティクスに準拠していないポリゴンを修復しようとします。

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

制約

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

例

次のクエリでは、WKT 文字列 POLYGON((0 0, 0 2, 2 2, 0 2, 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, oriented => FALSE), ST_GEOGPOINT(1, 1)) AS non_oriented,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, oriented => TRUE),  ST_GEOGPOINT(1, 1)) AS oriented
FROM polygon;

+-------------------+---------------+-----------+
| fromtext_default  | non_oriented  | oriented  |
+-------------------+---------------+-----------+
| true              | true          | false     |
+-------------------+---------------+-----------+

次のクエリは、無効なポリゴンを含む WKT 文字列を GEOGRAPHY に変換します。WKT 文字列は、有効なポリゴンの 2 つのプロパティに違反しています。ポリゴンを記述するループは閉じておらず、自己交差が含まれています。make_valid オプションを使用すると、ST_GeogFromText は、これをマルチポリゴンのシェイプへと正常に変換します。

WITH data AS (
  SELECT 'polygon((0 -1, 2 1, 2 -1, 0 1))' wkt)
SELECT
  SAFE.ST_GeogFromText(wkt) as geom,
  SAFE.ST_GeogFromText(wkt, make_valid => TRUE) as valid_geom
FROM data

+------+-----------------------------------------------------------------+
| geom | valid_geom                                                      |
+------+-----------------------------------------------------------------+
| NULL | MULTIPOLYGON(((0 -1, 1 0, 0 1, 0 -1)), ((1 0, 2 -1, 2 1, 1 0))) |
+------+-----------------------------------------------------------------+

ST_GEOGFROMWKB

ST_GEOGFROMWKB(wkb_bytes_expression)
ST_GEOGFROMWKB(wkb_hex_string_expression)

説明

16 進数テキストの STRING または BYTES の値の式を GEOGRAPHY の値に変換します。式は WKB 形式である必要があります。

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

制約

入力エッジはすべて、平面の直線ではなく、球状の測地線であると想定されます。平面投影でデータを読み取る場合は、ST_GEOGFROMGEOJSON の使用を検討してください。

戻り値の型

GEOGRAPHY

ST_GEOGPOINT

ST_GEOGPOINT(longitude, latitude)

説明

単一のポイントを含む GEOGRAPHY を作成します。ST_GEOGPOINT は、指定された FLOAT64 の経度と緯度のパラメータからポイントを作成し、そのポイントを GEOGRAPHY 値に含めて返します。

制約

緯度の範囲は [-90, 90] です。緯度がこの範囲に含まれない場合、エラーが発生します。
経度は [-180, 180] の範囲外であっても許容されます。ST_GEOGPOINT では、入力された経度のモジュロ 360 を使用して、[-180, 180] の範囲内の経度が取得されます。

戻り値の型

GEOGRAPHY

ST_GEOGPOINTFROMGEOHASH

ST_GEOGPOINTFROMGEOHASH(geohash)

説明

GeoHash で定義された境界ボックスの中央のポイントに対応する GEOGRAPHY 値を返します。

戻り値の型

GEOGRAPHY

ST_GEOHASH

ST_GEOHASH(geography_expression, maxchars)

説明

geography_expression の GeoHash 表現を返します。生成される GeoHash には最大で maxchars 文字が組み込まれます。文字数が少ないほど、それに応じて精度が低くなります（言い換えると、境界ボックスが大きくなります）。

空の GEOGRAPHY オブジェクトに対して ST_GeoHash を使用すると、NULL が返されます。

制約

単一点を表す GEOGRAPHY オブジェクトだけがサポートされます。
maxchars の最大値は 20 です。

戻り値の型

STRING

例

10 文字の精度でシアトルセンターの GeoHash を返します。

SELECT ST_GEOHASH(ST_GEOGPOINT(-122.35, 47.62), 10) geohash

+--------------+
| geohash      |
+--------------+
| c22yzugqw7   |
+--------------+

ST_GEOMETRYTYPE

ST_GEOMETRYTYPE(geography_expression)

説明

入力 GEOGRAPHY を STRING として記述する Open Geospatial Consortium（OGC）ジオメトリタイプを返します。OGC ジオメトリタイプは、WKT と GeoJSON 形式で使用され、ST_ASTEXT、ST_ASGEOJSON のようになります。ST_GEOMETRYTYPE は、OGC ジオメトリタイプに接頭辞 ST_ を付けて返します。

ST_GEOMETRYTYPE は、入力に対して以下のタイプを返します。

単一点の地理: ST_Point を返します。
ポイントのみのコレクション: ST_MultiPoint を返します。
単一の LineString の地理: ST_LineString を返します。
Linestring のみのコレクション: ST_MultiLineString を返します。
単一ポリゴンの地理: ST_Polygon を返します。
ポリゴンのみのコレクション: ST_MultiPolygon を返します。
さまざまなディメンションの要素を含むコレクション、または入力が空の地理: ST_GeometryCollection を返します。

戻り値の型

STRING

例

次の例は、ST_GEOMETRYTYPE で地理を取得し、OGC ジオメトリタイプの名前を返す方法を示しています。

WITH example AS(
  SELECT ST_GeogFromText('POINT(0 1)') AS geography
  UNION ALL
  SELECT ST_GeogFromText('MULTILINESTRING((2 2, 3 4), (5 6, 7 7))')
  UNION ALL
  SELECT ST_GeogFromText('GEOMETRYCOLLECTION(MULTIPOINT(-1 2, 0 12), LINESTRING(-2 4, 0 6))')
  UNION ALL
  SELECT ST_GeogFromText('GEOMETRYCOLLECTION EMPTY'))
SELECT
  geography AS WKT,
  ST_GeometryType(geography) AS geometry_type_name
FROM example;

+-------------------------------------------------------------------+-----------------------+
| WKT                                                               | geometry_type_name    |
+-------------------------------------------------------------------+-----------------------+
| POINT(0 1)                                                        | ST_Point              |
| MULTILINESTRING((2 2, 3 4), (5 6, 7 7))                           | ST_MultiLineString    |
| GEOMETRYCOLLECTION(MULTIPOINT(-1 2, 0 12), LINESTRING(-2 4, 0 6)) | ST_GeometryCollection |
| GEOMETRYCOLLECTION EMPTY                                          | ST_GeometryCollection |
+-------------------------------------------------------------------+-----------------------+

ST_INTERIORRINGS

ST_INTERIORRINGS(polygon_geography)

説明

ポリゴン geography の内側のリングに対応する LineString の geography の配列を返します。それぞれの内側のリングは、入力ポリゴン内の穴の境界です。

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

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

戻り値の型

ARRAY

例

WITH geo AS (
  SELECT ST_GEOGFROMTEXT('polygon((0 0, 1 1, 1 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))') UNION ALL
  SELECT ST_GEOGFROMTEXT('polygon((1 1, 1 10, 5 10, 5 1, 1 1), (2 2.5, 3.5 3, 2.5 2, 2 2.5), (3.5 7, 4 6, 3 3, 3.5 7))') UNION ALL
  SELECT ST_GEOGFROMTEXT('fullglobe') UNION ALL
  SELECT null)
SELECT ST_INTERIORRINGS(g) AS rings FROM geo;

+----------------------------------------------------------------------------+
| rings                                                                      |
+----------------------------------------------------------------------------+
| []                                                                         |
| [LINESTRING(2 2, 3 4, 2 4, 2 2)]                                           |
| [LINESTRING(2.5 2, 3.5 3, 2 2.5, 2.5 2), LINESTRING(3 3, 4 6, 3.5 7, 3 3)] |
| []                                                                         |
| NULL                                                                       |
+----------------------------------------------------------------------------+

ST_INTERSECTION

ST_INTERSECTION(geography_1, geography_2)

説明

入力された 2 つの GEOGRAPHY のポイントセット交差を表す GEOGRAPHY を返します。したがって、その交差内のすべてのポイントが geography_1 と geography_2 の両方に存在します。

入力された 2 つの GEOGRAPHY が共通部分を持たない場合（つまり、入力された geometry_1 と geometry_2 の両方に存在するポイントがない場合）、空の GEOGRAPHY が返されます。

関連する述語関数については、ST_INTERSECTS と ST_DISJOINT をご覧ください。

戻り値の型

GEOGRAPHY

ST_INTERSECTS

ST_INTERSECTS(geography_1, geography_2)

説明

geography_1 と geography_2 のポイントセットの交差が空でない場合は TRUE を返します。したがって、入力された両方の GEOGRAPHY に存在するポイントが 1 つ以上ある場合、この関数から TRUE が返されます。

ST_INTERSECTS によって TRUE が返される場合、ST_DISJOINT によって FALSE が返されることを意味します。

戻り値の型

BOOL

ST_INTERSECTSBOX

ST_INTERSECTSBOX(geography, lng1, lat1, lng2, lat2)

説明

geography が [lng1, lng2] と [lat1, lat2] の間にある矩形を交差する場合、TRUE を返します。矩形のエッジは経度と緯度の実線に沿っています。lng1 と lng2 は、矩形の境界となる最小と最大の経度線を指定します。lat1 と lat2 は、矩形の境界となる最小と最大の緯度の実線を指定します。

経度と緯度の引数はすべて度数で指定します。

制約

入力引数には次の制約が適用されます。

緯度の度数は [-90, 90] の範囲内でなければなりません。
経度は次のいずれかのルールに従う必要があります。
- どちらの緯度も [-180, 180] 度の範囲内です。
- 経度の 1 つは [-180, 180] 度の範囲内で、lng2 - lng1 は [0, 360] 間隔です。

戻り値の型

BOOL

例

SELECT p, st_intersectsbox(p, -90, 0, 90, 20) AS box1,
       st_intersectsbox(p, 90, 0, -90, 20) AS box2
FROM UNNEST([st_geogpoint(10, 10), st_geogpoint(170, 10),
             st_geogpoint(30, 30)]) p
+----------------+--------------+--------------+
| p              | box1         | box2         |
+----------------+--------------+--------------+
| POINT(10 10)   | true         | false        |
+----------------+--------------+--------------+
| POINT(170 10)  | false        | true         |
+----------------+--------------+--------------+
| POINT(30 30)   | false        | false        |
+----------------+--------------+--------------+

ST_ISCOLLECTION

ST_ISCOLLECTION(geography_expression)

説明

ポイント、LineString、ポリゴンの合計数が 1 以上の場合、TRUE を返します。

空の GEOGRAPHY は集合ではありません。

戻り値の型

BOOL

ST_ISEMPTY

ST_ISEMPTY(geography_expression)

説明

指定された GEOGRAPHY が空の場合（つまり、GEOGRAPHY にポイント、ライン、ポリゴンがまったく含まれていない場合）、TRUE を返します。

注: BigQuery の空の GEOGRAPHY は、特定のジオメトリ形状に関連付けられません。たとえば、式 ST_GEOGFROMTEXT('POINT EMPTY') と ST_GEOGFROMTEXT('GEOMETRYCOLLECTION EMPTY') の結果は同じです。

戻り値の型

BOOL

ST_LENGTH

ST_LENGTH(geography_expression[, use_spheroid])

説明

入力された GEOGRAPHY に含まれるラインの長さの合計をメートル単位で返します。

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

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

戻り値の型

FLOAT64

ST_MAKELINE

ST_MAKELINE(geography_1, geography_2)

ST_MAKELINE(array_of_geography)

説明

入力された各 GEOGRAPHY に含まれるポイントまたはラインの頂点を指定順に連結することで、1 つの LineString を含む GEOGRAPHY を作成します。

ST_MAKELINE には 2 種類あります。最初のバリアントでは、入力は 2 つの GEOGRAPHY である必要があります。2 番目のバリアントでは、入力は GEOGRAPHY タイプの ARRAY でなければなりません。いずれのバリアントの場合も、各入力 GEOGRAPHY は次のいずれかの値で構成されている必要があります。

1 つのポイント。
1 つの LineString。

ST_MAKELINE の最初のバリアントで、入力 GEOGRAPHY が NULL の場合、ST_MAKELINE は NULL を返します。2 番目のバリアントで、入力 ARRAY または入力 ARRAY にある要素が NULL の場合、ST_MAKELINE は NULL を返します。

制約

それぞれのエッジは 180 度未満にする必要があります。

注: BigQuery のスナップ処理では、所定の短さのエッジが破棄され、2 つの端点が一緒にスナップされる場合があります。たとえば、入力された 2 つの GEOGRAPHY のそれぞれに 1 つのポイントが含まれ、その 2 つのポイント間の距離がスナップ半径より短い場合、その 2 つのポイントはまとめてスナップされます。この結果、GEOGRAPHY に含まれるポイントは 1 つだけになります。

戻り値の型

GEOGRAPHY

ST_MAKEPOLYGON

ST_MAKEPOLYGON(geography_expression[, array_of_geography])

説明

入力された LineString のそれぞれがポリゴンリングの構成に使用される LineString の入力から、1 つのポリゴンを含む GEOGRAPHY を作成します。

ST_MAKEPOLYGON には 2 種類あります。最初のバリアントでは、1 つの LineString のみを含む単一の GEOGRAPHY によって入力 LineString が提供されます。2 つ目のバリアントでは、入力が 1 つの GEOGRAPHY と複数 GEOGRAPHY からなる配列で構成され、各配列には 1 つの LineString のみが含まれます。各バリアントの最初の GEOGRAPHY が、ポリゴンシェルの作成に使用されます。入力 ARRAY で提供された追加の GEOGRAPHY は、ポリゴンホールを指定します。1 つの LineString のみを含む入力 GEOGRAPHY はすべて、次の条件に合致している必要があります。

LineString が、少なくとも 3 つの個別の頂点で構成されていること。
LineString は閉じている必要があります。つまり、最初と最後の頂点が同じでなければなりません。最初と最後の頂点が異なる場合、この関数によって最初の頂点から最後の頂点に至る最後のエッジが作成されます。

ST_MAKEPOLYGON の最初のバリアントでは、入力 GEOGRAPHY が NULL の場合、ST_MAKEPOLYGON は NULL を返します。2 番目のバリアントでは、入力 ARRAY または入力 ARRAY 内のいずれかの要素が NULL の場合、ST_MAKEPOLYGON は NULL を返します。

注: ST_MAKEPOLYGON では、空の GEOGRAPHY が入力として受け入れられます。ST_MAKEPOLYGON は空の GEOGRAPHY を、空の LineString を含むものとして解釈します。空の LineString は完全ループ（つまり、地球全体をカバーするポリゴン）を作成します。

制約

入力されたリング全体で、以下のように有効なポリゴンが形成される必要があります。

ポリゴンシェルが、各ポリゴンホールをカバーしている必要があります。
存在できるポリゴンシェルは 1 つだけです（最初に入力されたリングであること）。これは、ポリゴンホールはネストできないことを意味します。
ポリゴンリングが交差できる地点は、交差する両方のリングの境界上にある頂点だけです。

それぞれのエッジは 180 度未満にする必要があります。

各ポリゴンリングによって球体が 2 つの領域に分割されます。ST_MAKEPOLYGON に入力された最初の LineString がポリゴンシェルを形成し、その内部が 2 つの領域のうちの小さい方になるよう選択されます。それ以降に入力されるそれぞれの LineString がポリゴンホールを指定するので、ポリゴンの内部はすでに適切に定義されていることになります。ポリゴンの内部が 2 つの領域の大きい方になるようポリゴンシェルを定義する方法については、ST_MAKEPOLYGONORIENTED をご覧ください。

注: BigQuery のスナップ処理では、所定の短さのエッジが破棄され、2 つの端点が一緒にスナップされる場合があります。このため、頂点がスナップされた時点で、極めて小さいポリゴンホールが消滅する可能性、つまり、出力の GEOGRAPHY に 1 つのラインまたはポイントだけが含まれる可能性があります。

戻り値の型

GEOGRAPHY

ST_MAKEPOLYGONORIENTED

ST_MAKEPOLYGONORIENTED(array_of_geography)

説明

ST_MAKEPOLYGON と同様ですが、入力された各 LineString の頂点の順序で、各ポリゴンリングの方向が決定されます。ポリゴンリングの方向は、ポリゴンの内部を次のように定義します。すなわち、入力された頂点の順序でポリゴンの境界に沿って進んだ場合、ポリゴンの内部は左側になります。これは指定された各ポリゴンリングに適用されます。

ST_MAKEPOLYGONORIENTED では、内部がポリゴンリングのいずれの側になってもポリゴンを作成できるため、このコンストラクタはポリゴンコンストラクタのバリエーションの中でも柔軟性の高いものです。ただし、必要とされるポリゴンを作成するには、ポリゴンリングの方向を正しく設定することが重要です。

入力 ARRAY または入力 ARRAY にある要素が NULL の場合、ST_MAKEPOLYGONORIENTED は NULL を返します。

注: ST_MAKEPOLYGONORIENTED の入力引数に空の GEOGRAPHY が含まれることがあります。ST_MAKEPOLYGONORIENTED では、空の GEOGRAPHY は空の LineString を持つと解釈されるため、空の LineString では完全ループ、つまり、地球全体をカバーするポリゴンが作成されます。

制約

入力されたリング全体で、以下のように有効なポリゴンが形成される必要があります。

ポリゴンシェルが、各ポリゴンホールをカバーしている必要があります。
存在するポリゴンシェルは 1 つだけです（最初に入力されたリングであること）。これは、ポリゴンホールはネストできないことを意味します。
ポリゴンリングが交差できる地点は、交差する両方のリングの境界上にある頂点だけです。

それぞれのエッジは 180 度未満にする必要があります。

ST_MAKEPOLYGONORIENTED では、各 LineString で入力された頂点の順序に従ってポリゴンの方向を決定します。これは、ポリゴンシェルとすべてのポリゴンホールに適用されます。ST_MAKEPOLYGONORIENTED では、すべてのポリゴンホールがシェルとは逆方向であると想定されます。代わりに使用できるポリゴンコンストラクタと、有効なポリゴンの作成に関するその他の制約については、ST_MAKEPOLYGON をご覧ください。

注: BigQuery のスナップ処理により、所定の短さのエッジは破棄され、2 つの端点がスナップされて 1 つのポイントになります。そのため、LineString 内の頂点が一緒にスナップされて、1 つ以上のエッジが消滅することがあります。したがって、極めて小さいポリゴンホールが消滅し、生成された GEOGRAPHY に 1 つのラインまたはポイントのみが含まれる場合もあります。

戻り値の型

GEOGRAPHY

ST_MAXDISTANCE

ST_MAXDISTANCE(geography_1, geography_2[, use_spheroid])

空でない 2 つの GEOGRAPHY の間の最長距離（つまり、最初の GEOGRAPHY に含まれる最初の頂点から 2 番目の GEOGRAPHY に含まれる 2 番目の頂点までの距離）をメートル単位で返します。geography_1 と geography_2 が同じ GEOGRAPHY である場合、この関数は、その GEOGRAPHY に含まれる最も離れた 2 つの頂点の間の距離を返します。

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

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

戻り値の型

FLOAT64

ST_NPOINTS

ST_NPOINTS(geography_expression)

説明

ST_NUMPOINTS のエイリアス。

ST_NUMGEOMETRIES

ST_NUMGEOMETRIES(geography_expression)

説明

入力された GEOGRAPHY 内のジオメトリの数を返します。1 つの点、1 つの LineString、または 1 つのポリゴンの場合、ST_NUMGEOMETRIES は 1 を返します。ジオメトリのコレクションの場合、ST_NUMGEOMETRIES はコレクションを構成するジオメトリの数を返します。入力が空の GEOGRAPHY の場合、ST_NUMGEOMETRIES は 0 を返します。

戻り値の型

INT64

例

次の例では、単一点の地理、2 つのコレクション、空の地理に対して ST_NUMGEOMETRIES を計算します。

WITH example AS(
  SELECT ST_GeogFromText('POINT(5 0)') AS geography
  UNION ALL
  SELECT ST_GeogFromText('MULTIPOINT(0 1, 4 3, 2 6)') AS geography
  UNION ALL
  SELECT ST_GeogFromText('GEOMETRYCOLLECTION(POINT(0 0), LINESTRING(1 2, 2 1))') AS geography
  UNION ALL
  SELECT ST_GeogFromText('GEOMETRYCOLLECTION EMPTY'))
SELECT
  geography,
  ST_NumGeometries(geography) AS num_geometries,
FROM example;

+------------------------------------------------------+----------------+
| geography                                            | num_geometries |
+------------------------------------------------------+----------------+
| POINT(5 0)                                           | 1              |
| MULTIPOINT(0 1, 4 3, 2 6)                            | 3              |
| GEOMETRYCOLLECTION(POINT(0 0), LINESTRING(1 2, 2 1)) | 2              |
| GEOMETRYCOLLECTION EMPTY                             | 0              |
+------------------------------------------------------+----------------+

ST_NUMPOINTS

ST_NUMPOINTS(geography_expression)

説明

入力された GEOGRAPHY に含まれる頂点の数を返します。これには、ポイントの数、LineString の頂点の数、ポリゴンの頂点の数が含まれます。

注: ポリゴンリングの最初と最後の頂点は別々にカウントされます。

戻り値の型

INT64

ST_PERIMETER

ST_PERIMETER(geography_expression[, use_spheroid])

説明

入力された GEOGRAPHY に含まれるポリゴンの境界の長さをメートル単位で返します。

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

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

戻り値の型

FLOAT64

ST_POINTN

ST_POINTN(linestring_geography, index)

説明

LineString の geography の N 番目の点をポイント geography として返します。N はインデックスです。インデックスは 1 から始まります。負の値は LineString の末尾から逆方向にカウントされるため、-1 が最後のポイントになります。入力が LineString でないか、空の場合、または指定されたインデックスに頂点がない場合、エラーを返します。無効な入力の場合に、エラーの代わりに NULL を取得するには、SAFE 接頭辞を使用します。

戻り値の型

ポイントの GEOGRAPHY

例

次の例では、ST_POINTN、ST_STARTPOINT、ST_ENDPOINT を使用して LineString からポイントを抽出します。

WITH linestring AS (
    SELECT ST_GeogFromText('linestring(1 1, 2 1, 3 2, 3 3)') g
)
SELECT ST_PointN(g, 1) AS first, ST_PointN(g, -1) AS last,
    ST_PointN(g, 2) AS second, ST_PointN(g, -2) AS second_to_last
FROM linestring;

+--------------+--------------+--------------+----------------+
| first        | last         | second       | second_to_last |
+--------------+--------------+--------------+----------------+
| POINT(1 1)   | POINT(3 3)   | POINT(2 1)   | POINT(3 2)     |
+--------------+--------------+--------------+----------------+

ST_SIMPLIFY

ST_SIMPLIFY(geography, tolerance_meters)

説明

geography（入力された GEOGRAPHY）の簡略化されたバージョンを返します。入力された GEOGRAPHY は、短いエッジのほぼ真っ直ぐなチェーンを 1 つの長いエッジに置き換えることによって簡略化されます。入力された geography は、tolerance_meters で指定された許容値を超えて変更されることはありません。したがって、簡略化されたエッジは、そのエッジから削除されたすべての頂点の元の位置から tolerance_meters 以内に存在することが保証されます。tolerance_meters は、地球表面上でのメートル数で指定します。

ST_SIMPLIFY はトポロジ関係を保持します。したがって、交差するエッジが新たに作成されることはなく、出力は有効であり続けます。許容値が十分に大きい場合は、隣接する複数の形状が 1 つのオブジェクトにまとめられる場合があります。また、形状がより低い次元の形状に簡略化される場合もあります。

制約

ST_SIMPLIFY を有効にするには、tolerance_meters をゼロ以外にする必要があります。

tolerance_meters で指定された許容値が次のいずれかである場合、ST_SIMPLIFY はエラーを返します。

負の許容値。
約 7,800 km を超える値。

戻り値の型

GEOGRAPHY

例

次の例は、ST_SIMPLIFY が中間の頂点を削除することにより、入力行 GEOGRAPHY が簡略化される様子を示しています。

WITH example AS
 (SELECT ST_GEOGFROMTEXT('LINESTRING(0 0, 0.05 0, 0.1 0, 0.15 0, 2 0)') AS line)
SELECT
   line AS original_line,
   ST_SIMPLIFY(line, 1) AS simplified_line
FROM example;

+---------------------------------------------+----------------------+
|                original_line                |   simplified_line    |
+---------------------------------------------+----------------------+
| LINESTRING(0 0, 0.05 0, 0.1 0, 0.15 0, 2 0) | LINESTRING(0 0, 2 0) |
+---------------------------------------------+----------------------+

次の例は、ST_SIMPLIFY の結果が元の形状よりも低い次元の形状になる様子を示しています。

WITH example AS
 (SELECT
    ST_GEOGFROMTEXT('POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0))') AS polygon,
    t AS tolerance
  FROM UNNEST([1000, 10000, 100000]) AS t)
SELECT
  polygon AS original_triangle,
  tolerance AS tolerance_meters,
  ST_SIMPLIFY(polygon, tolerance) AS simplified_result
FROM example

+-------------------------------------+------------------+-------------------------------------+
|          original_triangle          | tolerance_meters |          simplified_result          |
+-------------------------------------+------------------+-------------------------------------+
| POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0)) |             1000 | POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0)) |
| POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0)) |            10000 |            LINESTRING(0 0, 0.1 0.1) |
| POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0)) |           100000 |                          POINT(0 0) |
+-------------------------------------+------------------+-------------------------------------+

ST_SNAPTOGRID

ST_SNAPTOGRID(geography_expression, grid_size)

説明

入力された GEOGRAPHY を、各頂点を経度 / 緯度のグリッドにスナップして返します。グリッドサイズは、度数で指定される grid_size パラメータの値によって決まります。

制約

任意のグリッドサイズはサポートされていません。grid_size パラメータは、10^n の形式になるように丸められます（ただし、-10 < n < 0）。

戻り値の型

GEOGRAPHY

ST_STARTPOINT

ST_STARTPOINT(linestring_geography)

説明

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

戻り値の型

ポイントの GEOGRAPHY

例

SELECT ST_StartPoint(ST_GeogFromText('linestring(1 1, 2 1, 3 2, 3 3)')) first

+--------------+
| first        |
+--------------+
| POINT(1 1)   |
+--------------+

ST_TOUCHES

ST_TOUCHES(geography_1, geography_2)

説明

次の 2 つの条件が満たされている場合、TRUE を返します。

geography_1 が geography_2 を交差している。
geography_1 の内部と geography_2 の内部が切り離されている。

戻り値の型

BOOL

ST_UNION

ST_UNION(geography_1, geography_2)

ST_UNION(array_of_geography)

説明

入力されたすべての GEOGRAPHY のポイントセットのユニオンに相当する GEOGRAPHY を返します。

ST_UNION には 2 種類あります。最初のバリアントでは、入力は 2 つの GEOGRAPHY である必要があります。2 番目では、入力は GEOGRAPHY タイプの ARRAY です。

ST_UNION の最初のバリアントで、入力 GEOGRAPHY が NULL の場合、ST_UNION は NULL を返します。2 番目のバリアントで、入力 ARRAY の値が NULL の場合、ST_UNION は NULL を返します。NULL 以外の入力 ARRAY では、ユニオンが計算され、NULL 要素は出力に影響を与えないように無視されます。

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

戻り値の型

GEOGRAPHY

ST_UNION_AGG

ST_UNION_AGG(geography)

説明

入力されたすべての GEOGRAPHY のポイントセットのユニオンに相当する GEOGRAPHY を返します。

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

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

戻り値の型

GEOGRAPHY

ST_WITHIN

ST_WITHIN(geography_1, geography_2)

説明

geography_1 に geography_2 の外部にあるポイントがなく、geography_1 と geography_2 の内部が交差している場合、TRUE を返します。

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

戻り値の型

BOOL

ST_X

ST_X(geography_expression)

説明

入力された単一点の GEOGRAPHY の経度を度数で返します。

入力された GEOGRAPHY が単一点ではなく、空の GEOGRAPHY を含んでいる場合、ST_X からエラーが返されます。NULL を取得するには、SAFE. 接頭辞を使用してください。

戻り値の型

FLOAT64

例

次の例では、ST_X と ST_Y を使用して、単一点の地理表現から座標を抽出します。

WITH points AS
   (SELECT ST_GEOGPOINT(i, i + 1) AS p FROM UNNEST([0, 5, 12]) AS i)
 SELECT
   p,
   ST_X(p) as longitude,
   ST_Y(p) as latitude
FROM points;

+--------------+-----------+----------+
| p            | longitude | latitude |
+--------------+-----------+----------+
| POINT(0 1)   | 0.0       | 1.0      |
| POINT(5 6)   | 5.0       | 6.0      |
| POINT(12 13) | 12.0      | 13.0     |
+--------------+-----------+----------+

ST_Y

ST_Y(geography_expression)

説明

入力された単一点の GEOGRAPHY の緯度を度数で返します。

入力された GEOGRAPHY が単一点ではなく、空の GEOGRAPHY を含んでいる場合、ST_Y からエラーが返されます。代わりに NULL が返されるようにするには、SAFE. 接頭辞を使用してください。

戻り値の型

FLOAT64

例

使用例については、ST_X をご覧ください。