StarRocks 空间函数详解ST_Polygon / ST_PolyFromText / ST_PolygonFromText —— 将 WKT 文本转换为多边形几何对象【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocksST_Polygon 及其别名 ST_PolyFromText、ST_PolygonFromText 是 StarRocks 内置空间函数家族中的构造器之一用于把符合 OGC 标准的 WKTWell-Known Text格式字符串解析为多边形Polygon几何对象的内存编码形式供后续空间关系判断、区域筛选等场景使用。本文以官方函数参考文档为骨架结合 StarRocks 后端 C 实现、前端函数注册以及单元测试系统讲解该函数的语法、WKT 格式约定、返回值语义、底层解析与常量折叠优化并给出可直接运行的实战示例帮助你在地理围栏、区域聚合、空间关联等分析场景中正确使用多边形构造函数。函数概述与定位ST_Polygon 是 StarRocks 空间函数体系中文本 → 几何对象这一类构造函数中的一员。StarRocks 的空间函数统一遵循 OGC Simple Features 规范以 WKT 作为几何对象的通用文本交换格式。与之同族的构造函数包括ST_Point构造点PointST_LineFromText构造线LineStringST_Polygon构造多边形PolygonST_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_ContainsSELECT 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.cppStatusOrColumnPtr 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中可概括为四步读取输入通过ColumnViewerTYPE_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_preparegeo_functions.cpp。其底层的st_from_wkt_prepare_common会在函数执行前检查第一个参数列是否为常量列如果 WKT 是常量例如上文的字符串字面量则在 prepare 阶段提前完成一次解析与编码将结果存入StConstructState状态正式执行阶段不再逐行解析而是通过create_const_column直接批量产出常量结果列。这一机制意味着在数百万行数据上使用同一个常量区域做 ST_Contains 过滤时WKT 解析成本只发生一次对查询性能非常友好。编码格式与还原编码后的几何对象可通过GeoShape::from_encodedgeo_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 文本到内部几何编码的整条调用链。【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 StarRocks 空间函数详解：ST_Polygon / ST_PolyFromText / ST_PolygonFromText —— 将 WKT 文本转换为多边形几何对象
StarRocks 空间函数详解ST_Polygon / ST_PolyFromText / ST_PolygonFromText —— 将 WKT 文本转换为多边形几何对象【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocksST_Polygon 及其别名 ST_PolyFromText、ST_PolygonFromText 是 StarRocks 内置空间函数家族中的构造器之一用于把符合 OGC 标准的 WKTWell-Known Text格式字符串解析为多边形Polygon几何对象的内存编码形式供后续空间关系判断、区域筛选等场景使用。本文以官方函数参考文档为骨架结合 StarRocks 后端 C 实现、前端函数注册以及单元测试系统讲解该函数的语法、WKT 格式约定、返回值语义、底层解析与常量折叠优化并给出可直接运行的实战示例帮助你在地理围栏、区域聚合、空间关联等分析场景中正确使用多边形构造函数。函数概述与定位ST_Polygon 是 StarRocks 空间函数体系中文本 → 几何对象这一类构造函数中的一员。StarRocks 的空间函数统一遵循 OGC Simple Features 规范以 WKT 作为几何对象的通用文本交换格式。与之同族的构造函数包括ST_Point构造点PointST_LineFromText构造线LineStringST_Polygon构造多边形PolygonST_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_ContainsSELECT 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.cppStatusOrColumnPtr 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中可概括为四步读取输入通过ColumnViewerTYPE_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_preparegeo_functions.cpp。其底层的st_from_wkt_prepare_common会在函数执行前检查第一个参数列是否为常量列如果 WKT 是常量例如上文的字符串字面量则在 prepare 阶段提前完成一次解析与编码将结果存入StConstructState状态正式执行阶段不再逐行解析而是通过create_const_column直接批量产出常量结果列。这一机制意味着在数百万行数据上使用同一个常量区域做 ST_Contains 过滤时WKT 解析成本只发生一次对查询性能非常友好。编码格式与还原编码后的几何对象可通过GeoShape::from_encodedgeo_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 文本到内部几何编码的整条调用链。【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考