标准 SQL 中的地理函数

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

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

构造函数：通过坐标或现有的 GEOGRAPHY 来构建新的 GEOGRAPHY 值的函数，例如 ST_GEOGPOINT。
解析函数：从外部格式（如 WKT 和 GeoJSON）创建 GEOGRAPHY 的函数。例如，ST_GEOGFROMTEXT 从 WKT 创建 GEOGRAPHY。
格式化函数：将 GEOGRAPHY 导出为外部格式（如 WKT 和 GeoJSON）的函数。例如，ST_ASTEXT 将 GEOGRAPHY 格式化为 WKT。
转换函数：通过符合某些属性的 GEOGRAPHY 生成新的 GEOGRAPHY 的函数。例如 ST_INTERSECTION 和 ST_BOUNDARY。
谓词函数：针对两个 GEOGRAPHY 之间的空间关系或一个 GEOGRAPHY 的某些属性返回 TRUE 或 FALSE 的函数。这种函数通常用于过滤条件子句。例如，ST_DWITHIN 是一个谓词函数。
访问器函数：提供对 GEOGRAPHY 属性的访问权限并且无负面影响的函数，如 ST_NUMPOINTS。
计算函数：计算一个或多个 GEOGRAPHY 的测量值的函数，例如 ST_DISTANCE。
聚合函数：特定于地理位置的聚合函数，例如 ST_UNION_AGG。

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

ST_GEOGPOINT

ST_GEOGPOINT(longitude, latitude)

说明

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

限制条件

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

返回类型

GEOGRAPHY

ST_MAKELINE

ST_MAKELINE(geography_1, geography_2)

ST_MAKELINE(array_of_geography)

说明

通过单个线串（表示一系列点和连接这些点的线段）创建 GEOGRAPHY，方法是按输入顺序连接每个输入 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)

ST_MAKEPOLYGON(geography_expression, array_of_geography)

说明

创建一个包含由线串输入组成的单个多边形的 GEOGRAPHY，其中每个输入线串用于构造多边形的环。

ST_MAKEPOLYOGN 有两种变体。对于第一种变体，输入线串由仅包含一个线串的单个 GEOGRAPHY 提供。对于第二种变体，输入由单个 GEOGRAPHY 和一个 GEOGRAPHY 数组构成，其中每个 GEOGRAPHY 都包含一个线串。两种变体中的第一个 GEOGRAPHY 始终用于构造多边形的外环。输入 ARRAY 所提供的其他 GEOGRAPHY 则用于指定多边形内环。每个只包含一个线串的输入 GEOGRAPHY 必须满足以下条件：

线串必须至少包含三个不同的顶点。
线串必须闭合：也就是说，第一个顶点和最后一个顶点必须为同一顶点。如果第一个顶点和最后一个顶点不同，则该函数会为第一个顶点和最后一个顶点构造最后一条边。

对于 ST_MAKEPOLYGON 的第一种变体，如果任一输入 GEOGRAPHY 为 NULL，则 ST_MAKEPOLYOGN 返回 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_GEOGFROMGEOJSON

ST_GEOGFROMGEOJSON(geojson_string)

说明

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

ST_GEOGFROMGEOJSON 接受遵循 RFC 7946 的输入。

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)

ST_GEOGFROMTEXT(wkt_string, oriented)

说明

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

此函数支持为 oriented 设置 BOOL 类型的可选参数。如果此参数设置为 TRUE，则由输入构成的多边形按以下方式确定方向：如果按照输入顶点的顺序沿多边形的边界前进，则多边形的内部位于左侧。这使得 WKT 能够表示大于半球的多边形。如果 oriented 为 FALSE 或省略，则此函数返回面积较小的多边形。另请参阅 ST_MAKEPOLYGONORIENTED，此函数与 ST_GEOGFROMTEXT 类似，但 oriented=TRUE。

如需将 GEOGRAPHY 格式化为 WKT，请使用 ST_ASTEXT。

限制条件

所有输入边均假定为球面测地线，而不是平面直线。如需读取平面投影中的数据，请考虑使用 ST_GEOGFROMGEOJSON。如需详细了解球面测地线和平面线之间的差异，请参阅坐标系和边。

返回类型

GEOGRAPHY

示例

以下查询读取 WKT 字符串 POLYGON((0 0, 0 2, 2 2, 0 2, 0 0))，结果同时包含非定向多边形和定向多边形，然后检查每个结果是否包含点 (1, 1)。

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

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

ST_GEOGFROMWKB

ST_GEOGFROMWKB(wkb_bytes)

说明

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

如需将 GEOGRAPHY 格式化为 WKB，请使用 ST_ASBINARY。

限制条件

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

返回类型

GEOGRAPHY

ST_GEOGPOINTFROMGEOHASH

ST_STGEOGPOINTFROMGEOHASH(geohash)

说明

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

返回类型

GEOGRAPHY

ST_ASGEOJSON

ST_ASGEOJSON(geography_expression)

说明

为输入 GEOGRAPHY 返回遵循 RFC 7946 的 GeoJSON 表示形式。

如需根据 GeoJSON 信息构造一个 GEOGRAPHY，请参阅 ST_GEOGFROMGEOJSON。

返回类型

STRING

ST_ASTEXT

ST_ASTEXT(geography_expression)

说明

返回输入 GEOGRAPHY 的WKT表示形式。

如需根据 WKT 信息构造一个 GEOGRAPHY，请参阅 ST_GEOGFROMTEXT。

返回类型

STRING

ST_GEOHASH

ST_GEOHASH(geography_expression, maxchars)

说明

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

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

限制条件

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

示例

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

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

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

返回类型

STRING

ST_ASBINARY

ST_ASBINARY(geography_expression)

说明

返回输入 GEOGRAPHY 的 WKB 表示形式。

如需根据 WKB 信息构造一个 GEOGRAPHY，请参阅 ST_GEOGFROMWKB。

返回类型

BYTES

ST_BOUNDARY

ST_BOUNDARY(geography_expression)

说明

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

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

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

返回类型

GEOGRAPHY

ST_CENTROID

ST_CENTROID(geography_expression)

说明

以单点 GEOGRAPHY 的形式返回输入 GEOGRAPHY 的形心。

GEOGRAPHY 的形心表示 GEOGRAPHY 的最高维组成部分的形心的加权平均值。每个维度组成部分的形心具有如下定义：

点的形心是输入坐标的算术平均值。
线串的形心是所有边按长度加权的形心。每条边的形心是其测地线中点。
多边形的形心是其质心。

如果输入 GEOGRAPHY 为空，则返回空的 GEOGRAPHY。

限制条件

如果 GEOGRAPHY 的形心无法由地球表面上的某个点定义，则返回具备确定性的任意点。只有当形心恰好位于地球中心时才会发生这种情况，例如一对对映点的形心，这种可能性非常小。

返回类型

GEOGRAPHY

ST_CLOSESTPOINT

ST_CLOSESTPOINT(geography_1, geography_2)

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_DIFFERENCE

ST_DIFFERENCE(geography_1, geography_2)

说明

返回表示 geography_1 和 geography_2 的点集差异的 GEOGRAPHY。

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

限制条件

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

返回类型

GEOGRAPHY

ST_INTERSECTION

ST_INTERSECTION(geography_1, geography_2)

说明

返回表示两个输入 GEOGRAPHY 的点集的交集的 GEOGRAPHY。也就是说，交集部分中的每个点均出现在 geography_1 和 geography_2 中。

如果两个输入 GEOGRAPHY 不相交，即输入 geometry_1 和 geometry_2 不存在公共点，则返回空的 GEOGRAPHY。

如需了解相关的谓词函数，请参阅 ST_INTERSECTS 和 ST_DISJOINT。

返回类型

GEOGRAPHY

ST_SNAPTOGRID

ST_SNAPTOGRID(geography_expression, grid_size)

说明

返回输入 GEOGRAPHY，其中每个顶点均已贴靠到经度/纬度网格。网格大小由 grid_size 参数确定，此参数以度为单位。

限制条件

不支持任意的网格大小。grid_size 参数采用四舍五入来计算，因此其格式为 \(10^n\)，其中 \(-10 < n < 0\)。

返回类型

GEOGRAPHY

ST_UNION

ST_UNION(geography_1, geography_2)

ST_UNION(array_of_geography)

说明

返回表示所有输入 GEOGRAPHY 的点集的并集的 GEOGRAPHY。

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

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

ST_DISJOINT(geography_1, geography_2)

说明

如果 geography_1 和 geography_2 的交集为空，则返回 TRUE，也就是说，geography_1 中没有同时位于 geography_2 中的点。

ST_DISJOINT 是 ST_INTERSECTS 在逻辑上的否定。

返回类型

GEOGRAPHY

ST_DWITHIN

ST_DWITHIN(geography_1, geography_2), distance)

ST_DWITHIN(geography_1, geography_2, distance, use_spheroid)

说明

如果 geography_1 中至少有一个点与 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 代表相同的 GEOGRAPHY 值，则返回 TRUE。更确切地说，这意味着必须满足以下条件之一：

ST_COVERS(geography_1, geography_2) = TRUE 且 ST_COVERS(geography_2, geography_1) = TRUE
geography_1 和 geography_2 均为空。

因此，即使两个 GEOGRAPHY 的点或顶点的顺序不同，只要其仍然代表相同的几何结构，二者就可能相等。

限制条件

ST_EQUALS 不保证其为传递函数。

返回类型

BOOL

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_TOUCHES

ST_TOUCHES(geography_1, geography_2)

说明

如果满足以下两个条件，则返回 TRUE：

geography_1 与 geography_2 相交。
geography_1 的内部和 geography_2 的内部不相交。

返回类型

BOOL

ST_WITHIN

ST_WITHIN(geography_1, geography_2)

说明

如果 geography_1 中没有位于 geography_2 外部的点，且 geography_1 和 geography_2 的内部相交，则返回 TRUE。

给定两个地理位置 a 和 b，ST_WITHIN(a, b) 会返回与 ST_CONTAINS(b, a) 相同的结果。注意参数的顺序相反。

返回类型

BOOL

ST_ISEMPTY

ST_ISEMPTY(geography_expression)

说明

如果给定 GEOGRAPHY 为空，则返回 TRUE；也就是说，GEOGRAPHY 不包含任何点、线段或多边形。

注意：BigQuery 中的空 GEOGRAPHY 与特定的几何形状无关。例如，表达式 ST_GEOGFROMTEXT('POINT EMPTY') 和 ST_GEOGFROMTEXT('GEOMETRYCOLLECTION EMPTY') 的返回结果是相同的。

返回类型

BOOL

ST_ISCOLLECTION

ST_ISCOLLECTION(geography_expression)

说明

如果点、线串和多边形的总数大于 1，则返回 TRUE。

空的 GEOGRAPHY 不是集合。

返回类型

BOOL

ST_DIMENSION

ST_DIMENSION(geography_expression)

说明

返回输入 GEOGRAPHY 中最高维元素的维度。

每个可能元素的维度如下：

点的维度为 0。
线串的维度为 1。
多边形的维度为 2。

如果输入 GEOGRAPHY 为空，则 ST_DIMENSION 返回 -1。

返回类型

INT64

ST_NUMPOINTS

ST_NUMPOINTS(geography_expression)

说明

返回输入 GEOGRAPHY 的顶点数。这包括点的数量、线串顶点的数量以及多边形顶点的数量。

注意：多边形环的第一个顶点和最后一个顶点按不同顶点计算。

返回类型

INT64

ST_AREA

ST_AREA(geography_expression)

ST_AREA(geography_expression, use_spheroid)

说明

返回输入 GEOGRAPHY 中的多边形覆盖的面积（以平方米为单位）。

如果 geography_expression 是一个点或一条线段，则返回零。如果 geography_expression 是一个集合，则返回集合中多边形覆盖的面积；如果此集合不包含多边形，则返回零。

可选的 use_spheroid 参数用于确定此函数计算距离的方式。如果 use_spheroid 为 FALSE，则此函数计算完美球面上的距离。

use_spheroid 参数目前仅支持值 FALSE。use_spheroid 的默认值为 FALSE。

返回类型

FLOAT64

ST_DISTANCE

ST_DISTANCE(geography_1, geography_2)

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_LENGTH

ST_LENGTH(geography_expression)

ST_LENGTH(geography_expression, use_spheroid)

说明

返回输入 GEOGRAPHY 中线段的总长度（以米为单位）。

如果 geography_expression 是点或多边形，则返回零。如果 geography_expression 是一个集合，则返回集合中线段的长度；如果此集合不包含线段，则返回零。

可选的 use_spheroid 参数用于确定此函数计算距离的方式。如果 use_spheroid 为 FALSE，则此函数计算完美球面上的距离。

use_spheroid 参数目前仅支持值 FALSE。use_spheroid 的默认值为 FALSE。

返回类型

FLOAT64

ST_MAXDISTANCE

ST_MAXDISTANCE(geography_1, geography_2)

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_PERIMETER

ST_PERIMETER(geography_expression)

ST_PERIMETER(geography_expression, use_spheroid)

说明

返回输入 GEOGRAPHY 中的多边形的边界长度（以米为单位）。

如果 geography_expression 是一个点或一条线段，则返回零。如果 geography_expression 是一个集合，则返回集合中多边形的周长；如果此集合不包含多边形，则返回零。

可选的 use_spheroid 参数用于确定此函数计算距离的方式。如果 use_spheroid 为 FALSE，则此函数计算完美球面上的距离。

use_spheroid 参数目前仅支持值 FALSE。use_spheroid 的默认值为 FALSE。

返回类型

FLOAT64

ST_UNION_AGG

ST_UNION_AGG(geography)

说明

返回表示所有输入 GEOGRAPHY 的点集的并集的 GEOGRAPHY。

ST_UNION_AGG 会忽略输入 GEOGRAPHY 的 NULL 值。

如需查看 ST_UNION_AGG 的非聚合版本，请参阅 ST_UNION。

返回类型

GEOGRAPHY

ST_CENTROID_AGG

ST_CENTROID_AGG(geography)

说明

计算一组输入 GEOGRAPHY 的形心，并返回单点 GEOGRAPHY。

一组输入 GEOGRAPHY 的形心表示每个单独 GEOGRAPHY 的形心的加权平均值。在一组输入中，只有具有最高维度的 GEOGRAPHY 会影响整组输入的形心。例如，如果输入中包括含有线段的 GEOGRAPHY 和仅含有点的 GEOGRAPHY，则 ST_CENTROID_AGG 会返回含有线段的 GEOGRAPHY 的加权平均值，因为它们具有最高维度。在此示例中，ST_CENTROID_AGG 在计算聚合形心时忽略仅含有点的 GEOGRAPHY。

ST_CENTROID_AGG 会忽略输入 GEOGRAPHY 的 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_GEOGPOINT

ST_MAKELINE

ST_MAKEPOLYGON

ST_MAKEPOLYGONORIENTED

ST_GEOGFROMGEOJSON

ST_GEOGFROMTEXT

ST_GEOGFROMWKB

ST_GEOGPOINTFROMGEOHASH

ST_ASGEOJSON

ST_ASTEXT

ST_GEOHASH

ST_ASBINARY

ST_BOUNDARY

ST_CENTROID

ST_CLOSESTPOINT

ST_DIFFERENCE

ST_INTERSECTION

ST_SNAPTOGRID

ST_UNION

ST_X

ST_Y

ST_CONTAINS

ST_COVEREDBY

ST_COVERS

ST_DISJOINT

ST_DWITHIN

ST_EQUALS

ST_INTERSECTS

ST_INTERSECTSBOX

ST_TOUCHES

ST_WITHIN

ST_ISEMPTY

ST_ISCOLLECTION

ST_DIMENSION

ST_NUMPOINTS

ST_AREA

ST_DISTANCE

ST_LENGTH

ST_MAXDISTANCE

ST_PERIMETER

ST_UNION_AGG

ST_CENTROID_AGG

发送以下问题的反馈：