地理空間函數¶

以 ST_ 字首開頭的 Presto 地理空間函數支援 SQL/MM 規格，並符合開放地理空間協會 (OGC) 的 OpenGIS 規格。因此，許多 Presto 地理空間函數都需要，或者更準確地說，假設運算的幾何圖形都是簡單且有效的。例如，計算在多邊形外部定義孔的多邊形面積，或者從非簡單邊界線建構多邊形是沒有意義的。

Presto 地理空間函數支援空間物件的 Well-Known Text (WKT) 和 Well-Known Binary (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)。對於球體/地理空間用途，這表示 (經度, 緯度)，而不是 (緯度, 經度)。

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()¶

傳回由點陣列形成的線字串。如果輸入陣列中的非空點少於兩個，則會傳回空的線字串。如果陣列中的任何元素為 null 或空白，或與前一個元素相同，則會擲回例外狀況。傳回的幾何圖形可能不是簡單的，例如可能自我相交，或可能包含重複的頂點，視輸入而定。

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

傳回由指定的點形成的多點幾何物件。如果輸入陣列為空，則傳回 null。如果陣列中的任何元素為 null 或空白，則會擲回例外狀況。傳回的幾何圖形可能不是簡單的，如果輸入陣列有重複項目，則可能包含重複的點。

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

傳回具有指定座標值的幾何類型點物件。

ST_Polygon(varchar) -> Polygon()¶

從 WKT 表示法傳回幾何類型多邊形物件。

to_spherical_geography(Geometry) -> SphericalGeography()¶

將幾何物件轉換為地球半徑球體上的球體地理物件。此函數僅適用於 2D 空間中定義的 POINT、MULTIPOINT、LINESTRING、MULTILINESTRING、POLYGON、MULTIPOLYGON 幾何圖形，或此類幾何圖形的 GEOMETRYCOLLECTION。對於輸入幾何圖形的每個點，它會驗證 point.x 是否在 [-180.0, 180.0] 範圍內，而 point.y 是否在 [-90.0, 90.0] 範圍內，並將它們用作（經度，緯度）度數，以建構 SphericalGeography 結果的形狀。

to_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()¶

如果此幾何圖形是空的幾何圖形集合、多邊形、點等，則傳回 true。

ST_IsSimple(Geometry) -> boolean()¶

如果此幾何圖形沒有異常的幾何點，例如自我交叉或自我相切，則傳回 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 上最接近給定點的位置，以總 2D 線長的分數表示。

如果 LineString 或 Point 為空或 null，則回傳 null。

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

回傳 LineString 上，由 double 參數指定的距離比例所對應的 Point。如果距離不在 0 到 1 之間，則會拋出例外。

如果 LineString 為空，則回傳一個空的 Point。如果 LineString 或 double 為 null，則回傳 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()¶

回傳一個幾何圖形，代表所有輸入幾何圖形的點集合聯集。

Bing 圖磚¶

這些函數用於在幾何圖形和 Bing 圖磚之間進行轉換。對於 Bing 圖磚，x 和 y 指的是 tile_x 和 tile_y。Bing 圖磚可以使用內部表示法在 BigInt 之間相互轉換，該內部表示法會有效率地編碼 zoom、x 和 y。

cast(cast(tile AS BIGINT) AS BINGTILE)

雖然每個圖磚都可以轉換為 bigint，但如果從不代表有效圖磚的 bigint 轉換，則會拋出例外。

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

從 XY 座標和縮放層級建立 Bing 圖磚物件。支援 1 到 23 的縮放層級。

bing_tile(quadKey) -> BingTile()¶

從四元金鑰建立 Bing 圖磚物件。

bing_tile_parent(tile) -> BingTile()¶

回傳縮放層級低一級的 Bing 圖磚的父圖磚。如果圖磚的縮放層級為 0，則會拋出例外。

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

回傳指定較低縮放層級的 Bing 圖磚的父圖磚。如果 newZoom 小於 0，或 newZoom 大於圖磚的縮放層級，則會拋出例外。

bing_tile_children(tile) -> array(BingTile)¶

回傳縮放層級高一級的 Bing 圖磚的子圖磚。如果圖磚處於最大縮放層級，則會拋出例外。

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

回傳指定較高縮放層級的 Bing 圖磚的子圖磚。如果 newZoom 大於最大縮放層級，或 newZoom 小於圖磚的縮放層級，則會拋出例外。

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

回傳在給定縮放層級，包含給定緯度和經度點的 Bing 圖磚。緯度必須在 [-85.05112878, 85.05112878] 範圍內。經度必須在 [-180, 180] 範圍內。支援 1 到 23 的縮放層級。

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

回傳在給定縮放層級，環繞由緯度和經度參數指定的點的 Bing 圖磚集合。

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

回傳在指定的縮放層級，涵蓋以指定（緯度、經度）點為中心，指定半徑（以公里為單位）的圓形的最小 Bing 圖磚集合。

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

回傳給定 Bing 圖磚的 XY 座標。

bing_tile_polygon(tile) -> Geometry()¶

回傳給定 Bing 圖磚的多邊形表示法。

bing_tile_quadkey(tile) -> varchar()¶

回傳給定 Bing 圖磚的四元金鑰。

bing_tile_zoom_level(tile) -> tinyint()¶

回傳給定 Bing 圖磚的縮放層級。

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

回傳在給定縮放層級，完全涵蓋給定幾何圖形的最小 Bing 圖磚集合。支援 1 到 23 的縮放層級。

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

傳回涵蓋指定幾何形狀在指定縮放級別的最小 Bing 圖磚集合，並遞迴地將完整的子圖磚集合合併至父圖磚。這樣會產生一個較小的、包含不同縮放級別圖磚的陣列。例如，如果未合併的覆蓋範圍是 [“00”, “01”, “02”, “03”, “10”]，則合併後的覆蓋範圍將會是 [“0”, “10”]。支援從 1 到 23 的縮放級別。