標準 SQL の地理関数

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

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

コンストラクタ: 座標または既存の GEOGRAPHY 値から新しい GEOGRAPHY 値を作成する関数。ST_GEOGPOINT など。
パーサー: WKT や GeoJSON などの外部形式から GEOGRAPHY を作成する関数。たとえば、ST_GEOGFROMTEXT では WKT から GEOGRAPHY が作成されます。
フォーマッタ: GEOGRAPHY を WKT や GeoJSON などの外部形式にエクスポートする関数。たとえば、ST_ASTEXT では GEOGRAPHY が WKT 形式に設定されます。
変換: なんらかのプロパティに従い他から新しい GEOGRAPHY を生成する関数。ST_INTERSECTION や ST_BOUNDARY などがあります。
述語: 2 つの GEOGRAPHY 間の空間関係、または地理上のなんらかのプロパティに関して TRUE または FALSE を返す関数。この関数は、一般にフィルタ句で使用されます。述語の例として ST_DWITHIN があります。
アクセサ: 副次的影響を生じないで GEOGRAPHY のプロパティにアクセスできるようにする関数。たとえば ST_NUMPOINTS です。
測定: 1 つ以上の GEOGRAPHY の測定値を計算する関数。たとえば ST_DISTANCE です。
集計関数: 地理固有の集計関数。たとえば ST_UNION_AGG です。

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

ST_GEOGPOINT

ST_GEOGPOINT(longitude, latitude)

説明

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

制約

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

戻り値の型

GEOGRAPHY

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_GEOGFROMGEOJSON

ST_GEOGFROMGEOJSON(geojson_string)

説明

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

ST_GEOGFROMGEOJSON では、RFC 7946 に準拠した入力が受け入れられます。

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

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

ST_GEOGFROMTEXT

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, 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, 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     |
+-------------------+---------------+-----------+

ST_GEOGFROMWKB

ST_GEOGFROMWKB(wkb_bytes)

説明

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

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

制約

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

戻り値の型

GEOGRAPHY

ST_GEOGPOINTFROMGEOHASH

ST_GEOGPOINTFROMGEOHASH(geohash)

説明

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

戻り値の型

GEOGRAPHY

ST_ASGEOJSON

ST_ASGEOJSON(geography_expression)

説明

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

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

戻り値の型

STRING

ST_ASTEXT

ST_ASTEXT(geography_expression)

説明

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

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

戻り値の型

STRING

ST_GEOHASH

ST_GEOHASH(geography_expression, maxchars)

説明

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

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

制約

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

例

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

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

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

戻り値の型

STRING

ST_ASBINARY

ST_ASBINARY(geography_expression)

説明

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

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

戻り値の型

BYTES

ST_BOUNDARY

ST_BOUNDARY(geography_expression)

説明

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

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

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

戻り値の型

GEOGRAPHY

ST_CENTROID

ST_CENTROID(geography_expression)

説明

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

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

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

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

制約

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

戻り値の型

GEOGRAPHY

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_DIFFERENCE

ST_DIFFERENCE(geography_1, geography_2)

説明

geography_1 と geography_2 のポイントセットの相違部分を表す GEOGRAPHY を返します。

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

制約

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

戻り値の型

GEOGRAPHY

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_SNAPTOGRID

ST_SNAPTOGRID(geography_expression, grid_size)

説明

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

制約

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

戻り値の型

GEOGRAPHY

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_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_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_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 をご覧ください。

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_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_DISJOINT

ST_DISJOINT(geography_1, geography_2)

説明

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

ST_DISJOINT は ST_INTERSECTS の論理否定です。

戻り値の型

GEOGRAPHY

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_EQUALS

ST_EQUALS(geography_1, geography_2)

説明

geography_1 と geography_2 が同じ GEOGRAPHY 値を表す場合は TRUE を返します。厳密には、次のいずれかの条件に当てはまることを意味します。

ST_COVERS(geography_1, geography_2) = TRUE であり、ST_COVERS(geography_2, geography_1) = TRUE である。
geography_1 と geography_2 が両方とも空である。

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

制約

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

戻り値の型

BOOL

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] の範囲内でなければなりません。

戻り値の型

BOOL

ST_TOUCHES

ST_TOUCHES(geography_1, geography_2)

説明

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

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

戻り値の型

BOOL

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_ISEMPTY

ST_ISEMPTY(geography_expression)

説明

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

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

戻り値の型

BOOL

ST_ISCOLLECTION

ST_ISCOLLECTION(geography_expression)

説明

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

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

戻り値の型

BOOL

ST_DIMENSION

ST_DIMENSION(geography_expression)

説明

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

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

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

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

戻り値の型

INT64

ST_NUMPOINTS

ST_NUMPOINTS(geography_expression)

説明

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

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

戻り値の型

INT64

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_AREA

ST_AREA(geography_expression[, use_spheroid])

説明

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

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

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

戻り値の型

FLOAT64

ST_DISTANCE

ST_DISTANCE(geography_1, geography_2[, use_spheroid])

説明

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

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

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

戻り値の型

FLOAT64

ST_LENGTH

ST_LENGTH(geography_expression[, use_spheroid])

説明

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

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

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

戻り値の型

FLOAT64

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_PERIMETER

ST_PERIMETER(geography_expression[, use_spheroid])

説明

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

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

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

戻り値の型

FLOAT64

ST_UNION_AGG

ST_UNION_AGG(geography)

説明

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

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

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

戻り値の型

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)      |
+-----------------+