Source: https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/geo/ Documentation version: v5.3.2 # 地理空间函数 ## ST_Point() 基于给定的经度和纬度返回一个 Point。 NULL 行为：默认 ### 函数签名 ```` ST_Point(longitude Numeric, latitude Numeric) -> Geography(Point) ```` ### 示例 ```` RETURN ST_Point(37.7749, -12.4194) AS point1 ```` 返回： ```` +-------------------------+ | point1 | +-------------------------+ | POINT(37.7749 -12.4194) | +-------------------------+ ```` ## ST_GeogFromText() / ST_GeogFromWKT() 返回给定的 WKT 字符串对应的地理空间值。 NULL 行为：默认 ### 函数签名 ```` ST_GeogFromText(wkt String) -> Geography(Any) ```` 或 ```` ST_GeogFromWKT(wkt String) -> Geography(Any) ```` NULL 行为：默认 ### 示例 #### 返回一个 Point ```` RETURN ST_GeogFromText('POINT(37.7749 -12.4194)') AS point1 ```` 返回： ```` +-------------------------+ | point1 | +-------------------------+ | POINT(37.7749 -12.4194) | +-------------------------+ ```` #### 返回一个 LineString ```` RETURN ST_GeogFromText('LINESTRING(1 2, 2 4, 4 8, 8 16)') AS linestring1 ```` 返回： ```` +-------------------------------------------------+ | linestring1 | +-------------------------------------------------+ | LINESTRING(1.0 2.0, 2.0 4.0, 4.0 8.0, 8.0 16.0) | +-------------------------------------------------+ ```` #### 返回一个 Polygon ```` RETURN ST_GeogFromText('POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))') AS polygon1 ```` 返回： ```` +------------------------------------------------------------+ | polygon1 | +------------------------------------------------------------+ | POLYGON((0.0 0.0, 0.0 10.0, 10.0 10.0, 10.0 0.0, 0.0 0.0)) | +------------------------------------------------------------+ ```` ## ST_ASText() 返回一个地理空间值对应的 WKT 字符串。 NULL 行为：默认 ### 函数签名 ```` ST_ASText(g Geography) -> String ```` ### 示例 ```` RETURN ST_ASText(ST_Point(37.7749, -12.4194)) AS string_point ```` 返回： ```` +-------------------------+ | string_point | +-------------------------+ | POINT(37.7749 -12.4194) | +-------------------------+ ```` ## ST_Centroid() 返回一个地理空间值的中心点，即形状的几何中心。 NULL 行为：默认 ### 函数签名 ```` ST_Centroid(g Geography) -> Geography(Point) ```` ### 示例 #### 返回一个 Point 的中心 ```` RETURN ST_Centroid(ST_GeogFromText('POINT(37.7749 -12.4194)')) AS centroid1 ```` 返回： ```` +-------------------------+ | centroid1 | +-------------------------+ | POINT(37.7749 -12.4194) | +-------------------------+ ```` #### 返回一个 LineString 的中心 ```` RETURN ST_Centroid(ST_GeogFromText('LINESTRING(1 2, 2 4, 4 8, 8 16)')) AS centroid1 ```` 返回： ```` +--------------------------------------------+ | centroid1 | +--------------------------------------------+ | POINT(4.462127805439562 9.001796271028539) | +--------------------------------------------+ ```` #### 返回一个 Polygon 的中心 ```` RETURN ST_Centroid(ST_GeogFromText('POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))')) AS centroid1 ```` 返回： ```` +--------------------------------------------+ | centroid1 | +--------------------------------------------+ | POINT(5.000000000000015 5.005958633534428) | +--------------------------------------------+ ```` ## ST_ISValid() 如果给定的地理空间值有效，返回`true`，否则返回`false`。 NULL 行为：默认 ### 函数签名 ```` ST_ISValid(g Geography) -> Boolean ```` ### 示例 ```` RETURN ST_ISValid(ST_Point(37.7749, -124.4194)) AS isValidPoint ```` 返回： ```` +--------------+ | isValidPoint | +--------------+ | false | +--------------+ ```` ## ST_Intersects() 如果给定的两个地理空间值相交（共享至少一个公共点），返回`true`；否则返回`false`。 NULL 行为：默认 ### 函数签名 ```` ST_Intersects(g1 Geography, g2 Geography) -> Boolean ```` ### 示例 ```` RETURN ST_Intersects(ST_GeogFromText('POINT(0 1)'), ST_GeogFromText('POLYGON((0 1, 1 2, 2 3, 0 1))')) AS v ```` 返回： ```` +------+ | v | +------+ | true | +------+ ```` ## ST_IntersectionPoints 返回两个地理空间值边界交叉点的列表。 NULL 行为：默认 ### 函数签名 ```` ST_IntersectionPoints(g1 Geography, g2 Geography) -> LIST ```` ### 示例 ```` RETURN ST_IntersectionPoints(ST_GeogFromText("LineString(0 1,1 0)"),ST_GeogFromText("LineString(0 0,1 1)")) AS v ```` 返回： ```` +------------------------------------------------+ | v | +------------------------------------------------+ | [POINT(0.4999999999999999 0.5000571197534015)] | +------------------------------------------------+ ```` ## ST_Covers() 给定两个地理空间值`g1`和`g2`。如果`g1`完全包含`g2`（即`g2`的所有点位于`g1`的内部或边界上），返回`true`，否则返回`false`。 NULL 行为：默认 ### 函数签名 ```` ST_Covers(g1 Geography, g2 Geography) -> Boolean ```` ### 示例 ```` RETURN ST_Covers(ST_GeogFromText('POLYGON((0 1, 1 2, 3 0, 0 1))'), ST_GeogFromText('POINT(1 1)')) AS v ```` 返回： ```` +------+ | v | +------+ | true | +------+ ```` ## ST_CoveredBy 给定两个地理空间值`g1`和`g2`。如果`g2`完全包含`g1`（即`g1`的所有点位于`g2`的内部或边界上），返回`true`，否则返回`false`。 NULL 行为：默认 ### 函数签名 ```` ST_CoveredBy(g1 Geography, g2 Geography) -> Boolean ```` ### 示例 ```` RETURN ST_CoveredBy(ST_GeogFromText('POLYGON((0 1, 1 2, 3 0, 0 1))'), ST_GeogFromText('POINT(1 1)')) AS v ```` 返回： ```` +-------+ | v | +-------+ | false | +-------+ ```` ## ST_DWithin 给定两个地理空间值`g1`和`g2`以及一个以米为单位的距离阈值。如果`g1`中至少一个点与`g2`中至少一个点之间的距离小于或等于该阈值，返回`true`；否则返回`false`。 NULL 行为：默认 ### 函数签名 ```` ST_DWithin(g1 Geography, g2 Geography, distance DOUBLE) -> Boolean ```` ### 示例 ```` RETURN ST_DWithin(ST_GeogFromText("Point(0 0)"),ST_GeogFromText("Point(10 10)"),20000000000) AS v ```` 返回： ```` +------+ | v | +------+ | true | +------+ ```` ## ST_Distance 返回两个地理空间值之间的最短距离（以米为单位）。 NULL 行为：默认 ### 函数签名 ```` ST_Distance(g1 Geography, g2 Geography) -> DOUBLE ```` ### 示例 ```` RETURN ST_Distance(ST_GeogFromText("Point(0 0)"),ST_GeogFromText("Point(10 10)")) AS distance ```` 返回： ```` +--------------------+ | distance | +--------------------+ | 1568523.0187677438 | +--------------------+ ```` ## S2_CellIdFromPoint 返回覆盖一个 Point 的 [S2 单元](https://s2geometry.io/devguide/s2cell_hierarchy) ID。 NULL 行为：默认 ### 函数签名 ```` S2_CellIdFromPoint(g Geography(Point)) -> UINT64 ```` ### 示例 ```` RETURN S2_CellIdFromPoint(ST_GeogFromText("Point(1 1)")) AS v ```` 返回： ```` +---------------------+ | v | +---------------------+ | 1153277837650709461 | +---------------------+ ```` ## S2_CoveringCellIds 返回覆盖一个地理空间值的 [S2 单元](https://s2geometry.io/devguide/s2cell_hierarchy) ID 列表。 NULL 行为：默认 ### 函数签名 ```` S2_CoveringCellIds(g Geography) -> LIST ```` ### 示例 ```` RETURN S2_CoveringCellIds(ST_GeogFromText("POLYGON((0 1, 1 2, 2 3, 0 1))")) AS v ```` 返回： ```` +-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | v | +-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | [1152391494368201343,1153466862374223872,1153554823304445952,1153836298281156608,1153959443583467520,1154240918560178176,1160503736791990272,1160591697722212352] | +-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ````