地理位置函数用于生成 BigQuery GEOGRAPHY
值或对其进行操作。任何地理函数的签名均以 ST_
开头。BigQuery 支持以下函数,这些函数可用于分析地理数据、确定地貌之间的空间关系,以及构造或操作 GEOGRAPHY
。
如果任何输入参数为 NULL
,则所有 BigQuery 地理函数均返回 NULL
。
类别
地理函数根据其行为分为以下类别:
S2_CELLIDFROMPOINT
S2_CELLIDFROMPOINT(point_geography[, level => cell_level])
说明
返回覆盖点 GEOGRAPHY
的 S2 单元 ID。
- 可选的
INT64
参数level
指定返回单元的 S2 单元级别。为此参数命名是可选操作。
这是与利用 S2 几何图形库的系统互操作性的高级功能。
限制条件
- 以有符号
INT64
位(等效于无符号 64 位整数表示形式)形式返回单元 ID。 - 可以返回负单元 ID。
- 有效的 S2 单元级别为 0 到 30。
- 如果未明确指定,则
level
默认为 30。 - 该函数仅支持单点 GEOGRAPHY。如果输入可以是点集、线串、多边形或空的
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 几何图形库的系统互操作性的高级功能。
限制条件
- 以有符号
INT64
位(等效于无符号 64 位整数表示形式)形式返回单元 ID。 - 可以返回负单元 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)
说明
获取三个点 GEOGRAPHY
值,它们表示两条相交的线。返回这些线之间的夹角。点 2 和点 1 表示第一条线,点 2 和点 3 表示第二条线。这些线之间的夹角以弧度表示,范围为 [0, 2pi)
。夹角按顺时针方向从第一条线开始测量,直至第二条线。
ST_ANGLE
存在以下边缘情况:
- 如果点 2 和点 3 相同,则返回
NULL
。 - 如果点 2 和点 1 相同,则返回
NULL
。 - 如果点 2 和点 3 是完全对映点,则返回
NULL
。 - 如果点 2 和点 1 是完全对映点,则返回
NULL
。 - 如果任何输入地理位置不是单点或为空地理位置,则会抛出错误。
返回类型
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
对象明确具有平面边。为了在这两种边之间进行转换,BigQuery 会在必要时为线段添加其他点,以使转换后的边序列保持在原始边的 10 米范围内。
如需按照 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)
说明
接受两个点 GEOGRAPHY
值,并返回由点 1 和点 2 形成的线段的方位角。方位角是点 1 的真北方向线与点 1 和点 2 形成的线段之间的角的弧度。
正角在球面上按顺时针方向测量。 例如,线段的方位角:
- 指北是
0
- 指东是
PI/2
- 指南是
PI
- 指西是
3PI/2
ST_AZIMUTH
存在以下边缘情况:
- 如果两个输入点相同,则返回
NULL
。 - 如果两个输入点是完全对映点,则返回
NULL
。 - 如果任一输入地理位置不是单点或为空地理位置,则会抛出错误。
返回类型
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
的每个组成部分边界的定义如下:
- 点的边界为空。
- 线串的边界由线串的端点组成。
- 多边形的边界由构成多边形外环及其所有内环的线串组成。
返回类型
GEOGRAPHY
ST_BOUNDINGBOX
ST_BOUNDINGBOX(geography_expression)
说明
返回表示指定地理位置边界框的 STRUCT
。边界框是围绕该地理位置的最小矩形。矩形的边由经度和纬度的恒定线组成。
注意事项:
- 如果输入为
NULL
或空地理位置,则返回NULL
。 - 如果允许较小的矩形,则边界框可能会穿过对向子午线。在这种情况下,边界框的其中一个纵向边界超出 [-180, 180] 范围,因此
xmin
小于最东值xmax
。
返回类型
STRUCT<xmin FLOAT64, ymin FLOAT64, xmax FLOAT64, ymax FLOAT64>
。
边界框部分:
xmin
:用于限制矩形边界的最西恒定经度线。xmax
:用于限制矩形边界的最东恒定经度线。ymin
:用于限制矩形边界的最短恒定纬度线。ymax
:用于限制矩形边界的最长恒定纬度线。
示例
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
。buffer_radius
:DOUBLE
,表示输入地理位置周围缓冲区的半径。半径以米为单位。请注意,使用负buffer_radius
缓冲时,多边形会收缩。收缩到某个点的多边形外环和孔会被舍弃。num_seg_quarter_circle
:(可选)DOUBLE
指定用于近似四分之一圆的片段数。默认值为8.0
。为此参数命名是可选操作。endcap
:(可选)STRING
可让您指定两种结尾样式之一:ROUND
和FLAT
。默认值为ROUND
。此选项只会影响已缓冲 LineString 的结尾。side
:(可选)STRING
可让您为线条指定以下三种可能的值之一:BOTH
、LEFT
和RIGHT
。默认值为BOTH
。 此选项仅影响 LineString 的缓冲方式。use_spheroid
:(可选)BOOL
用于确定此函数计算距离的方式。如果use_spheroid
为FALSE
,则此函数会计算完美球面上的距离。use_spheroid
参数目前仅支持值FALSE
。use_spheroid
的默认值为FALSE
。
返回类型
GEOGRAPHY
示例
以下示例展示了某个点的 ST_BUFFER
结果。缓冲点为近似圆。当为 num_seg_quarter_circle = 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
。buffer_radius
:DOUBLE
,表示输入地理位置周围缓冲区的半径。半径以米为单位。请注意,使用负buffer_radius
缓冲时,多边形会收缩。收缩到某个点的多边形外环和孔会被舍弃。tolerance_meters
:DOUBLE
指定对近似形状的容忍度(以米为单位)。容忍度决定多边形与理想半径的差距。为此参数命名是可选操作。endcap
:(可选)STRING
可让您指定两种结尾样式之一:ROUND
和FLAT
。默认值为ROUND
。此选项只会影响已缓冲 LineString 的结尾。side
:(可选)STRING
可让您指定三种可能的线条样式之一:BOTH
、LEFT
和RIGHT
。默认值为BOTH
。 此选项只会影响已缓冲 LineString 的结尾。use_spheroid
:(可选)BOOL
用于确定此函数计算距离的方式。如果use_spheroid
为FALSE
,则此函数会计算完美球面上的距离。use_spheroid
参数目前仅支持值FALSE
。use_spheroid
的默认值为FALSE
。
返回类型
GEOGRAPHY
示例
以下示例展示了某个点的 ST_BUFFERWITHTOLERANCE
结果,假设容忍度为两个不同的值,但缓冲区半径均为 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
的最高维组成部分的形心的加权平均值。每个维度组成部分的形心的定义如下:
- 点的形心是输入坐标的算术平均值。
- 线串的形心是所有边按长度加权的形心。每条边的形心是其测地线中点。
- 多边形的形心是其质心。
如果输入 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
不同,计算并集的函数会移除重复项。第二个查询的输入具有混合维度,其中只有具有最高维度的值(线段)才会影响聚合形心。
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
,其中包含 geography_1
上与 geography_2
距离最小的点。这意味着,ST_CLOSESTPOINT
返回的点与 geography_2
之间的距离小于或等于 geography_1
上的任何其他点与 geography_2
之间的距离。
如果任一输入 GEOGRAPHY
为空,则 ST_CLOSESTPOINT
返回 NULL
。
可选的 use_spheroid
参数用于确定此函数计算距离的方式。如果 use_spheroid
为 FALSE
,则此函数会计算完美球面上的距离。
use_spheroid
参数目前仅支持值 FALSE
。use_spheroid
的默认值为 FALSE
。
返回类型
GEOGRAPHY
ST_CLUSTERDBSCAN
ST_CLUSTERDBSCAN(geography_column, epsilon, minimum_geographies)
OVER over_clause
over_clause:
{ named_window | ( [ window_specification ] ) }
window_specification:
[ named_window ]
[ PARTITION BY partition_expression [, ...] ]
[ ORDER BY expression [ { ASC | DESC } ] [, ...] ]
对地理位置列执行 DBSCAN 聚类。返回从 0 开始的集群编号。
如需详细了解 OVER
子句及其用法,请参阅窗口函数调用。
输入参数
geography_column
:聚簇的GEOGRAPHY
列。epsilon
:指定半径的 Epsilon(以米为单位),用于测量距离核心的值。非负FLOAT64
值。minimum_geographies
:指定单个集群中地理位置数量下限。只有密集输入才能形成一个集群,否则会被分类为噪声。非负INT64
值。
地理位置类型和 DBSCAN 算法
DBSCAN 算法可识别高密度数据簇,并在低密度噪声区域中标记离群值。可通过 DBSCAN 算法以下述三种方式之一对从 geography_column
传入的地理位置进行分类:
- 核心值:如果地理位置在
minimum_geographies
地理位置的epsilon
距离范围内(包括自身本身),则该地理位置为核心值。核心值将启动新集群,或作为核心值添加到在epsilon
距离范围内的相同集群。核心值以及epsilon
距离范围内的其他所有核心和边界值划分到同一个集群组。 - 边界值:如果地理位置位于核心值的 epsilon 距离范围内,则地理位置是边界值。该节点将作为核心值添加到
epsilon
距离范围内的相同集群。边界值可以位于多个集群的epsilon
距离范围内。在这种情况下,可以随意为任一集群分配该函数,且该函数会在后续调用中产生相同的结果。 - 噪声:如果既不是核心值,也不是边界值,则地理位置为噪声。噪声值会分配给
NULL
集群。空GEOGRAPHY
始终归类为噪音。
限制条件
- 参数
minimum_geographies
是非负INT64
,epsilon
是非负FLOAT64
。 - 空的地理位置无法加入任何集群。
- 可对边界值进行多次聚类分配。如果地理位置是边界值,
ST_CLUSTERDBSCAN
会将其分配给任意一个有效集群。
返回类型
地理位置列中的每个地理位置的 INT64
。
示例
本示例执行半径为 100,000 米,minimum_geographies
参数为 1 的 DBSCAN 聚类。被分析的地区由点、线和多边形组成。
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))
是否包含 (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
是凸形。
在大多数情况下,凸包由单个多边形组成。值得注意的边缘情况包括:
- 单个点的凸包也是一个点。
- 两个或多个共线点的凸包是线串,只要该线串是凸形即可。
- 如果输入
GEOGRAPHY
的跨度大于半球,则凸包就是完整球体。这包括任何包含一对反经纬度点的输入。 - 如果输入是
NULL
或空的GEOGRAPHY
,则ST_CONVEXHULL
返回NULL
。
返回类型
GEOGRAPHY
示例
ST_CONVEXHULL
返回的凸形可以是点、线串或多边形,具体取决于输入。
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
。
对于给定的两个 GEOGRAPHY
(a
和 b
),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))
是否覆盖 (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_1
中与 geography_2
不相交的部分。
如果 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))
)之间的差异。结果是带有一个孔的 geog1
,geog2
在该孔处与其相交。
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
。 - 线串的维度为
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])
说明
返回两个非空 GEOGRAPHY
之间的最短距离(以米为单位)。
如果任一输入 GEOGRAPHY
为空,则 ST_DISTANCE
返回 NULL
。
可选的 use_spheroid
参数用于确定此函数计算距离的方式。如果 use_spheroid
为 FALSE
,则此函数会计算完美球面上的距离。
use_spheroid
参数目前仅支持值 FALSE
。use_spheroid
的默认值为 FALSE
。
返回类型
FLOAT64
ST_DUMP
ST_DUMP(geography[, dimension])
说明
返回由简单 GEOGRAPHY
组成的 ARRAY
,其中每个元素都是输入 GEOGRAPHY
的组件。简单的 GEOGRAPHY
由单个点、线串或多边形组成。如果输入 GEOGRAPHY
很简单,则结果是单个元素。当输入 GEOGRAPHY
是一个集合时,ST_DUMP
会为集合中的每个组件返回一个简单 GEOGRAPHY
的 ARRAY
。
如果提供了 dimension
,则此函数仅返回相应维度的 GEOGRAPHY
。维度 -1 相当于省略 dimension
。
返回类型
ARRAY
示例
以下示例演示了 ST_DUMP
如何返回复杂地理位置中的简单地理位置。
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
仅返回给定维度的简单地理位置。
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
中至少有一个点与 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)
说明
返回线串地理位置的最后一个点作为点地理位置。如果输入不是线串或输入为空,则会返回错误。使用 SAFE
前缀可获取 NULL
,表示无效输入而非错误。
返回类型
点 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)
说明
如果 geography_1
和 geography_2
代表相同的值,则返回 TRUE
GEOGRAPHY
值。更确切地说,这意味着必须满足以下条件之一:
+ ST_COVERS(geography_1, geography_2) = TRUE
和 ST_COVERS(geography_2,
geography_1) = TRUE
+ geography_1
和 geography_2
均为空。
因此,即使两个 GEOGRAPHY
的点或顶点的顺序不同,只要其仍然代表相同的几何结构,二者就可能相等。
限制条件
ST_EQUALS
不保证其为传递函数。
返回类型
BOOL
ST_EXTENT
ST_EXTENT(geography_expression)
说明
返回 STRUCT
,其表示一组输入 GEOGRAPHY
值的边界框。边界框是围绕地理位置的最小矩形。矩形的边由经度和纬度的恒定线组成。
注意事项:
- 如果所有输入均为
NULL
或空地理位置,则返回NULL
。 - 如果允许较小的矩形,则边界框可能会穿过对向子午线。在这种情况下,边界框的其中一个纵向边界超出 [-180, 180] 范围,因此
xmin
小于最东值xmax
。 - 如果边界框的经度 span 大于或等于 180 度,则此函数会返回经度范围为 [-180, 180] 的边界框。
返回类型
STRUCT<xmin FLOAT64, ymin FLOAT64, xmax FLOAT64, ymax FLOAT64>
。
边界框部分:
xmin
:用于限制矩形边界的最西恒定经度线。xmax
:用于限制矩形边界的最东恒定经度线。ymin
:用于限制矩形边界的最短恒定纬度线。ymax
:用于限制矩形边界的最长恒定纬度线。
示例
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
,则返回空地理位置。 - 如果输入不是单个多边形,则返回错误。
使用 SAFE
前缀可为无效输入返回 NULL
,而非错误。
返回类型
- 线串
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。
- 十六进制文本格式的 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 格式的十六进制编码字符串并返回 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
,则该函数会尝试修复不符合开放地理空间信息联盟语义的多边形。
此参数使用具名参数语法,应使用 make_valid => argument_value
语法指定。
BigQuery GEOGRAPHY
具有球面测地边,而 GeoJSON Geometry
对象明确具有平面边。为了在这两种边之间进行转换,BigQuery 会在必要时为线段添加其他点,以使转换后的边序列保持在原始边的 10 米范围内。
如需将 GEOGRAPHY
的格式设置为 GeoJSON,请参阅 ST_ASGEOJSON
。
限制条件
输入存在以下限制条件:
ST_GEOGFROMGEOJSON
只接受 JSON 几何图形片段,不能用于提取整个 JSON 文档。- 输入 JSON 片段必须包含 GeoJSON 几何图形类型,包括
Point
、MultiPoint
、LineString
、MultiLineString
、Polygon
、MultiPolygon
和GeometryCollection
。其他任何 GeoJSON 类型都将导致错误,例如Feature
或FeatureCollection
。 - GeoJSON 几何图形类型的
coordinates
成员的位置信息必须仅包含两个元素。第一个是经度,第二个是纬度。因此,ST_GEOGFROMGEOJSON
不支持coordinates
成员的位置信息包含可选的第三个元素。
返回类型
GEOGRAPHY
ST_GEOGFROMTEXT
Signature 1
ST_GEOGFROMTEXT(wkt_string[, oriented])
说明
返回与输入 WKT 表示形式相对应的 GEOGRAPHY
值。
此函数支持 BOOL
类型的可选参数 oriented
。如果此参数设置为 TRUE
,则由输入构成的多边形按以下方式确定方向:如果按照输入顶点的顺序沿多边形的边界前进,则多边形的内部位于左侧。这使得 WKT 能够表示大于半球的多边形。如果 oriented
为 FALSE
或被省略,则此函数会返回面积较小的多边形。另请参阅 ST_MAKEPOLYGONORIENTED
,此函数与 ST_GEOGFROMTEXT
类似,但 oriented=TRUE
。
如需将 GEOGRAPHY
的格式设置为 WKT,请使用 ST_ASTEXT
。
限制条件
- 所有输入边均假定为球面测地线,而不是平面直线。如需读取平面投影中的数据,请考虑使用
ST_GEOGFROMGEOJSON
。 如需详细了解球面测地线和平面线之间的差异,请参阅坐标系和边。 - 此函数不支持具有
Z
后缀的三维几何图形,也不支持使用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 |
+-------------------+---------------+-----------+
Signature 2
ST_GEOGFROMTEXT(wkt_string[, oriented => boolean_constant_1]
[, planar => boolean_constant_2] [, make_valid => boolean_constant_3])
说明
返回与输入 WKT 表示形式相对应的 GEOGRAPHY
值。
此函数支持三个类型为 BOOL
的可选参数:oriented
、planar
和 make_valid
。此签名使用具名参数语法,应使用 parameter_name => parameter_value
语法以任意顺序指定参数。
如果 oriented
参数设置为 TRUE
,则由输入构成的多边形按以下方式确定方向:如果按照输入顶点的顺序沿多边形的边界前进,则多边形的内部位于左侧。这使得 WKT 能够表示大于半球的多边形。如果 oriented
为 FALSE
或被省略,则此函数会返回面积较小的多边形。另请参阅 ST_MAKEPOLYGONORIENTED
,此函数与 ST_GEOGFROMTEXT
类似,但 oriented=TRUE
。
如果参数 planar
设置为 TRUE
,则假定线字符串和多边形的边使用平面地图语义,而不是 BigQuery 默认的球面测地线语义。如需详细了解球面测地线和平面线之间的差异,请参阅坐标系和边。
如果参数 make_valid
设置为 TRUE
,则该函数会尝试修复不符合开放地理空间信息联盟语义的多边形。
如需将 GEOGRAPHY
的格式设置为 WKT,请使用 ST_ASTEXT
。
限制条件
- 默认情况下,所有输入边均假定为球面测地线,而不是平面直线。如需读取平面投影中的数据,请传递
planar => TRUE
参数,或考虑使用ST_GEOGFROMGEOJSON
。如需详细了解球面测地线和平面线之间的差异,请参阅坐标系和边。 - 此函数不支持具有
Z
后缀的三维几何图形,也不支持使用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 字符串违反了有效多边形的两个属性 - 描述多边形的环路未闭合,并且包含自交。如果设置了 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)
说明
将十六进制文本 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
并返回该 GEOGRAPHY
对象的 GeoHash 表示形式。
geography_expression
:表示GEOGRAPHY
对象。仅支持表示单点的GEOGRAPHY
对象。如果对空GEOGRAPHY
对象使用ST_GEOHASH
,则返回NULL
。maxchars
:该可选的INT64
参数指定哈希可包含的字符数上限。较少的字符对应较低的精确度(换句话说,其边界框较大)。如果未明确指定,则maxchars
默认为 20。有效的maxchars
值为 1 到 20。任何小于或大于该范围的值都会被忽略,并使用默认值 20。
返回类型
STRING
示例
返回西雅图中心的 GeoHash 表示形式,精确度为 10 个字符。
SELECT ST_GEOHASH(ST_GEOGPOINT(-122.35, 47.62), 10) geohash
+--------------+
| geohash |
+--------------+
| c22yzugqw7 |
+--------------+
ST_GEOMETRYTYPE
ST_GEOMETRYTYPE(geography_expression)
说明
返回将输入 GEOGRAPHY
描述为 STRING
的开放地理空间联盟 (OGC) 几何图形类型。OGC 几何图形类型与 WKT 和 GeoJSON 格式中使用的类型相匹配,并输出到 ST_ASTEXT 和 ST_ASGEOJSON。ST_GEOMETRYTYPE
会返回带有“ST_”前缀的 OGC 几何图形类型。
对于输入的类型,ST_GEOMETRYTYPE
返回以下内容:
- 单点地理位置:返回
ST_Point
。 - 仅限点的集合:返回
ST_MultiPoint
。 - 单行字符串地理位置:返回
ST_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
,则返回空数组。 - 如果输入多边形没有孔,则返回空数组。
- 如果输入不是单个多边形,则返回错误。
使用 SAFE
前缀可为无效输入返回 NULL
,而非错误。
返回类型
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)
说明
返回表示两个输入 GEOGRAPHY
的点集的交集的 GEOGRAPHY
。也就是说,交集部分中的每个点均出现在 geography_1
和 geography_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
至少有一个公共点,则此函数返回 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]
度范围内。 - 其中一个经度位于
[-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)
说明
如果点、线串和多边形的总数大于 1,则返回 TRUE
。
空的 GEOGRAPHY
不是集合。
返回类型
BOOL
ST_ISEMPTY
ST_ISEMPTY(geography_expression)
说明
如果给定 GEOGRAPHY
为空,则返回 TRUE
;也就是说,GEOGRAPHY
不包含任何点、线段或多边形。
注意: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
,方法是按输入顺序连接每个输入 GEOGRAPHY
的点或线段顶点。
ST_MAKELINE
有两种变体。对于第一种变体,输入必须是两个 GEOGRAPHY
。对于第二种变体,输入是 GEOGRAPHY
类型的 ARRAY
。在任一变体中,每个输入 GEOGRAPHY
都必须包含以下某个值:
- 一个点。
- 一个线串。
对于 ST_MAKELINE
的第一种变体,如果任一个输入 GEOGRAPHY
为 NULL
,则 ST_MAKELINE
返回 NULL
。对于第二种变体,如果输入 ARRAY
或输入 ARRAY
中的任何元素是 NULL
,则 ST_MAKELINE
返回 NULL
。
限制条件
每条边的跨度必须严格小于 180 度。
注意:BigQuery 的贴靠过程可能会舍弃过短的边并将两个端点贴靠在一起。例如,如果两个输入 GEOGRAPHY
各自包含一个点,并且两个点之间的距离小于贴靠半径,则这两个点将被贴靠在一起。在这种情况下,返回结果为只有一个点的 GEOGRAPHY
。
返回类型
GEOGRAPHY
ST_MAKEPOLYGON
ST_MAKEPOLYGON(geography_expression[, array_of_geography])
说明
创建一个包含由线串输入组成的单个多边形的 GEOGRAPHY
,其中每个输入线串用于构造多边形环。
ST_MAKEPOLYGON
有两种变体。对于第一种变体,输入线串由仅包含一个线串的单个 GEOGRAPHY
提供。对于第二种变体,输入由单个 GEOGRAPHY
和一个 GEOGRAPHY
数组构成,其中每个 GEOGRAPHY 都只包含一个线串。两种变体中的第一个 GEOGRAPHY
用于构造多边形外环。输入 ARRAY
所提供的其他 GEOGRAPHY
则用于指定多边形内环。每个只包含一个线串的输入 GEOGRAPHY
必须满足以下条件:
- 线串必须至少包含三个不同的顶点。
- 线串必须闭合:也就是说,第一个顶点和最后一个顶点必须为同一顶点。如果第一个顶点和最后一个顶点不同,则该函数会为第一个顶点和最后一个顶点构造最后一条边。
对于 ST_MAKEPOLYGON
的第一种变体,如果任一输入 GEOGRAPHY
为 NULL
,则 ST_MAKEPOLYGON
返回 NULL
。对于第二种变体,如果输入 ARRAY
或 ARRAY
中的任何元素是 NULL
,则 ST_MAKEPOLYGON
返回 NULL
。
注意:ST_MAKEPOLYGON
接受空的 GEOGRAPHY
作为输入。ST_MAKEPOLYGON
将空的 GEOGRAPHY
解释为具有空的线串,这将创建一个完整的环:即覆盖整个地球的多边形。
限制条件
输入环必须组成一个有效的多边形:
- 每个多边形内环都必须处于多边形外环内。
- 多边形只能有一个外环(必须是第一个输入环)。这意味着多边形内环不能嵌套。
- 多边形环只能在两个环的边界的顶点处相交。
每条边的跨度必须严格小于 180 度。
每个多边形环会将球面分成两个区域。ST_MAKEPOLYGON
的第一个输入线串构成多边形外环,其内部是两个区域中较小的区域。每个后续输入线串可指定一个多边形内环,它对多边形内部进行了明确的定义。如需定义一个多边形外环,使多边形内部区域是这两个区域中较大的区域,请参阅 ST_MAKEPOLYGONORIENTED
。
注意:BigQuery 的贴靠过程可能会舍弃过短的边并将两个端点贴靠在一起。因此,当顶点贴靠在一起时,特别小的多边形内环可能会消失,或者输出 GEOGRAPHY
可能只包含一条线段或一个点。
返回类型
GEOGRAPHY
ST_MAKEPOLYGONORIENTED
ST_MAKEPOLYGONORIENTED(array_of_geography)
说明
与 ST_MAKEPOLYGON
大体一样,但每个输入线串的顶点顺序决定了每个多边形环的方向。多边形环的方向按如下方式定义多边形的内部:如果按照输入顶点的顺序沿多边形的边界前进,则多边形的内部位于左侧。这适用于每个给定的多边形环。
作为多边形构造函数的变体,ST_MAKEPOLYGONORIENTED
更加灵活,因为它能够构造一个内部区域可位于环的任意一侧的多边形。然而,多边形环的正确方向对于构造所需的多边形至关重要。
如果输入 ARRAY
或 ARRAY
中的任何元素是 NULL
,则 ST_MAKEPOLYGONORIENTED
返回 NULL
。
注意:ST_MAKEPOLYGONORIENTED
的输入参数可能包含空的 GEOGRAPHY
。ST_MAKEPOLYGONORIENTED
将空的 GEOGRAPHY
解释为具有空线串,这将创建一个完整的环,即覆盖整个地球的多边形。
限制条件
输入环必须组成一个有效的多边形:
- 每个多边形内环都必须处于多边形外环内。
- 多边形只能有一个外环(必须是第一个输入环)。这意味着多边形内环不能嵌套。
- 多边形环只能在两个环的边界的顶点处相交。
每条边的跨度必须严格小于 180 度。
ST_MAKEPOLYGONORIENTED
根据每个线串的输入顶点的顺序来确定多边形的方向。这适用于多边形外环和任意内环。ST_MAKEPOLYGONORIENTED
构建的多边形的所有内环均与外环方向相反。如需了解其他多边形构造函数以及构建有效多边形的其他限制条件,请参阅 ST_MAKEPOLYGON
。
注意:BigQuery 的贴靠过程可能会舍弃长度过短的边并将两个端点贴靠在一起,使其成为一个点。因此,线串中的顶点可能会被贴靠在一起,造成一条或多条边消失。因此,特别小的多边形内环可能会消失,或者输出 GEOGRAPHY
可能只包含一条线段或一个点。
返回类型
GEOGRAPHY
ST_MAXDISTANCE
ST_MAXDISTANCE(geography_1, geography_2[, use_spheroid])
返回两个非空 GEOGRAPHY
之间的最长距离(以米为单位);也就是返回第一个 GEOGRAPHY
中的一个顶点和第二个 GEOGRAPHY
中的一个顶点之间的距离。如果 geography_1
和 geography_2
是同一个 GEOGRAPHY
,则此函数返回这个 GEOGRAPHY
中最远的两个顶点之间的距离。
如果任一输入 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
中的几何图形数。对于单点、线串或多边形,ST_NUMGEOMETRIES
会返回 1
。对于任何几何图形集合,ST_NUMGEOMETRIES
都会返回构成集合的几何图形数量。如果输入为空 GEOGRAPHY
,ST_NUMGEOMETRIES
将返回 0
。
返回类型
INT64
示例
以下示例会计算单点地理位置、两个集合和空地理位置的 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
的顶点数。这包括点的数量、线串顶点的数量以及多边形顶点的数量。
注意:多边形环的第一个顶点和最后一个顶点按不同顶点计算。
返回类型
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)
说明
以点地理位置形式返回线串地理位置的第 N 个点,其中 N 是索引。索引从 1 开始。负值从线串末尾反向计数,因此 -1 是最后一个点。如果输入不是线串、输入为空或者给定索引中没有顶点,则会返回错误。使用 SAFE
前缀可获取 NULL
,表示无效输入而非错误。
返回类型
点 GEOGRAPHY
示例
以下示例使用 ST_POINTN
、ST_STARTPOINT
和 ST_ENDPOINT
从线串中提取点。
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
。输入 geography
的变化幅度不会超过 tolerance_meters
指定的容限。因此,经过简化的边一定会在从该边移除的所有顶点的原始位置的 tolerance_meters
内传递。给定 tolerance_meters
为地球表面以米为单位的距离。
请注意,ST_SIMPLIFY
会保留拓扑关系,这意味着将不会创建新的交叉边,并且输出将是有效的。如需获得足够大的容限,可以将相邻的形状合拢为单个对象,或者将形状简化为维度较小的形状。
限制条件
要使 ST_SIMPLIFY
发挥作用,tolerance_meters
必须为非零值。
如果 tolerance_meters
指定的容限为以下值之一,则 ST_SIMPLIFY
将返回错误:
- 负容限。
- 大于约 7800 公里。
返回类型
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)
说明
返回线串地理位置的第一个点作为点地理位置。如果输入不是线串或输入为空,则会返回错误。使用 SAFE
前缀可获取 NULL
,表示无效输入而非错误。
返回类型
点 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)
说明
如果满足以下两个条件,则返回 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
有两种变体。对于第一种变体,输入必须是两个 GEOGRAPHY
。对于第二种变体,输入是 GEOGRAPHY
类型的 ARRAY
。
对于 ST_UNION
的第一种变体,如果输入 GEOGRAPHY
为 NULL
,则 ST_UNION
返回 NULL
。对于第二种变体,如果输入 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
,ST_WITHIN(a, b)
会返回与 ST_CONTAINS
(b, a)
相同的结果。注意参数的顺序相反。
返回类型
BOOL
ST_X
ST_X(geography_expression)
说明
返回单点输入 GEOGRAPHY
的经度,以度为单位。
对于任何并非单点的输入 GEOGRAPHY
(包括空的 GEOGRAPHY
),ST_X
会返回一个错误。使用 SAFE.
前缀获取 NULL
。
返回类型
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
会返回一个错误。使用 SAFE.
前缀可返回 NULL
。
返回类型
FLOAT64
示例
如需查看使用示例,请参阅 ST_X
。