地理空间函数¶

以 ST_ 为前缀的 Presto 地理空间函数支持 SQL/MM 规范，并符合开放地理空间联盟 (OGC) 的 OpenGIS 规范。因此，许多 Presto 地理空间函数需要（更准确地说，假定）对它们进行操作的几何图形既简单又有效。例如，计算具有在多边形外部定义的孔的多边形的面积，或者从非简单边界线构造多边形是没有意义的。

Presto 地理空间函数支持空间对象的“熟知文本”(WKT) 和“熟知二进制”(WKB) 格式。

• POINT (0 0)

• LINESTRING (0 0, 1 1, 1 2)

• POLYGON ((0 0, 4 0, 4 4, 0 4, 0 0), (1 1, 2 1, 2 2, 1 2, 1 1))

• MULTIPOINT (0 0, 1 2)

• MULTILINESTRING ((0 0, 1 1, 1 2), (2 3, 3 2, 5 4))

• MULTIPOLYGON (((0 0, 4 0, 4 4, 0 4, 0 0), (1 1, 2 1, 2 2, 1 2, 1 1)), ((-1 -1, -1 -2, -2 -2, -2 -1, -1 -1)))

• GEOMETRYCOLLECTION (POINT(2 3), LINESTRING (2 3, 3 4))

使用 ST_GeometryFromText 和 ST_GeomFromBinary 函数从 WKT 或 WKB 创建几何图形对象。在 WKT/WKB 中，坐标顺序为 (x, y)。对于球面/地理空间使用，这意味着 (longitude, latitude) 而不是 (latitude, longitude)。

Geometry 类型的基础是一个平面。平面上的两点之间的最短路径是一条直线。这意味着几何图形的计算（面积、距离、长度、交点等）可以使用笛卡尔数学和直线向量进行计算。

类型 SphericalGeography 为以“地理”坐标（有时称为“大地测量”坐标或“经纬度”或“经度/纬度”）表示的空间特征提供原生支持。地理坐标是使用角度单位（度）表示的球面坐标。

类型 SphericalGeography 的基础是一个球体。球体上两点之间的最短路径是大圆弧。这意味着地理上的计算（面积、距离、长度、交点等）必须在球体上进行计算，使用更复杂的数学方法。不支持考虑实际地球椭球形状的更精确的测量。

对于 SphericalGeography 对象，测量函数 ST_Distance 和 ST_Length 返回的值以米为单位；ST_Area 返回的值以平方米为单位。

使用 to_spherical_geography() 函数将几何对象转换为地理对象。例如，ST_Distance(ST_Point(-71.0882, 42.3607), ST_Point(-74.1197, 40.6976)) 在欧几里得平面上的传入值单位中返回 3.4577，而 ST_Distance(to_spherical_geography(ST_Point(-71.0882, 42.3607)), to_spherical_geography(ST_Point(-74.1197, 40.6976))) 以米为单位返回 312822.179。

构造函数¶

ST_AsBinary(Geometry) -> varbinary()¶

返回几何的 WKB 表示。

ST_AsText(Geometry) -> varchar()¶

返回几何的 WKT 表示。对于空几何，ST_AsText(ST_LineFromText('LINESTRING EMPTY')) 将生成 'MULTILINESTRING EMPTY'，而 ST_AsText(ST_Polygon('POLYGON EMPTY')) 将生成 'MULTIPOLYGON EMPTY'。

ST_GeometryFromText(varchar) -> Geometry()¶

从 WKT 表示返回几何类型对象。

ST_GeomFromBinary(varbinary) -> Geometry()¶

从 WKB 表示返回几何类型对象。

ST_LineFromText(varchar) -> LineString()¶

从 WKT 表示返回几何类型线字符串对象。

ST_LineString(array(Point)) -> LineString()¶

返回由一系列点形成的 LineString。如果输入数组中少于两个非空点，则将返回一个空的 LineString。如果数组中的任何元素为 null 或为空或与前一个元素相同，则抛出异常。返回的几何可能不简单，例如可能自相交或可能包含重复顶点，具体取决于输入。

ST_MultiPoint(array(Point)) -> MultiPoint()¶

返回由指定点形成的 MultiPoint 几何对象。如果输入数组为空，则返回 null。如果数组中的任何元素为 null 或为空，则抛出异常。如果输入数组有重复项，则返回的几何可能不简单，可能包含重复点。

ST_Point(x, y) -> Point()¶

返回具有给定坐标值的几何类型点对象。

ST_Polygon(varchar) -> Polygon()¶

从 WKT 表示返回几何类型多边形对象。

to_spherical_geography(Geometry) -> SphericalGeography()¶

将 Geometry 对象转换为地球半径的球体上的 SphericalGeography 对象。此函数仅适用于在二维空间中定义的 POINT、MULTIPOINT、LINESTRING、MULTILINESTRING、POLYGON、MULTIPOLYGON 几何，或此类几何的 GEOMETRYCOLLECTION。对于输入几何的每个点，它验证 point.x 在 [-180.0, 180.0] 内，point.y 在 [-90.0, 90.0] 内，并使用它们作为 (经度, 纬度) 度来构建 SphericalGeography 结果的形状。

to_geometry(SphericalGeography) -> Geometry()¶

将 SphericalGeography 对象转换为 Geometry 对象。

关系测试¶

ST_Contains(Geometry, Geometry) -> boolean()¶

当且仅当第二几何的任何点都不在第一几何的外部，并且第一几何的内部至少有一个点在第二几何的内部时，返回 true。

ST_Crosses(Geometry, Geometry) -> boolean()¶

如果提供的几何具有部分但不全部内部点重合，则返回 true。

ST_Disjoint(Geometry, Geometry) -> boolean()¶

如果给定的几何不 *空间相交*（它们没有共享任何空间），则返回 true。

ST_Equals(Geometry, Geometry) -> boolean()¶

如果给定的几何表示相同的几何，则返回 true。

ST_Intersects(Geometry, Geometry) -> boolean()¶

如果给定的几何在二维空间中空间相交（共享任何部分的空间），则返回 true；如果它们不相交（它们是不相交的），则返回 false。

ST_Overlaps(Geometry, Geometry) -> boolean()¶

如果给定的几何共享空间、具有相同的维度，但没有完全包含在彼此内，则返回 true。

ST_Relate(Geometry, Geometry) -> boolean()¶

如果第一个几何与第二个几何空间相关，则返回 true。

ST_Touches(Geometry, Geometry) -> boolean()¶

如果给定的几何至少有一个公共点，但它们的内部不相交，则返回 true。

ST_Within(Geometry, Geometry) -> boolean()¶

如果第一个几何完全在第二个几何内部，则返回 true。

操作¶

geometry_union(array(Geometry)) -> Geometry()¶

返回一个几何，该几何表示输入几何的点集并集。此函数与 array_agg() 结合使用，以首先聚合输入几何，其性能可能优于 geometry_union_agg()，但以更高的内存使用率为代价。

ST_Boundary(Geometry) -> Geometry()¶

返回此几何的组合边界的闭包。

ST_Buffer(Geometry, distance) -> Geometry()¶

返回一个几何，该几何表示从指定几何到所有点的距离小于或等于指定距离的所有点。如果几何的点非常靠近 (delta < 1e-8)，这可能会返回一个空几何。

ST_Difference(Geometry, Geometry) -> Geometry()¶

返回表示给定几何图形点集差的几何图形值。

ST_Envelope(Geometry) -> Geometry()¶

返回几何图形的边界矩形多边形。

ST_EnvelopeAsPts(Geometry) -> array(Geometry)¶

返回两个点数组：几何图形的边界矩形多边形的左下角和右上角。如果输入几何图形为空，则返回 null。

expand_envelope(Geometry, double) -> Geometry()¶

返回几何图形的边界矩形多边形，按距离扩展。空几何图形将返回空多边形。负数或 NaN 距离将返回错误。正无穷大距离可能导致未定义的结果。

ST_ExteriorRing(Geometry) -> Geometry()¶

返回表示输入多边形的外部环的线字符串。

ST_Intersection(Geometry, Geometry) -> Geometry()¶

返回表示两个几何图形的点集交集的几何图形值。

ST_SymDifference(Geometry, Geometry) -> Geometry()¶

返回表示两个几何图形的点集对称差的几何图形值。

ST_Union(Geometry, Geometry) -> Geometry()¶

返回表示输入几何图形的点集并集的几何图形。

另请参阅：geometry_union(), geometry_union_agg()

访问器¶

ST_Area(Geometry) -> double()¶

返回几何图形的二维欧几里得面积。

对于点和线字符串类型，返回 0.0。对于几何图形集合类型，返回各个几何图形的面积总和。

ST_Area(SphericalGeography) -> double()¶

返回多边形或多边形集合的面积（以平方米为单位），使用地球的球面模型。

ST_Centroid(Geometry) -> Point()¶

返回作为几何图形数学形心的点值。

ST_Centroid(SphericalGeography) -> Point()¶

返回作为球面几何图形数学形心的点值。

它支持点和多点作为输入，并返回投影到（球面）地球表面上的三维形心，例如 MULTIPOINT (0 -45, 0 45, 30 0, -30 0) 返回 Point(0, 0) 注意：如果三维形心位于 (0, 0, 0)，则球面形心未定义，并将返回任意点，例如 MULTIPOINT (0 0, -180 0) 返回 Point(-90, 45)

ST_ConvexHull(Geometry) -> Geometry()¶

返回包围所有输入几何图形的最小凸几何图形。

ST_CoordDim(Geometry) -> bigint()¶

返回几何图形的坐标维数。

ST_Dimension(Geometry) -> bigint()¶

返回此几何图形对象的固有维数，该维数必须小于或等于坐标维数。

ST_Distance(Geometry, Geometry) -> double()¶

返回两个几何图形在投影单位中基于空间参考的二维笛卡尔最小距离。

ST_Distance(SphericalGeography, SphericalGeography) -> double()¶

返回两个 SphericalGeography 点之间的球面距离（以米为单位）。

geometry_nearest_points(Geometry, Geometry) -> array(Point)¶

返回每个几何图形上最靠近另一个几何图形的点。如果任一几何图形为空，则返回 NULL。否则，返回两个点的数组，这两个点在几何图形上具有最小距离。第一个点将来自第一个几何图形参数，第二个点将来自第二个几何图形参数。如果有多对具有最小距离的点，则任意选择其中一对。

ST_GeometryN(Geometry, index) -> Geometry()¶

返回给定索引处的几何图形元素（索引从 1 开始）。如果几何图形是几何图形集合（例如，GEOMETRYCOLLECTION 或 MULTI*），则返回给定索引处的几何图形。如果给定索引小于 1 或大于集合中元素的总数，则返回 NULL。使用 :func:ST_NumGeometries 来找出元素的总数。单一几何图形（例如，POINT、LINESTRING、POLYGON）被视为包含一个元素的集合。空几何图形被视为空集合。

ST_InteriorRingN(Geometry, index) -> Geometry()¶

返回指定索引处的内部环元素（索引从 1 开始）。如果给定索引小于 1 或大于输入几何图形中内部环的总数，则返回 NULL。如果输入几何图形不是多边形，则抛出错误。使用 :func:ST_NumInteriorRing 来找出元素的总数。

ST_GeometryType(Geometry) -> varchar()¶

返回几何图形的类型。

ST_IsClosed(Geometry) -> boolean()¶

如果线字符串的起点和终点重合，则返回 true。

ST_IsEmpty(Geometry) -> boolean()¶

如果此 Geometry 是空几何图形集合、多边形、点等，则返回 true。

ST_IsSimple(Geometry) -> boolean()¶

如果此 Geometry 没有异常的几何点，例如自交或自切，则返回 true。使用 geometry_invalid_reason() 来确定几何图形为什么不是简单的。

ST_IsRing(Geometry) -> boolean()¶

当且仅当线是闭合且简单的时，返回 true。

ST_IsValid(Geometry) -> boolean()¶

当且仅当输入几何图形格式良好时，返回 true。使用 geometry_invalid_reason() 来确定几何图形为什么格式不佳。

ST_Length(Geometry) -> double()¶

返回使用二维平面（基于空间参考）上的欧几里得度量计算的线字符串或多线字符串的长度，以投影单位表示。

ST_Length(SphericalGeography) -> double()¶

返回线字符串或多线字符串在地球球面模型上的长度。这相当于线字符串上相邻点之间的大圆距离之和。

ST_PointN(LineString, index) -> Point()¶

返回线字符串中给定索引处的顶点（索引从 1 开始）。如果给定的索引小于 1 或大于集合中元素的总数，则返回 NULL。使用 :func:ST_NumPoints 来找出元素的总数。

ST_Points(Geometry) -> array(Point)¶

返回线字符串中的一系列点。

ST_XMax(Geometry) -> double()¶

返回几何图形边界框的 X 最大值。

ST_YMax(Geometry) -> double()¶

返回几何图形边界框的 Y 最大值。

ST_XMin(Geometry) -> double()¶

返回几何图形边界框的 X 最小值。

ST_YMin(Geometry) -> double()¶

返回几何图形边界框的 Y 最小值。

ST_StartPoint(Geometry) -> point()¶

返回 LineString 几何图形的第一个点，表示为 Point。这是 ST_PointN(geometry, 1) 的快捷方式。

ST_EndPoint(Geometry) -> point()¶

返回 LineString 几何图形的最后一个点，表示为 Point。这是 ST_PointN(geometry, ST_NumPoints(geometry)) 的快捷方式。

ST_X(Point) -> double()¶

返回点的 X 坐标。

ST_Y(Point) -> double()¶

返回点的 Y 坐标。

ST_InteriorRings(Geometry) -> array(Geometry)¶

返回输入几何图形中找到的所有内部环的数组，如果多边形没有内部环，则返回空数组。如果输入几何图形为空，则返回 null。如果输入几何图形不是多边形，则抛出错误。

ST_NumGeometries(Geometry) -> bigint()¶

返回集合中几何图形的数量。如果几何图形是几何图形的集合（例如，GEOMETRYCOLLECTION 或 MULTI*），则返回几何图形的数量，对于单个几何图形返回 1，对于空几何图形返回 0。请注意，GEOMETRYCOLLECTION 内部的空几何图形将计为一个几何图形；例如 ST_NumGeometries(ST_GeometryFromText('GEOMETRYCOLLECTION(MULTIPOINT EMPTY)')) 将评估为 1。

ST_Geometries(Geometry) -> array(Geometry)¶

返回指定集合中的几何图形数组。如果输入几何图形不是多几何图形，则返回一个元素的数组。如果输入几何图形为空，则返回 null。

例如，MultiLineString 将创建一个 LineString 数组。GeometryCollection 将生成其组成部分的未扁平化数组：GEOMETRYCOLLECTION(MULTIPOINT(0 0, 1 1), GEOMETRYCOLLECTION(MULTILINESTRING((2 2, 3 3)))) 将生成 array[MULTIPOINT(0 0, 1 1), GEOMETRYCOLLECTION(MULTILINESTRING((2 2, 3 3)))]。

flatten_geometry_collections(Geometry) -> array(Geometry)¶

递归地扁平化 Geometry 中的任何 GeometryCollection，返回一个组成非 GeometryCollection 几何图形的数组。数组的顺序是任意的，不应该依赖于它。例子

POINT (0 0) -> [POINT (0 0)], MULTIPOINT (0 0, 1 1) -> [MULTIPOINT (0 0, 1 1)], GEOMETRYCOLLECTION (POINT (0 0), GEOMETRYCOLLECTION (POINT (1 1))) -> [POINT (0 0), POINT (1 1)], GEOMETRYCOLLECTION EMPTY -> []。

ST_NumPoints(Geometry) -> bigint()¶

返回几何图形中的点数。这是对 SQL/MM ST_NumPoints 函数的扩展，该函数仅适用于点和线字符串。

ST_NumInteriorRing(Geometry) -> bigint()¶

返回多边形内部环集合的基数。

simplify_geometry(Geometry, double) -> Geometry()¶

使用 Douglas-Peucker 算法返回输入几何图形的“简化”版本。将避免创建无效的派生几何图形（特别是多边形）。

line_locate_point(LineString, Point) -> double()¶

返回一个介于 0 和 1 之间的浮点数，表示 LineString 上最靠近给定 Point 的点的位置，作为总 2d 线长度的一部分。

如果 LineString 或 Point 为空或 null，则返回 null。

line_interpolate_point(LineString, double) -> Geometry()¶

返回 LineString 上由双精度参数给出的分数距离处的 Point。如果距离不在 0 到 1 之间，则抛出异常。

如果 LineString 为空，则返回一个空 Point。如果 LineString 或 double 为空，则返回 null。

geometry_invalid_reason(Geometry) -> varchar()¶

返回输入几何图形无效或不简单的原因。如果几何图形既无效也不简单，它将只给出无效的原因。如果输入有效且简单，则返回 null。

great_circle_distance(latitude1, longitude1, latitude2, longitude2) -> double()¶

返回地球表面上两点之间的大圆距离，以公里为单位。

geometry_as_geojson(Geometry) -> varchar()¶

返回由输入几何图形定义的 GeoJSON 编码。如果几何图形是原子（非多）空，则此函数将返回 null。

geometry_from_geojson(varchar) -> Geometry()¶

从 GeoJSON 表示中返回几何类型对象。如果几何类型是原子（非多重）几何类型，则几何类型不能为空。

聚合¶

convex_hull_agg(Geometry) -> Geometry()¶

返回包围所有输入几何图形的最小凸几何图形。

geometry_union_agg(Geometry) -> Geometry()¶

返回表示所有输入几何图形的点集并集的几何图形。

必应瓦片¶

这些函数在几何图形和 必应瓦片 之间进行转换。对于必应瓦片，x 和 y 指的是 tile_x 和 tile_y。必应瓦片可以使用内部表示形式转换为和从 BigInts 转换，该表示形式有效地编码了 zoom、x 和 y

cast(cast(tile AS BIGINT) AS BINGTILE)

虽然每个瓦片都可以转换为 bigint，但从不代表有效瓦片的 bigint 转换会引发异常。

bing_tile(x, y, zoom_level) -> BingTile()¶

从 XY 坐标和缩放级别创建必应瓦片对象。支持缩放级别 1 到 23。

bing_tile(quadKey) -> BingTile()¶

从四叉树键创建必应瓦片对象。

bing_tile_parent(tile) -> BingTile()¶

返回在低一个缩放级别上的必应瓦片的父级。如果瓦片位于缩放级别 0，则抛出异常。

bing_tile_parent(tile, newZoom) -> BingTile()¶

返回在指定低缩放级别上的必应瓦片的父级。如果 newZoom 小于 0 或 newZoom 大于瓦片的缩放级别，则抛出异常。

bing_tile_children(tile) -> array(BingTile)¶

返回在高一个缩放级别上的必应瓦片的子级。如果瓦片位于最大缩放级别，则抛出异常。

bing_tile_children(tile, newZoom) -> array(BingTile)¶

返回在指定高缩放级别上的必应瓦片的子级。如果 newZoom 大于最大缩放级别或 newZoom 小于瓦片的缩放级别，则抛出异常。

bing_tile_at(latitude, longitude, zoom_level) -> BingTile()¶

返回在给定缩放级别上包含给定纬度和经度上的点的必应瓦片。纬度必须在 [-85.05112878, 85.05112878] 范围内。经度必须在 [-180, 180] 范围内。支持缩放级别 1 到 23。

bing_tiles_around(latitude, longitude, zoom_level) -> array(BingTile)¶

返回在给定缩放级别上围绕由纬度和经度参数指定的点的必应瓦片的集合。

bing_tiles_around(latitude, longitude, zoom_level, radius_in_km) -> array(BingTile)¶

返回在指定缩放级别上覆盖以指定 (纬度，经度) 点为中心的指定半径（公里）圆的最小必应瓦片集。

bing_tile_coordinates(tile) -> row<x, y>()¶

返回给定必应瓦片的 XY 坐标。

bing_tile_polygon(tile) -> Geometry()¶

返回给定必应瓦片的 polygon 表示形式。

bing_tile_quadkey(tile) -> varchar()¶

返回给定必应瓦片的四叉树键。

bing_tile_zoom_level(tile) -> tinyint()¶

返回给定必应瓦片的缩放级别。

geometry_to_bing_tiles(geometry, zoom_level) -> array(BingTile)¶

返回在给定缩放级别上完全覆盖给定几何图形的最小必应瓦片集。支持缩放级别 1 到 23。

geometry_to_dissolved_bing_tiles(geometry, max_zoom_level) -> array(BingTile)¶

返回在给定缩放级别上完全覆盖给定几何图形的最小必应瓦片集，递归地将完整的子集集解散为父集。这将导致一个更小的不同缩放级别瓦片数组。例如，如果未解散的覆盖范围为 [“00”，“01”，“02”，“03”，“10”]，则解散后的覆盖范围将为 [“0”，“10”]。支持缩放级别 1 到 23。