地理函数

地理位置函数用于生成 BigQuery GEOGRAPHY 值或对其进行操作。任何地理函数的签名均以 ST_ 开头。BigQuery 支持以下函数，这些函数可用于分析地理数据、确定地貌之间的空间关系，以及构造或操作 GEOGRAPHY。

如果任何输入参数为 NULL，则所有 BigQuery 地理函数均返回 NULL。

类别

地理函数根据其行为分为以下类别：

类别	函数	说明
构造函数	ST_GEOGPOINT ST_MAKELINE ST_MAKEPOLYGON ST_MAKEPOLYGONORIENTED	根据坐标或现有地理位置构建新的地理位置值的函数。
解析器	ST_GEOGFROM ST_GEOGFROMGEOJSON ST_GEOGFROMTEXT ST_GEOGFROMWKB ST_GEOGPOINTFROMGEOHASH	按照外部格式（例如 WKT 和 GeoJSON）创建地理位置的函数。
格式设置函数	ST_ASBINARY ST_ASGEOJSON ST_ASTEXT ST_GEOHASH	将地理位置导出为外部格式（例如 WKT）的函数。
转换	ST_BOUNDARY ST_BUFFER ST_BUFFERWITHTOLERANCE ST_CENTROID ST_CENTROID_AGG（聚合函数） ST_CLOSESTPOINT ST_CONVEXHULL ST_DIFFERENCE ST_DUMP ST_EXTERIORRING ST_INTERIORRINGS ST_INTERSECTION ST_SIMPLIFY ST_SNAPTOGRID ST_UNION ST_UNION_AGG（聚合函数）	根据输入生成新地理位置的函数。
访问函数	ST_DIMENSION ST_DUMP ST_ENDPOINT ST_GEOMETRYTYPE ST_ISCOLLECTION ST_ISEMPTY ST_NPOINTS ST_NUMGEOMETRIES ST_NUMPOINTS ST_POINTN ST_STARTPOINT ST_X ST_Y	提供对地理位置属性的访问权限并且无负面影响的函数。
谓词	ST_CONTAINS ST_COVEREDBY ST_COVERS ST_DISJOINT ST_DWITHIN ST_EQUALS ST_INTERSECTS ST_INTERSECTSBOX ST_TOUCHES ST_WITHIN	针对两个地理位置之间的某种空间关系或地理位置的某个属性返回 TRUE 或 FALSE 的函数。这种函数通常用于过滤条件子句。
量度	ST_ANGLE ST_AREA ST_AZIMUTH ST_BOUNDINGBOX ST_DISTANCE ST_EXTENT（聚合函数） ST_LENGTH ST_MAXDISTANCE ST_PERIMETER	计算一个或多个地理位置计量结果的函数。
聚簇	ST_CLUSTERDBSCAN	针对地理位置执行聚簇的函数。
S2 函数	S2_CELLIDFROMPOINT S2_COVERINGCELLIDS	用于处理 GEOGRAPHY 的 S2 单元覆盖的函数。

S2_CELLIDFROMPOINT

S2_CELLIDFROMPOINT(point_geography[, level => cell_level])

说明

返回覆盖点 GEOGRAPHY 的 S2 单元 ID。

• 可选的 INT64 参数 level 指定返回单元的 S2 单元级别。为此参数命名是可选操作。

这是与利用 S2 几何图形库的系统互操作性的高级功能。

限制条件

• 以有符号 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

预览

本产品或功能受《Google Cloud Platform 服务条款》的正式发布前产品条款约束。对正式发布前产品和功能的支持可能有限，并且对正式发布前产品和功能的变更可能不兼容其他正式发布前版本。如需了解详情，请参阅发布阶段说明。

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

预览

本产品或功能受《Google Cloud Platform 服务条款》的正式发布前产品条款约束。对正式发布前产品和功能的支持可能有限，并且对正式发布前产品和功能的变更可能不兼容其他正式发布前版本。如需了解详情，请参阅发布阶段说明。

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
• Signature 2

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：

1. geography_1 与 geography_2 相交。
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。