StarRocks 空间函数详解:ST_Polygon / ST_PolyFromText / ST_PolygonFromText —— 将 WKT 文本转换为多边形几何对象
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_Point:构造点(Point);
- ST_LineFromText:构造线(LineString);
- ST_Polygon:构造多边形(Polygon);
- ST_GeometryFromText:构造任意类型几何对象;
- ST_Circle:构造圆。
它们构造出的几何对象,可以继续交给 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 中,可概括为四步:
- 读取输入:通过
ColumnViewer<TYPE_VARCHAR>按行读取 WKT 字符串; - 解析 WKT:调用
GeoShape::from_wkt(定义于 geo_types.cpp),内部经由WktParse::parse_wkt完成词法/语法解析并构建GeoShape对象; - 类型校验:解析结果非空且
shape->type() == GEO_SHAPE_POLYGON时才继续,否则该行追加NULL——这正是传入点或线等非多边形文本时返回空值的原因; - 编码输出:调用
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)等底层行为,可作为深入理解该函数语义的参考。
注意事项与最佳实践
- 闭合环:WKT 多边形的环必须闭合(首尾坐标相同),否则可能解析失败;
- 坐标顺序:遵循"经度 纬度"顺序,与常见地图 API 的习惯保持一致,避免因坐标颠倒导致区域判断错误;
- 类型约束:
ST_Polygon只接受多边形文本,构造点请用 ST_Point,构造线请用 ST_LineFromText,不确定类型时可用 ST_GeometryFromText; - 性能:在批量过滤场景中优先使用常量 WKT 字面量,以触发 prepare 阶段的常量折叠优化,避免在热点查询中重复解析;
- 结果解读:函数返回的是内部编码的
GEOMETRY,若需以文本形式查看结果,需配合ST_AsText使用;该结果列可直接存储到表中作为预计算区域,但更常见的做法是查询时构造、查询时使用。
相关函数与延伸阅读
- ST_AsText:几何对象 → WKT 文本(与 ST_Polygon 构成往返);
- ST_Contains:判断几何对象间的包含关系;
- ST_Point 与 ST_LineFromText:同族构造函数;
- ST_Circle:以圆心与半径构造圆;
- ST_Distance_Sphere:球面距离计算。
如需从源码层面继续深入,可依次查看 geo_functions.cpp、geo_types.cpp 以及 WKT 词法/语法定义 wkt_lex.l 与 wkt_yacc.y,即可完整还原 ST_Polygon 从 SQL 文本到内部几何编码的整条调用链。