地理関数によって BigQuery の GEOGRAPHY
値が処理または生成されます。地理関数のシグネチャは、すべて ST_
で始まります。BigQuery は、以下の関数をサポートしています。これらの関数を使用して、地理データの分析、地理フィーチャー間の空間関係の特定、GEOGRAPHY
の作成または操作を実施できます。
BigQuery の地理関数はすべて、入力引数のいずれかに NULL
があると、NULL
を返します。
カテゴリ
地理関数は、それぞれの動作に基づいて次のカテゴリに分類されます。
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
パラメータは、この関数で距離が測定される方法を決定します。use_spheroid
が FALSE
の場合、完全な球体の表面上の距離が測定されます。
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
例
次のクエリでは、ポリゴン POLYGON((1 1, 20 1, 10 20, 1 1))
に 3 つのポイント (0, 0)
、(1, 1)
、(10, 10)
(それぞれこのポリゴンの外部、境界上、内部のポイント)が含まれているかどうかをポイントごとに検証します。
SELECT
ST_GEOGPOINT(i, i) AS p,
ST_COVERS(ST_GEOGFROMTEXT('POLYGON((1 1, 20 1, 10 20, 1 1))'),
ST_GEOGPOINT(i, i)) AS `covers`
FROM UNNEST([0, 1, 10]) AS i;
+--------------+--------+
| p | covers |
+--------------+--------+
| POINT(0 0) | false |
| POINT(1 1) | true |
| POINT(10 10) | true |
+--------------+--------+
ST_DIFFERENCE
ST_DIFFERENCE(geography_1, geography_2)
説明
geography_1
と geography_2
のポイントセットの相違部分を表す GEOGRAPHY
を返します。したがって、結果は geography_2
と交差しない geography_1
の部分で構成されます。
geometry_1
が geometry_2
内に完全に包含されている場合、ST_DIFFERENCE
から空の GEOGRAPHY
が返されます。
制約
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
パラメータは、この関数で距離が測定される方法を決定します。use_spheroid
が FALSE
の場合、完全な球体の表面上の距離が測定されます。
use_spheroid
パラメータで現在サポートされている値は FALSE
だけです。use_spheroid
のデフォルト値は FALSE
です。
戻り値の型
FLOAT64
ST_DUMP
ST_DUMP(geography[, dimension])
説明
各要素が入力 GEOGRAPHY
のコンポーネントである単純な GEOGRAPHY
の ARRAY
を返します。単純な GEOGRAPHY
は、単一のポイント、LineString、またはポリゴンで構成されます。入力 GEOGRAPHY
が単純な場合、結果は 1 つの要素になります。入力 GEOGRAPHY
がコレクションの場合、ST_DUMP
は、コレクション内の各コンポーネントに対して 1 つの単純な GEOGRAPHY
を含む ARRAY
を返します。
dimension
を指定すると、この関数は、対応するディメンションの GEOGRAPHY
のみを返します。ディメンションで -1 を指定することは、dimension
を省略することと同じです。
戻り値の型
ARRAY
例
次の例は、ST_DUMP
が複雑な geography 内の単純な geography を返す方法を示しています。
WITH example AS (
SELECT ST_GeogFromText('POINT(0 0)') AS geography
UNION ALL
SELECT ST_GeogFromText('MULTIPOINT(0 0, 1 1)') AS geography
UNION ALL
SELECT ST_GeogFromText('GEOMETRYCOLLECTION(POINT(0 0), LINESTRING(1 2, 2 1))'))
SELECT
geography AS original_geography,
ST_DUMP(geography) AS dumped_geographies
FROM example
+-------------------------------------+-------------------------------+
| original_geographies | dumped_geographies |
+-------------------------------------+-------------------------------+
| POINT(0 0) | [POINT(0 0)] |
+-------------------------------------+-------------------------------+
| MULTIPOINT(0 0, 1 1) | [POINT(0 0), POINT(1 1)] |
+-------------------------------------+-------------------------------+
| GEOMETRYCOLLECTION(POINT(0 0), | [POINT(0 0), |
| LINESTRING(1 2, 2 1)) | LINESTRING(1 2, 2 1)] |
+-------------------------------------+-------------------------------+
次の例は、ディメンション引数を含む ST_DUMP
が、指定されたディメンションの単純な geography のみを返す方法を示しています。
WITH example AS (
SELECT ST_GeogFromText('GEOMETRYCOLLECTION(POINT(0 0), LINESTRING(1 2, 2 1))') AS geography)
SELECT
geography AS original_geography,
ST_DUMP(geography, 1) AS dumped_geographies
FROM example
+-------------------------------------+------------------------------+
| original_geographies | dumped_geographies |
+-------------------------------------+------------------------------+
| GEOMETRYCOLLECTION(POINT(0 0), | [LINESTRING(1 2, 2 1)] |
| LINESTRING(1 2, 2 1)) | |
+-------------------------------------+------------------------------+
ST_DWITHIN
ST_DWITHIN(geography_1, geography_2, distance[, use_spheroid])
説明
geography_1
の少なくとも 1 つのポイントと geography_2
のいずれかのポイントとの間の距離が、distance
引数で指定された距離以下の場合は TRUE
を返し、それ以外の場合は FALSE
を返します。入力された GEOGRAPHY
のいずれかが空の場合、ST_DWithin
から FALSE
が返されます。distance
は、地球表面上でのメートル数で指定します。
任意の use_spheroid
パラメータは、この関数で距離が測定される方法を決定します。use_spheroid
が FALSE
の場合、完全な球体の表面上の距離が測定されます。
use_spheroid
パラメータで現在サポートされている値は FALSE
だけです。use_spheroid
のデフォルト値は FALSE
です。
戻り値の型
BOOL
ST_ENDPOINT
ST_ENDPOINT(linestring_geography)
説明
LineString の geography の終点をポイントの geography として返します。入力が LineString でないか、入力が空の場合、エラーを返します。無効な入力の場合に、エラーの代わりに NULL
を取得するには、SAFE
接頭辞を使用します。
戻り値の型
ポイントの GEOGRAPHY
例
SELECT ST_EndPoint(ST_GeogFromText('linestring(1 1, 2 1, 3 2, 3 3)')) last
+--------------+
| last |
+--------------+
| POINT(3 3) |
+--------------+
ST_EQUALS
ST_EQUALS(geography_1, geography_2)
説明
次の場合は TRUE
返します。geography_1
と geography_2
が同じ
GEOGRAPHY
値を表す場合。厳密には、次の条件が満たされていることを意味します。ST_COVERS(geography_1, geography_2) = TRUE
かつ ST_COVERS(geography_2,
geography_1) = TRUE
、または、geography_1
と geography_2
が両方とも空である。
そのため、この 2 つの GEOGRAPHY
は、同じジオメトリ構造を表している限り、ポイントや頂点の順序が異なっていても等しいと判断されます。
制約
ST_EQUALS
は必ずしも推移的関数であるとは限りません。
戻り値の型
BOOL
ST_EXTENT
ST_EXTENT(geography_expression)
説明
一連の入力された GEOGRAPHY
値の境界ボックスを表す STRUCT
を返します。境界ボックスは geography を囲む最小の矩形です。矩形のエッジは経度と緯度の実線に沿っています。
注意点:
- すべての入力が
NULL
または空の geography である場合、NULL
を返します。 - 境界ボックスは、より小さい矩形を許容する場合、経度 180 度線と交差する可能性があります。この場合、境界ボックスは経度の境界の一つが [-180, 180] の範囲外であるため、
xmin
は最東端の値xmax
よりも小さくなります。 - 境界ボックスの経度スパンが 180 度またはそれ以上である場合、この関数は経度範囲が [-180, 180] の境界ボックスを返します。
戻り値の型
STRUCT<xmin FLOAT64, ymin FLOAT64, xmax FLOAT64, ymax FLOAT64>
。
境界ボックスのパーツ:
xmin
: 矩形の境界を形成する最西端の経度の実線(X 座標)。xmax
: 矩形の境界を形成する最東端の経度の実線(X 座標)。ymin
: 矩形の境界を形成する最小緯度の実線(Y 座標)。ymax
: 矩形の境界を形成する最大緯度の実線(Y 座標)。
例
WITH data AS (
SELECT 1 id, st_geogfromtext('polygon((-125 48, -124 46, -117 46, -117 49, -125 48))') g
UNION ALL
SELECT 2 id, st_geogfromtext('polygon((172 53, -130 55, -141 70, 172 53))') g
UNION ALL
SELECT 3 id, st_geogfromtext('point empty') g
)
SELECT st_extent(g) AS box
FROM data
+----------------------------------------------+
| box |
+----------------------------------------------+
| {xmin:172, ymin:46, xmax:243, ymax:70} |
+----------------------------------------------+
ST_EXTENT の非集計バージョンについては、ST_BOUNDINGBOX
をご覧ください。
ST_EXTERIORRING
ST_EXTERIORRING(polygon_geography)
説明
ポリゴン geography の最も外側のリングに対応する LineString の geography を返します。
- 入力 geography がポリゴンの場合は、そのポリゴンの最も外側のリングを取得し、対応する LineString を返します。
- 入力が完全な
GEOGRAPHY
の場合は、空の geography を返します。 - 入力が単一のポリゴンでない場合は、エラーを返します。
無効な入力に対して、エラーではなく NULL
を返すには、SAFE
接頭辞を使用します。
戻り値の型
- LineString
GEOGRAPHY
GEOGRAPHY
を空にしてください
例
WITH geo as
(SELECT ST_GEOGFROMTEXT('POLYGON((0 0, 1 4, 2 2, 0 0))') AS g UNION ALL
SELECT ST_GEOGFROMTEXT('''POLYGON((1 1, 1 10, 5 10, 5 1, 1 1),
(2 2, 3 4, 2 4, 2 2))''') as g)
SELECT ST_EXTERIORRING(g) AS ring FROM geo;
+---------------------------------------+
| ring |
+---------------------------------------+
| LINESTRING(2 2, 1 4, 0 0, 2 2) |
| LINESTRING(5 1, 5 10, 1 10, 1 1, 5 1) |
+---------------------------------------+
ST_GEOGFROM
ST_GEOGFROM(expression)
説明
STRING
または BYTES
の値の式を GEOGRAPHY
の値に変換します。
expression
が STRING
値を表す場合は、次のいずれかの形式の GEOGRAPHY
表現にする必要があります。
- WKT 形式。この形式と使用要件の詳細については、ST_GEOGFROMTEXT をご覧ください。
- 16 進数のテキスト形式の WKB。この形式と使用要件の詳細については、ST_GEOGFROMWKB をご覧ください。
- GeoJSON 形式。この形式と使用要件の詳細については、ST_GEOGFROMGEOJSON をご覧ください。
expression
が BYTES
値を表す場合は、WKB 形式の有効な GEOGRAPHY
バイナリ式にする要があります。この形式と使用要件の詳細については、ST_GEOGFROMWKB をご覧ください。
expression
が NULL
の場合、出力は NULL
です。
戻り値の型
GEOGRAPHY
例
WKT 形式の文字列を取得し、GEOGRAPHY
ポリゴンを返します。
SELECT ST_GEOGFROM('Polygon((0 0, 0 2, 2 2, 2 0, 0 0))') AS WKT_format
+------------------------------------+
| WKT_format |
+------------------------------------+
| POLYGON((2 0, 2 2, 0 2, 0 0, 2 0)) |
+------------------------------------+
WKB 形式の 16 進数でエンコードされた文字列を取得し、GEOGRAPHY
ポイントを返します。
SELECT ST_GEOGFROM(FROM_HEX('010100000000000000000000400000000000001040')) AS WKB_format
+----------------+
| WKB_format |
+----------------+
| POINT(2 4) |
+----------------+
WKB 形式のバイトを取得し、GEOGRAPHY
ポイントを返します。
SELECT ST_GEOGFROM('010100000000000000000000400000000000001040')-AS WKB_format
+----------------+
| WKB_format |
+----------------+
| POINT(2 4) |
+----------------+
GEOJSON 形式の文字列を取得し、GEOGRAPHY
ポリゴンを返します。
SELECT ST_GEOGFROM(
'{ "type": "Polygon", "coordinates": [ [ [2, 0], [2, 2], [1, 2], [0, 2], [0, 0], [2, 0] ] ] }'
) AS GEOJSON_format
+-----------------------------------------+
| GEOJSON_format |
+-----------------------------------------+
| POLYGON((2 0, 2 2, 1 2, 0 2, 0 0, 2 0)) |
+-----------------------------------------+
ST_GEOGFROMGEOJSON
ST_GEOGFROMGEOJSON(geojson_string [, make_valid => constant_expression])
説明
入力された GeoJSON 表現に対応する GEOGRAPHY
値を返します。
ST_GEOGFROMGEOJSON
では、RFC 7946 を遵守した入力が受け入れられます。
パラメータ make_valid
が TRUE
に設定されている場合、この関数は、Open Geospatial Consortium セマンティクスに準拠していないポリゴンを修復しようとします。このパラメータは、名前付き引数の構文を使用します。make_valid => argument_value
構文を使用して指定する必要があります。
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
署名 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
パラメータは、この関数で距離が測定される方法を決定します。use_spheroid
が FALSE
の場合、完全な球体の表面上の距離が測定されます。
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
パラメータは、この関数で距離が測定される方法を決定します。use_spheroid
が FALSE
の場合、完全な球体の表面上の距離が測定されます。
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
パラメータは、この関数で距離が測定される方法を決定します。use_spheroid
が FALSE
の場合、完全な球体の表面上の距離が測定されます。
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
をご覧ください。