标准 SQL 中的地理函数

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

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

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

ST_GEOGPOINT

ST_GEOGPOINT(longitude, latitude)

说明

创建包含一个点的 GEOGRAPHYST_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 的第一种变体,如果输入 GEOGRAPHYNULL,则 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 的第一种变体,如果任一输入 GEOGRAPHYNULL,则 ST_MAKEPOLYOGN 返回 NULL。对于第二种变体,如果输入 ARRAYARRAY 中的任何元素是 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 更加灵活,因为它能够构造一个内部区域可位于环的任意一侧的多边形。总之,多边形环的正确方向对于构造所需的多边形而言至关重要。

如果输入 ARRAYARRAY 中的任何元素是 NULL,则 ST_MAKEPOLYGONORIENTED 返回 NULL

注意:ST_MAKEPOLYGONORIENTED 的输入参数可能包含空的 GEOGRAPHYST_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 几何图形类型,包括 PointMultiPointLineStringMultiLineStringPolygonMultiPolygonGeometryCollection。其他任何 GeoJSON 类型都将导致出错,例如 FeatureFeatureCollection
  • GeoJSON 几何图形类型的 coordinates 成员的位置信息必须由两个元素组成。第一个是经度,第二个是纬度。因此,ST_GEOGFROMGEOJSON 不支持 coordinates 成员的位置信息包含可选的第三个元素。

返回类型

GEOGRAPHY

ST_GEOGFROMTEXT

ST_GEOGFROMTEXT(wkt_string)
ST_GEOGFROMTEXT(wkt_string, oriented)

说明

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

此函数支持为 oriented 设置 BOOL 类型的可选参数。如果此参数设置为 TRUE,则由输入构成的多边形按以下方式确定方向:如果按照输入顶点的顺序沿多边形的边界前进,则多边形的内部位于左侧。这使得 WKT 能够表示大于半球的多边形。如果 orientedFALSE 或省略,则此函数返回面积较小的多边形。另请参阅 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 7946GeoJSON 表示形式。

BigQuery GEOGRAPHY 具有球面测地边,而 GeoJSON Geometry 对象明确具有平面边。为了在这两种边之间进行转换,BigQuery 会在必要时为线段添加其他点,以使转换后的边序列保持在原始边的 10 米范围内。

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

返回类型

STRING

ST_ASTEXT

ST_ASTEXT(geography_expression)

说明

返回输入 GEOGRAPHYWKT表示形式。

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

返回类型

STRING

ST_GEOHASH

ST_GEOHASH(geography_expression, maxchars)

说明

返回 geography_expressionGeoHash 表示形式。生成的 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)

说明

返回输入 GEOGRAPHYWKB 表示形式。

如需根据 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_spheroidFALSE,则此函数计算完美球面上的距离。

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

返回类型

GEOGRAPHY

ST_DIFFERENCE

ST_DIFFERENCE(geography_1, geography_2)

说明

返回表示 geography_1geography_2 的点集差异的 GEOGRAPHY

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

限制条件

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

返回类型

GEOGRAPHY

ST_INTERSECTION

ST_INTERSECTION(geography_1, geography_2)

说明

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

如果两个输入 GEOGRAPHY 不相交,即输入 geometry_1geometry_2 不存在公共点,则返回空的 GEOGRAPHY

如需了解相关的谓词函数,请参阅 ST_INTERSECTSST_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 的第一种变体,如果输入 GEOGRAPHYNULL,则 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,包括空的 GEOGRAPHYST_X 会返回一个错误。使用 SAFE. 前缀时,此函数返回 NULL

返回类型

FLOAT64

示例

以下示例使用 ST_XST_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,包括空的 GEOGRAPHYST_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_1geography_2 为空,则返回 FALSE。如果 geography_1 中没有位于 geography_2 外部的点,则返回 TRUE

给定两个 GEOGRAPHYabST_COVEREDBY(a, b) 会返回与 ST_COVERS(b, a) 相同的结果。注意参数的顺序相反。

返回类型

BOOL

ST_COVERS

ST_COVERS(geography_1, geography_2)

说明

如果 geography_1geography_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_1geography_2 的交集为空,则返回 TRUE,也就是说,geography_1 中没有同时位于 geography_2 中的点。

ST_DISJOINTST_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_spheroidFALSE,则此函数计算完美球面上的距离。

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

返回类型

BOOL

ST_EQUALS

ST_EQUALS(geography_1, geography_2)

说明

如果 geography_1geography_2 代表相同的 GEOGRAPHY 值,则返回 TRUE。更确切地说,这意味着必须满足以下条件之一:

  • ST_COVERS(geography_1, geography_2) = TRUEST_COVERS(geography_2, geography_1) = TRUE
  • geography_1geography_2 均为空。

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

限制条件

ST_EQUALS 不保证其为传递函数。

返回类型

BOOL

ST_INTERSECTS

ST_INTERSECTS(geography_1, geography_2)

说明

如果 geography_1geography_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。矩形的边由经度和纬度的恒定线组成。lng1lng2 指定矩形边界的最小和最大经度线,lat1lat2 指定矩形边界的最小和最大恒定纬度线。

指定所有经度和纬度参数时,以度为单位。

限制条件

输入参数存在以下限制条件:

  • 纬度应在 [-90, 90] 度范围内。
  • 经度应在 [-180, 180] 度范围内。

返回类型

BOOL

ST_TOUCHES

ST_TOUCHES(geography_1, geography_2)

说明

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

  1. geography_1geography_2 相交。
  2. geography_1 的内部和 geography_2 的内部不相交。

返回类型

BOOL

ST_WITHIN

ST_WITHIN(geography_1, geography_2)

说明

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

给定两个地理位置 abST_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_spheroidFALSE,则此函数计算完美球面上的距离。

use_spheroid 参数目前仅支持值 FALSEuse_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_spheroidFALSE,则此函数计算完美球面上的距离。

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

返回类型

FLOAT64

ST_LENGTH

ST_LENGTH(geography_expression)
ST_LENGTH(geography_expression, use_spheroid)

说明

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

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

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

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

返回类型

FLOAT64

ST_MAXDISTANCE

ST_MAXDISTANCE(geography_1, geography_2)
ST_MAXDISTANCE(geography_1, geography_2, use_spheroid)

返回两个非空 GEOGRAPHY 之间的最长距离(以米为单位);也就是返回第一个 GEOGRAPHY 中的一个顶点和第二个 GEOGRAPHY 中的一个顶点之间的距离。如果 geography_1geography_2 是同一个 GEOGRAPHY,则此函数返回这个 GEOGRAPHY 中最远的两个顶点之间的距离。

如果任一输入 GEOGRAPHY 为空,则 ST_MAXDISTANCE 返回 NULL

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

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

返回类型

FLOAT64

ST_PERIMETER

ST_PERIMETER(geography_expression)
ST_PERIMETER(geography_expression, use_spheroid)

说明

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

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

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

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

返回类型

FLOAT64

ST_UNION_AGG

ST_UNION_AGG(geography)

说明

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

ST_UNION_AGG 会忽略输入 GEOGRAPHYNULL 值。

如需查看 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 会忽略输入 GEOGRAPHYNULL 值。

如需查看 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)      |
+-----------------+
此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面