标准 SQL 中的地理函数

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

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

类别

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

类别	函数	说明
构造函数	ST_GEOGPOINT ST_MAKELINE ST_MAKEPOLYGON ST_MAKEPOLYGONORIENTED	根据坐标或现有地理位置构建新的地理位置值的函数。
解析器	ST_GEOGFROMGEOJSON ST_GEOGFROMTEXT ST_GEOGFROMWKB ST_GEOGPOINTFROMGEOHASH	按照外部格式（例如 WKT 和 GeoJSON）创建地理位置的函数。
格式设置函数	ST_ASBINARY ST_ASGEOJSON ST_ASTEXT ST_GEOHASH	将地理位置导出为外部格式（例如 WKT）的函数。
转换	ST_BOUNDARY ST_CENTROID ST_CENTROID_AGG（聚合函数） ST_CLOSESTPOINT ST_CONVEXHULL ST_DIFFERENCE ST_DUMP ST_INTERSECTION ST_SIMPLIFY ST_SNAPTOGRID ST_UNION ST_UNION_AGG（聚合函数）	根据输入生成新地理位置的函数。
访问函数	ST_DIMENSION ST_DUMP ST_ISCOLLECTION ST_ISEMPTY ST_NUMPOINTS 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_AREA ST_DISTANCE ST_LENGTH ST_MAXDISTANCE ST_PERIMETER	计算一个或多个地理位置计量结果的函数。
聚簇	ST_CLUSTERDBSCAN	针对地理位置执行聚簇的函数。

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_BOUNDARY

ST_BOUNDARY(geography_expression)

说明

返回一个 GEOGRAPHY，其中包含给定输入 GEOGRAPHY 中每个组成部分边界的并集。

GEOGRAPHY 的每个组成部分边界的定义如下：

• 点的边界为空。
• 线串的边界由线串的端点组成。
• 多边形的边界由构成多边形外环及其所有内环的线串组成。

返回类型

GEOGRAPHY

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 会忽略输入 GEOGRAPHY 中的 NULL 值。

如需查看 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 (...)

对地理位置列执行 DBSCAN 聚类。返回从 0 开始的集群编号。

输入参数

• geography_column：聚簇的 GEOGRAPHY 列。
• epsilon：指定半径的 Epsilon（以米为单位），用于测量距离核心的值。非负 FLOAT64 值。
• minimum_geographies：指定单个集群中地理位置数量下限。只有密集输入才能形成一个集群，否则会被分类为噪声。非负 INT64 值。

• OVER：指定一个窗口。请参阅分析函数。OVER 子句与 ST_CLUSTERDBSCAN 的使用与以下内容兼容：

  • PARTITION BY：可选。
  • ORDER BY：可选。
  • window_frame_clause：禁止。

地理位置类型和 DBSCAN 算法

DBSCAN 算法可识别高密度数据簇，并在低密度噪声区域中标记离群值。可通过 DBSCAN 算法以下述三种方式之一对从 geography_column 传入的地理位置进行分类：

• 核心值：如果地理位置在 minimum_geographies 地理位置的 epsilon 距离范围内（包括自身本身），则该地理位置为核心值。核心值将启动新集群，或作为核心值添加到在 epsilon 距离范围内的相同集群。核心值以及 epsilon 距离范围内的其他所有核心和边界值划分到同一个集群组。
• 边界值：如果地理位置位于核心值的 epsilon 距离范围内，则地理位置是边界值。该节点将作为核心值添加到 epsilon 距离范围内的相同集群。边界值可以位于多个集群的 epsilon 距离范围内。在这种情况下，可以随意为任一集群分配该函数，且该函数会在后续调用中产生相同的结果。
• 噪声：如果既不是核心值，也不是边界值，则地理位置为噪声。噪声值会分配给 NULL 集群。空 GEOGRAPHY 始终归类为噪音。

限制条件

• 参数 minimum_geographies 是非负 INT64，epsilon 是非负 FLOAT64。
• EMPTY 地理位置对象无法加入任何集群。
• 可对边界值进行多次聚类分配。如果地理位置是边界值，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。

如果 geometry_1 完全包含在 geometry_2 内，则 ST_DIFFERENCE 会返回空的 GEOGRAPHY。

限制条件

BigQuery GEOGRAPHY 表示的基础几何图形对象对应于点集的闭集。因此，ST_DIFFERENCE 是 geography_1 和 geography_2 的点集差异的闭集。这意味着，如果 geography_1 和 geography_2 相交，则其点集差异可能包含 geography_2 的边界的一部分。

返回类型

GEOGRAPHY

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

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, 0 2, 0 0))，结果同时包含非定向多边形和定向多边形，然后检查每个结果是否包含点 (1, 1)。

WITH polygon AS (SELECT 'Polygon((0 0, 0 2, 2 2, 2 0, 0 0))' AS p)
SELECT
  ST_CONTAINS(ST_GEOGFROMTEXT(p), ST_GEOGPOINT(1, 1)) AS fromtext_default,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, FALSE), ST_GEOGPOINT(1, 1)) AS non_oriented,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, TRUE),  ST_GEOGPOINT(1, 1)) AS oriented
FROM polygon;

+-------------------+---------------+-----------+
| fromtext_default  | non_oriented  | oriented  |
+-------------------+---------------+-----------+
| true              | true          | false     |
+-------------------+---------------+-----------+

ST_GEOGFROMWKB

ST_GEOGFROMWKB(wkb_bytes)

说明

返回与输入 WKB 表示形式相对应的 GEOGRAPHY 值。

如需将 GEOGRAPHY 的格式设置为 WKB，请使用 ST_ASBINARY。

限制条件

所有输入边均假定为球面测地线，而不是平面直线。如需读取平面投影中的数据，请考虑使用 ST_GEOGFROMGEOJSON。

返回类型

GEOGRAPHY

ST_GEOGPOINT

ST_GEOGPOINT(longitude, latitude)

说明

创建包含一个点的 GEOGRAPHY。ST_GEOGPOINT 根据指定的 FLOAT64 格式的经度和纬度参数创建一个点，并通过 GEOGRAPHY 值返回该点。

限制条件

• 纬度必须在 [-90, 90] 范围内。如果纬度超出此范围，将导致错误。
• 允许超出 [-180,180] 范围的经度；ST_GEOGPOINT 使用输入经度对 360 取模的余数来获得 [-180, 180] 范围内的经度。

返回类型

GEOGRAPHY

ST_GEOGPOINTFROMGEOHASH

ST_GEOGPOINTFROMGEOHASH(geohash)

说明

返回与 GeoHash 中定义的边界框的中间点对应的 GEOGRAPHY 值。

返回类型

GEOGRAPHY

ST_GEOHASH

ST_GEOHASH(geography_expression, maxchars)

说明

返回 geography_expression 的 GeoHash 表示形式。生成的 GeoHash 最多包含 maxchars 个字符。较少的字符对应较低的精确度（换句话说，其边界框较大）。

ST_GeoHash 会为空的 GEOGRAPHY 对象返回 NULL。

限制条件

• 仅支持表示一个点的 GEOGRAPHY 对象。
• maxchars 的最大值为 20。

示例

返回西雅图中心的 GeoHash 表示形式，精确度为 10 个字符。

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

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

返回类型

STRING

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] 度范围内。

返回类型

BOOL

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_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_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_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 会忽略输入 GEOGRAPHY 中的 NULL 值。

如需查看 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。