标准 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
按照外部格式(例如 WKTGeoJSON)创建地理位置的函数。
格式设置函数 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
针对两个地理位置之间的某种空间关系或地理位置的某个属性返回 TRUEFALSE 的函数。这种函数通常用于过滤条件子句。
量度 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_spheroidFALSE,则此函数会计算完美球面上的距离。

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

返回类型

FLOAT64

ST_ASBINARY

ST_ASBINARY(geography_expression)

说明

返回输入 GEOGRAPHYWKB 表示形式。

如需按照 WKB 构造 GEOGRAPHY,请参阅 ST_GEOGFROMWKB

返回类型

BYTES

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

use_spheroid 参数目前仅支持值 FALSEuse_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 是非负 INT64epsilon 是非负 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_1geography_2 为空,则返回 FALSE。如果 geography_1 中没有位于 geography_2 外部的点,则返回 TRUE

对于给定的两个 GEOGRAPHYab),ST_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_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_DIMENSION

ST_DIMENSION(geography_expression)

说明

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

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

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

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

返回类型

INT64

ST_DISJOINT

ST_DISJOINT(geography_1, geography_2)

说明

如果 geography_1geography_2 的交集为空(geography_1 中没有同时位于 geography_2 中的点),则返回 TRUE

ST_DISJOINTST_INTERSECTS 的逻辑求反函数。

返回类型

BOOL

ST_DISTANCE

ST_DISTANCE(geography_1, geography_2[, use_spheroid])

说明

返回两个非空 GEOGRAPHY 之间的最短距离(以米为单位)。

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

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

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

返回类型

FLOAT64

ST_DUMP

ST_DUMP(geography[, dimension])

说明

返回由简单 GEOGRAPHY 组成的 ARRAY,其中每个元素都是输入 GEOGRAPHY 的组件。简单的 GEOGRAPHY 由单个点、线串或多边形组成。如果输入 GEOGRAPHY 很简单,则结果是单个元素。当输入 GEOGRAPHY 是一个集合时,ST_DUMP 会为集合中的每个组件返回一个简单 GEOGRAPHYARRAY

如果提供了 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_spheroidFALSE,则此函数会计算完美球面上的距离。

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

返回类型

BOOL

ST_EQUALS

ST_EQUALS(geography_1, geography_2)

说明

如果 geography_1geography_2 代表相同的值,则返回 TRUE

GEOGRAPHY 值。更确切地说,这意味着必须满足以下条件之一: + ST_COVERS(geography_1, geography_2) = TRUEST_COVERS(geography_2, geography_1) = TRUE + geography_1geography_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 几何图形类型,包括 PointMultiPointLineStringMultiLineStringPolygonMultiPolygonGeometryCollection。其他任何 GeoJSON 类型都将导致错误,例如 FeatureFeatureCollection
  • GeoJSON 几何图形类型的 coordinates 成员的位置信息必须仅包含两个元素。第一个是经度,第二个是纬度。因此,ST_GEOGFROMGEOJSON 不支持 coordinates 成员的位置信息包含可选的第三个元素。

返回类型

GEOGRAPHY

ST_GEOGFROMTEXT

ST_GEOGFROMTEXT(wkt_string[, oriented])

说明

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

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

说明

创建包含一个点的 GEOGRAPHYST_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_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_INTERSECTION

ST_INTERSECTION(geography_1, geography_2)

说明

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

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

如需了解相关的谓词函数,请参阅 ST_INTERSECTSST_DISJOINT

返回类型

GEOGRAPHY

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

use_spheroid 参数目前仅支持值 FALSEuse_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 的第一种变体,如果任一个输入 GEOGRAPHYNULL,则 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 的第一种变体,如果任一输入 GEOGRAPHYNULL,则 ST_MAKEPOLYGON 返回 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_MAXDISTANCE

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_NUMPOINTS

ST_NUMPOINTS(geography_expression)

说明

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

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

返回类型

INT64

ST_PERIMETER

ST_PERIMETER(geography_expression[, use_spheroid])

说明

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

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

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

use_spheroid 参数目前仅支持值 FALSEuse_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_1geography_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 的第一种变体,如果输入 GEOGRAPHYNULL,则 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_1geography_2 的内部相交,则返回 TRUE

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

返回类型

BOOL

ST_X

ST_X(geography_expression)

说明

返回单点输入 GEOGRAPHY 的经度,以度为单位。

对于任何并非单点的输入 GEOGRAPHY(包括空的 GEOGRAPHY),ST_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(包括空的 GEOGRAPHY),ST_Y 会返回一个错误。使用 SAFE. 前缀可返回 NULL

返回类型

FLOAT64

示例

如需查看用法示例,请参阅 ST_X