標準 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 から新しい 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 を作成します。

入力は、2 つの GEOGRAPHY、または型が GEOGRAPHY の ARRAY です。入力された各 GEOGRAPHY は次のいずれかの値で構成されている必要があります。

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

制約

各エッジに許容されるスパン範囲は 180 度未満にする必要があります。

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

戻り値の型

GEOGRAPHY

ST_MAKEPOLYGON

ST_MAKEPOLYGON(geography_expression)

ST_MAKEPOLYGON(geography_expression, array_of_geography)

説明

LineString の入力から 1 つのポリゴンを含む GEOGRAPHY を作成します。入力された各 LineString を使用してポリゴンリングが作成されます。

LineString の入力は、1 つの LineString のみを含む単一の GEOGRAPHY によって、または単一の GEOGRAPHY とそれぞれが LineString を 1 つ含む GEOGRAPHY の配列によって指定されます。常に最初の GEOGRAPHY がポリゴンシェルの作成に使用されます。配列内の先頭以外の GEOGRAPHY ではポリゴンホールが指定されます。LineString 1 つのみが含まれる入力 GEOGRAPHY はすべて、次の条件に合致している必要があります。

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

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

注: 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)

ST_GEOGFROMTEXT(wkt_string, oriented)

説明

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

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

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

制約

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

戻り値の型

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

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_UNION

ST_UNION(geography_1, geography_2)

ST_UNION(array_of_geography)

説明

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

入力は、2 つの GEOGRAPHY、または型が GEOGRAPHY である ARRAY です。

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) のそれぞれが含まれているかどうかを検証します。この 3 つのポイントはそれぞれ、このポリゴンの外部、境界上、内部にあります。

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

例

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

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)

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_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 つの geography がある場合、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_AREA

ST_AREA(geography_expression)

ST_AREA(geography_expression, use_spheroid)

説明

入力された GEOGRAPHY 内のポリゴンが覆っている面積を平方メートルで返します。

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

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

戻り値の型

FLOAT64

ST_DISTANCE

ST_DISTANCE(geography_1, geography_2)

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)

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)

ST_MAXDISTANCE(geography_1, geography_2, use_spheroid)

空でない 2 つの GEOGRAPHY の間の最長距離をメートル単位で返します。つまり最初の頂点が最初の GEOGRAPHY 内にあり、2 番目の頂点が 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)

ST_PERIMETER(geography_expression, use_spheroid)

説明

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

geography_expression がポイントまたはラインの場合は、0 を返します。geography_expression が集合の場合、その集合内のポリゴンの周囲の長さを返します。集合にポリゴンが含まれていない場合は 0 を返します。

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

戻り値の型

FLOAT64

ST_UNION_AGG

ST_UNION_AGG(geography)

説明

入力されたすべての GEOGRAPHY のポイントセットのユニオンに相当する 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 の非集計バージョンと、個々の 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_GEOGPOINT

ST_MAKELINE

ST_MAKEPOLYGON

ST_MAKEPOLYGONORIENTED

ST_GEOGFROMGEOJSON

ST_GEOGFROMTEXT

ST_GEOGFROMWKB

ST_ASGEOJSON

ST_ASTEXT

ST_GEOHASH

ST_ASBINARY

ST_BOUNDARY

ST_CENTROID

ST_CLOSESTPOINT

ST_DIFFERENCE

ST_INTERSECTION

ST_SNAPTOGRID

ST_UNION

ST_X

ST_Y

ST_CONTAINS

ST_COVEREDBY

ST_COVERS

ST_DISJOINT

ST_DWITHIN

ST_EQUALS

ST_INTERSECTS

ST_INTERSECTSBOX

ST_TOUCHES

ST_WITHIN

ST_ISEMPTY

ST_ISCOLLECTION

ST_DIMENSION

ST_NUMPOINTS

ST_AREA

ST_DISTANCE

ST_LENGTH

ST_MAXDISTANCE

ST_PERIMETER

ST_UNION_AGG

ST_CENTROID_AGG

フィードバックを送信...