StarRocks 空间函数详解:ST_Polygon / ST_PolyFromText / ST_PolygonFromText —— 将 WKT 文本转换为多边形几何对象

原创2026-09-18 13:25:541,430 阅读
文章标签:大数据OLAP数据仓库湖仓一体数据库数据分析

StarRocks 空间函数详解:ST_Polygon / ST_PolyFromText / ST_PolygonFromText —— 将 WKT 文本转换为多边形几何对象

ST_Polygon 及其别名 ST_PolyFromText、ST_PolygonFromText 是 StarRocks 内置空间函数家族中的"构造器"之一,用于把符合 OGC 标准的 WKT(Well-Known Text)格式字符串解析为多边形(Polygon)几何对象的内存编码形式,供后续空间关系判断、区域筛选等场景使用。本文以官方函数参考文档为骨架,结合 StarRocks 后端 C++ 实现、前端函数注册以及单元测试,系统讲解该函数的语法、WKT 格式约定、返回值语义、底层解析与常量折叠优化,并给出可直接运行的实战示例,帮助你在地理围栏、区域聚合、空间关联等分析场景中正确使用多边形构造函数。

函数概述与定位

ST_Polygon 是 StarRocks 空间函数体系中"文本 → 几何对象"这一类构造函数中的一员。StarRocks 的空间函数统一遵循 OGC Simple Features 规范,以 WKT 作为几何对象的通用文本交换格式。与之同族的构造函数包括:

它们构造出的几何对象,可以继续交给 ST_Contains(包含关系判断)、ST_AsText(输出 WKT 文本)等函数使用,从而支撑"某经纬度点是否落在某行政区域内"这类典型的地理围栏查询。

函数语法

根据 官方函数参考文档,该函数的语法为:

GEOMETRY ST_Polygon(VARCHAR wkt)

其中:

  • ST_Polygon 是正式函数名,同时提供 ST_PolyFromText、ST_PolygonFromText 两个等义别名,三者行为完全一致;
  • 参数 wkt 是一个 VARCHAR 类型的字符串,内容是描述多边形的 WKT 文本;
  • 返回类型为 GEOMETRY,即多边形在 StarRocks 内部的内存编码形式(实际存储为经过编码的二进制字节序列,见下文"底层实现"一节)。

从源码看,前端在 FunctionSet.java 中注册了三个等义名称:

public static final String ST_POLYGON = "st_polygon";
public static final String ST_POLYFROMTEXT = "st_polyfromtext";
public static final String ST_POLYGONFROMTEXT = "st_polygonfromtext";

也就是说,ST_Polygon(...)、ST_PolyFromText(...)、ST_PolygonFromText(...) 三种写法最终都会路由到同一个后端实现 GeoFunctions::st_polygon。

WKT 多边形格式说明

WKT 中多边形的基本书写规则如下:

  • 以关键字 POLYGON 开头,后面紧跟一对圆括号;
  • 圆括号内是一组"环(ring)"的坐标序列,每个环由一组二维坐标点 x y 组成,多个点之间用逗号分隔;
  • 多边形通常至少包含一个外环(exterior ring),环的首尾坐标必须相同(即闭合);
  • 可选的第二个及后续环表示多边形中的"洞(hole)";
  • 坐标顺序为经度在前、纬度在后。

一个典型的合法多边形 WKT 示例:

POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))

它描述了一个以 (0,0)、(10,0)、(10,10)、(0,10) 为四个顶点、并回到起点闭合的矩形区域。支持带洞的多边形,例如:

POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0), (2 2, 2 4, 4 4, 4 2, 2 2))

第二个环即代表多边形内部被挖去的一块区域。

从仓库的语法定义看,StarRocks 使用 flex/bison 实现了 WKT 解析器:词法文件 wkt_lex.l 中定义了 POLYGON、MULTIPOLYGON 等关键字,语法文件 wkt_yacc.y 中定义了 KW_POLYGON '(' coordinate_list_list ')' 的产生式,因此 ST_Polygon 可正确解析单环与多环(含洞)多边形。此外,底层几何类型体系 geo_types.h 中的 GeoShapeType 枚举还区分了 GEO_SHAPE_POLYGON(值为 3)与 GEO_SHAPE_MULTI_POLYGON(值为 6),多面(MultiPolygon)类型的解析能力同样存在,只是 ST_Polygon 只接受单多边形输入。

使用示例

以下示例取自官方文档,展示构造多边形后再用 ST_AsText 还原为 WKT 文本的完整往返过程:

MySQL > SELECT ST_AsText(ST_Polygon("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))"));
+------------------------------------------------------------------+
| st_astext(st_polygon('POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))')) |
+------------------------------------------------------------------+
| POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))                          |
+------------------------------------------------------------------+

场景一:经纬度点与区域多边形的包含判断

构造一个真实地理围栏并判断某个点是否落在其中(借助 ST_Contains):

SELECT ST_Contains(
         ST_Polygon('POLYGON ((116.30 39.80, 116.45 39.80, 116.45 40.00, 116.30 40.00, 116.30 39.80))'),
         ST_Point(116.40, 39.90)
       );

结果为 1,表示该坐标点位于多边形内部;若点落在区域之外则返回 0。

场景二:在表查询中结合常量折叠使用

ST_Polygon 的参数既可以是字符串字面量,也可以是表中的 VARCHAR 列:

-- 常量区域:每个点都判断是否落入同一个区域
SELECT id, lng, lat
FROM user_locations
WHERE ST_Contains(
          ST_Polygon('POLYGON ((116.30 39.80, 116.45 39.80, 116.45 40.00, 116.30 40.00, 116.30 39.80))'),
          ST_Point(lng, lat)
      );

-- 列参数:区域本身来自表
SELECT ST_AsText(ST_Polygon(region_wkt)) AS region
FROM region_table
WHERE region_id = 1;

场景三:验证往返一致性

用 ST_AsText 将构造结果还原成文本,可校验 WKT 是否被正确解析和编码:

SELECT ST_AsText(ST_Polygon('POLYGON ((0 0, 4 0, 4 4, 0 4, 0 0))'));

返回 POLYGON ((0 0, 4 0, 4 4, 0 4, 0 0)),与输入一致。

无效输入的行为

  • 如果 wkt 参数为 NULL,函数返回 NULL;
  • 如果 WKT 文本语法非法,或解析出的几何类型不是多边形(例如传入 POINT (1 1)),函数返回 NULL,不会抛出异常导致查询失败。

底层实现原理

ST_Polygon 在后端由 GeoFunctions::st_polygon 实现,位于 geo_functions.cpp:

StatusOr<ColumnPtr> GeoFunctions::st_polygon(FunctionContext* context, const Columns& columns) {
    return st_from_wkt_common(context, columns, GEO_SHAPE_POLYGON);
}

其核心流程记录在 geo_functions.cpp 的公共函数 st_from_wkt_common 中,可概括为四步:

  1. 读取输入:通过 ColumnViewer<TYPE_VARCHAR> 按行读取 WKT 字符串;
  2. 解析 WKT:调用 GeoShape::from_wkt(定义于 geo_types.cpp),内部经由 WktParse::parse_wkt 完成词法/语法解析并构建 GeoShape 对象;
  3. 类型校验:解析结果非空且 shape->type() == GEO_SHAPE_POLYGON 时才继续,否则该行追加 NULL——这正是传入点或线等非多边形文本时返回空值的原因;
  4. 编码输出:调用 shape->encode_to(&buf) 将几何对象序列化为二进制字节串,作为结果列的 VARCHAR 值返回,即文档中所说的"内存形式(memory form)"。

常量折叠优化

值得关注的是,st_polygon 带有专门的 prepare 阶段函数 st_polygon_prepare(geo_functions.cpp)。其底层的 st_from_wkt_prepare_common 会在函数执行前检查第一个参数列是否为常量列:如果 WKT 是常量(例如上文的字符串字面量),则在 prepare 阶段提前完成一次解析与编码,将结果存入 StConstructState 状态;正式执行阶段不再逐行解析,而是通过 create_const_column 直接批量产出常量结果列。这一机制意味着:在数百万行数据上使用同一个常量区域做 ST_Contains 过滤时,WKT 解析成本只发生一次,对查询性能非常友好。

编码格式与还原

编码后的几何对象可通过 GeoShape::from_encoded(geo_types.cpp)解码还原:该函数按首字节校验编码版本(要求为 0X00)、按第二个字节区分几何类型(GEO_SHAPE_POLYGON 对应 GeoPolygon),再调用 decode 恢复坐标。ST_AsText 等输出类函数正是基于该解码能力工作的,这也是 SELECT ST_AsText(ST_Polygon(...)) 能够完整还原输入文本的原因。

单元测试佐证

仓库在后端测试 geography_functions_test.cpp 中为该函数提供了两类测试:

  • st_polygonGeneralTest:向 st_polygon 传入普通 WKT 列,验证返回的编码结果可被 GeoPolygon::decode_from 成功解码;
  • st_polygonConstTest:构造常量列输入,验证常量折叠路径下输出与普通路径一致。

此外,geo_types_test.cpp 覆盖了多边形的包含关系判断(polygon_contains)与非法 WKT 解析失败(polygon_parse_fail)等底层行为,可作为深入理解该函数语义的参考。

注意事项与最佳实践

  1. 闭合环:WKT 多边形的环必须闭合(首尾坐标相同),否则可能解析失败;
  2. 坐标顺序:遵循"经度 纬度"顺序,与常见地图 API 的习惯保持一致,避免因坐标颠倒导致区域判断错误;
  3. 类型约束:ST_Polygon 只接受多边形文本,构造点请用 ST_Point,构造线请用 ST_LineFromText,不确定类型时可用 ST_GeometryFromText;
  4. 性能:在批量过滤场景中优先使用常量 WKT 字面量,以触发 prepare 阶段的常量折叠优化,避免在热点查询中重复解析;
  5. 结果解读:函数返回的是内部编码的 GEOMETRY,若需以文本形式查看结果,需配合 ST_AsText 使用;该结果列可直接存储到表中作为预计算区域,但更常见的做法是查询时构造、查询时使用。

相关函数与延伸阅读

如需从源码层面继续深入,可依次查看 geo_functions.cpp、geo_types.cpp 以及 WKT 词法/语法定义 wkt_lex.l 与 wkt_yacc.y,即可完整还原 ST_Polygon 从 SQL 文本到内部几何编码的整条调用链。

登录后查看全文
starrocks