原生 GEO 函数重载矩阵
本文定义初始 GEO 函数组中原生 GEOGRAPHY 和 GEOMETRY 函数的重载契约。函数 ID 用于 FE 到 BE 的分发。系统按 SQL 逻辑类型解析重载,并在运行时单独校验值描述符;不会根据 WKB 字节推断球面或平面语义。
通用行为
- 原生构造和序列化函数支持全部七种二维 OGC 类型:
POINT、LINESTRING、POLYGON、MULTIPOINT、MULTILINESTRING、MULTIPOLYGON和GEOMETRYCOLLECTION,也支持带类型的EMPTY和空子对象。 - 参数为
NULL时返回NULL。对于格式错误的 WKT/WKB 或不支持的构造参数,构造函数也返回NULL。 - 原生计算函数要求 XY 值和有效描述符。不支持的类型、维度或描述符会返回受控错误,除非下表明确规定该行的
EMPTY返回NULL。 GEOGRAPHY与GEOMETRY是不同的逻辑类型。混合类型调用没有对应重载,因此会被拒绝。GEOGRAPHY使用OGC:CRS84、球面边、经度/纬度坐标顺序和 SRID 4326。GEOMETRY使用平面语义和描述符中显式指定的 CRS。本矩阵中的函数都不执行坐标重投影。
构造函数
| 签名 | 函数 ID | 返回类型 | 支持的类型和维度 | CRS 和描述符行为 |
|---|---|---|---|---|
ST_GeogFromText(VARCHAR wkt) |
120020 | GEOGRAPHY |
全部七种二维类型和 EMPTY |
使用原生 OGC:CRS84 球面描述符和 SRID 4326。 |
ST_GeogFromText(VARCHAR wkt, INT srid) |
120021 | GEOGRAPHY |
全部七种二维类型和 EMPTY |
srid 必须为 4326;结果使用原生 OGC:CRS84 球面描述符。 |
ST_GeomFromText(VARCHAR wkt, VARCHAR crs) |
120022 | GEOMETRY |
全部七种二维类型和 EMPTY |
crs 必须是非空字符串字面量,并写入平面结果描述符。没有默认 CRS。 |
ST_GeogFromWKB(VARBINARY wkb) |
120030 | GEOGRAPHY |
全部七种二维类型和 EMPTY;支持两种 WKB 字节序 |
使用原生 OGC:CRS84 球面描述符和 SRID 4326。不支持 EWKB。 |
ST_GeogFromWKB(VARBINARY wkb, INT srid) |
120031 | GEOGRAPHY |
全部七种二维类型和 EMPTY;支持两种 WKB 字节序 |
srid 必须为 4326;结果使用原生 OGC:CRS84 球面描述符。不支持 EWKB。 |
ST_GeomFromWKB(VARBINARY wkb, VARCHAR crs) |
120032 | GEOMETRY |
全部七种二维类型和 EMPTY;支持两种 WKB 字节序 |
crs 必须是非空字符串字面量,并写入平面结果描述符。不支持 EWKB 和 Z/M 坐标。 |
Geography 坐标必须位于支持的经纬度范围内。Geometry 构造函数不会重新解释坐标,也不会把坐标转换到其他 CRS。参见 ST_GeogFromText、ST_GeogFromWKB、ST_GeomFromText 和 ST_GeomFromWKB。
序列化函数
| 签名 | 函数 ID | 返回类型 | 行为 |
|---|---|---|---|
ST_AsText(GEOGRAPHY value) |
120040 | VARCHAR |
输出 WKT,不修改坐标或输入描述符。 |
ST_AsText(GEOMETRY value) |
120041 | VARCHAR |
输出 WKT,不修改坐标或输入描述符。 |
ST_AsWKT(GEOGRAPHY value) |
120050 | VARCHAR |
原生 ST_AsText(GEOGRAPHY) 行为的别名。 |
ST_AsWKT(GEOMETRY value) |
120051 | VARCHAR |
原生 ST_AsText(GEOMETRY) 行为的别名。 |
ST_AsBinary(GEOGRAPHY value) |
120060 | VARBINARY |
输出 WKB。逻辑类型、CRS 和边语义仍是类型元数据,不编码为 EWKB。 |
ST_AsBinary(GEOMETRY value) |
120061 | VARBINARY |
输出 WKB。逻辑类型和 CRS 仍是类型元数据,不编码为 EWKB。 |
ST_AsWKB(GEOGRAPHY value) |
120070 | VARBINARY |
原生 ST_AsBinary(GEOGRAPHY) 行为的别名。 |
ST_AsWKB(GEOMETRY value) |
120071 | VARBINARY |
原生 ST_AsBinary(GEOMETRY) 行为的别名。 |
参见 ST_AsText 和 ST_AsWKT 以及 ST_AsBinary 和 ST_AsWKB。
初始计算函数
| 签名 | 函数 ID | 返回值和单位 | 支持的值 | NULL、EMPTY 和描述符行为 |
|---|---|---|---|---|
ST_X(GEOGRAPHY point) |
120080 | DOUBLE,经度(度) |
非空 XY POINT |
NULL 传递。EMPTY、非 POINT 或不支持的描述符报错。 |
ST_X(GEOMETRY point) |
120081 | DOUBLE,输入 CRS 单位 |
非空 XY POINT |
NULL 传递。EMPTY、非 POINT 或不支持的描述符报错。 |
ST_Y(GEOGRAPHY point) |
120090 | DOUBLE,纬度(度) |
非空 XY POINT |
NULL 传递。EMPTY、非 POINT 或不支持的描述符报错。 |
ST_Y(GEOMETRY point) |
120091 | DOUBLE,输入 CRS 单位 |
非空 XY POINT |
NULL 传递。EMPTY、非 POINT 或不支持的描述符报错。 |
ST_GeometryType(GEOGRAPHY value) |
120170 | VARCHAR 类型名称 |
所有受支持的 XY 类型 | NULL 传递。带类型的 EMPTY 保留其类型名称。不支持的维度或描述符报错。 |
ST_GeometryType(GEOMETRY value) |
120171 | VARCHAR 类型名称 |
所有受支持的 XY 类型 | NULL 传递。带类型的 EMPTY 保留其类型名称。不支持的维度或描述符报错。 |
ST_Distance(GEOGRAPHY lhs, GEOGRAPHY rhs) |
120180 | DOUBLE,米 |
球面 CRS84 契约下的 XY POINT/POINT,或 POINT 与 LINESTRING/MULTILINESTRING |
NULL 或 EMPTY 返回 NULL。不支持的类型、维度、描述符或不明确的对跖线段报错。 |
ST_Distance(GEOMETRY lhs, GEOMETRY rhs) |
120181 | DOUBLE,输入 CRS 单位 |
描述符匹配的 XY POINT/POINT,或 POINT 与 LINESTRING/MULTILINESTRING |
NULL 或 EMPTY 返回 NULL。不支持的类型、维度或不兼容描述符报错。 |
ST_DWithin(GEOGRAPHY lhs, GEOGRAPHY rhs, DOUBLE distance) |
120230 | BOOLEAN;distance 单位为米 |
XY POINT 与 LINESTRING/MULTILINESTRING,参数顺序不限 |
阈值包含相等边界。NULL 传递;EMPTY 返回 false。阈值必须是有限的非负数。 |
ST_DWithin(GEOMETRY lhs, GEOMETRY rhs, DOUBLE distance) |
120231 | BOOLEAN;distance 使用输入 CRS 单位 |
描述符匹配的 XY POINT 与 LINESTRING/MULTILINESTRING,参数顺序不限 |
阈值包含相等边界。NULL 传递;EMPTY 返回 false。阈值必须是有限的非负数。 |
参见 ST_X、ST_Y、ST_GeometryType、ST_Distance 和 ST_DWithin。
包含关系谓词
| 签名 | 函数 ID | 边界行为 |
|---|---|---|
ST_Contains(GEOGRAPHY polygon, GEOGRAPHY point) |
120190 | 仅当点位于多边形内部时返回 true。 |
ST_Contains(GEOMETRY polygon, GEOMETRY point) |
120191 | 仅当点位于多边形内部时返回 true。 |
ST_Within(GEOGRAPHY point, GEOGRAPHY polygon) |
120200 | ST_Contains 的反向关系,不包含边界。 |
ST_Within(GEOMETRY point, GEOMETRY polygon) |
120201 | ST_Contains 的反向关系,不包含边界。 |
ST_Covers(GEOGRAPHY polygon, GEOGRAPHY point) |
120210 | 包含外环和内环边界。 |
ST_Covers(GEOMETRY polygon, GEOMETRY point) |
120211 | 包含外环和内环边界。 |
ST_CoveredBy(GEOGRAPHY point, GEOGRAPHY polygon) |
120220 | ST_Covers 的反向关系,包含边界。 |
ST_CoveredBy(GEOMETRY point, GEOMETRY polygon) |
120221 | ST_Covers 的反向关系,包含边界。 |
这些重载支持 XY POINT 与 POLYGON 或 MULTIPOLYGON。GEOGRAPHY 按球面 CRS84 边计算;GEOMETRY 按平面边计算并要求描述符匹配。NULL 传递,EMPTY 输入返回 false。不支持的类型、维度、描述符以及混合 GEOGRAPHY/GEOMETRY 调用会被拒绝。参见 ST_Contains、ST_Within、ST_Covers 和 ST_CoveredBy。
相交谓词
| 签名 | 函数 ID | 边界行为 |
|---|---|---|
ST_Intersects(GEOGRAPHY lhs, GEOGRAPHY rhs) |
120240 | 球面重叠、包含和边界接触均返回 true。 |
ST_Intersects(GEOMETRY lhs, GEOMETRY rhs) |
120241 | 平面重叠、包含和边界接触均返回 true。 |
这些重载支持 XY POLYGON 和 MULTIPOLYGON。GEOMETRY 输入必须具有匹配的描述符。NULL 传递,EMPTY 输入返回 false。不支持的类型、集合以及混合的原生逻辑类型会被拒绝。参见 ST_Intersects。
度量和属性
| 签名 | 函数 ID | 结果和单位 | Family 行为 |
|---|---|---|---|
ST_Area(GEOGRAPHY value) |
120250 | DOUBLE,平方米 |
递归合计面面积,扣除洞,低维分量贡献 0。 |
ST_Area(GEOMETRY value) |
120251 | DOUBLE,输入 CRS 单位的平方 |
递归合计面面积,扣除洞,低维分量贡献 0。 |
ST_Length(GEOGRAPHY value) |
120260 | DOUBLE,米 |
递归合计线长度,点和面贡献 0。 |
ST_Length(GEOMETRY value) |
120261 | DOUBLE,输入 CRS 单位 |
递归合计线长度,点和面贡献 0。 |
ST_Perimeter(GEOGRAPHY value) |
120270 | DOUBLE,米 |
递归合计面的外环和内环长度。 |
ST_Perimeter(GEOMETRY value) |
120271 | DOUBLE,输入 CRS 单位 |
递归合计面的外环和内环长度。 |
ST_Centroid(GEOGRAPHY value) |
120280 | GEOGRAPHY POINT,descriptor 不变 |
使用最高非空维度和球面尺寸权重。 |
ST_Centroid(GEOMETRY value) |
120281 | GEOMETRY POINT,descriptor 不变 |
使用最高非空维度和平面尺寸权重。 |
ST_IsValid(GEOGRAPHY value) |
120290 | BOOLEAN |
使用球面有效性,包括 MultiPolygon 内部重叠检查。 |
ST_IsValid(GEOMETRY value) |
120291 | BOOLEAN |
使用稳健的平面拓扑有效性。 |
所有 overload 均接受七种 XY OGC family,并在适用时递归处理 MULTI* 和 GEOMETRYCOLLECTION。NULL 传播;度量对 EMPTY 返回 0,ST_Centroid 返回 POINT EMPTY,ST_IsValid 返回 true。可读取但拓扑无效的值仅由 ST_IsValid 返回 false,度量和质心会拒绝该输入。WKB 格式错误、不支持的维度或 descriptor 会返回错误。
球面面环与方向无关,并归一化为较小区域;单个环不表示超过半球的区域。参见 ST_Area、ST_Length、ST_Perimeter、ST_Centroid 和 ST_IsValid。
CRS 元数据与坐标转换
| 签名 | 函数 ID | 结果 | 行为 |
|---|---|---|---|
ST_SRID(GEOMETRY value) |
120300 | INT 或 NULL |
从描述符读取数字 EPSG 映射,不转换坐标。 |
ST_SetSRID(GEOMETRY value, INT constant) |
120305 | GEOMETRY,目标 EPSG 描述符 |
只修改元数据;WKB 和坐标保持不变。 |
ST_Transform(GEOMETRY value, INT constant) |
120310 | GEOMETRY,目标 EPSG 描述符 |
使用 Web Mercator 公式在 EPSG:4326 和 EPSG:3857 之间重投影 XY 坐标。 |
两个目标 SRID 都必须是可由 FE 折叠为常量的 4326 或 3857。源 CRS 必须是 EPSG:4326、EPSG:3857 或 OGC:CRS84。ST_Transform 处理七种 XY OGC 几何类型及集合;NULL 传播,EMPTY 保持为空。参见 ST_SRID、ST_SetSRID 和 ST_Transform。
旧版兼容性
原生重载不会重新编号或替换现有的 VARCHAR 函数:
| 旧版签名 | 函数 ID |
|---|---|
ST_X(VARCHAR) |
120001 |
ST_Y(VARCHAR) |
120002 |
ST_AsText(VARCHAR) |
120004 |
ST_AsWKT(VARCHAR) |
120005 |
ST_GeometryFromText(VARCHAR) |
120006 |
ST_GeomFromText(VARCHAR) |
120007 |
ST_Contains(VARCHAR, VARCHAR) |
120014 |
升级与参考测试契约
滚动升级时,应先升级 BE,再升级 FE。原生标量函数使用普通的稳定函数 ID 分发,不引入单独的 GEO 版本门控。覆盖窗口注册表见下文。不支持新 FE 与旧 BE 的升级顺序。
该契约由聚焦的 FE analyzer 测试验证重载解析、返回类型、旧版兼容性和函数 ID,并由 BE registry 测试验证每个原生 ID。现有 BE 函数测试覆盖常量、Nullable、变化输入、EMPTY、格式错误输入、类型、维度、CRS 和描述符行为。
多边形叠加运算
支持具有兼容 CRS 的原生 XY 多边形及多多边形;4326 和 3857 均使用笛卡尔语义。NULL 参数返回 NULL。ST_Union、ST_Difference 和 ST_SymDifference 的单个组成部分返回 POLYGON,多个返回 MULTIPOLYGON,空结果返回 POLYGON EMPTY。无效拓扑返回错误。精度与资源限制见链接页面。
ST_Intersection 还保留公共边和孤立接触点:无面积时返回线或点类型,混合维度返回 GEOMETRYCOLLECTION。已被较高维结果覆盖的部分不会重复返回;不相交的输入返回 POLYGON EMPTY。
| Signature | Function ID | Reference |
|---|---|---|
ST_Intersection(GEOMETRY, GEOMETRY) |
120341 | ST_Intersection |
ST_Union(GEOMETRY, GEOMETRY) |
120351 | ST_Union |
ST_Difference(GEOMETRY, GEOMETRY) |
120361 | ST_Difference |
ST_SymDifference(GEOMETRY, GEOMETRY) |
120371 | ST_SymDifference |
笛卡尔缓冲区
支持原生 XY POINT、LINESTRING、POLYGON 及其 MULTI 类型。距离为输入 CRS 单位下的有限有符号值;圆角近似、NULL 传播、空结果为多边形 EMPTY。结果保留 CRS。ST_Buffer 不支持 GEOGRAPHY、集合、Z/M 或选项。
| Signature | Function ID | Reference |
|---|---|---|
ST_Buffer(GEOMETRY, DOUBLE) |
120401 | ST_Buffer |
保留拓扑的简化
笛卡尔 XY 标量几何,保留类型、环、接触关系、带类型的 EMPTY 子元素和 CRS。容差使用输入坐标单位。不支持 GEOGRAPHY、Z/M 或跨行覆盖简化。
| Signature | Function ID | Reference |
|---|---|---|
ST_SimplifyPreserveTopology(GEOMETRY, DOUBLE) |
120411 | ST_SimplifyPreserveTopology |
H3 网格函数
几何参数需要原生 XY CRS84 GEOGRAPHY;网格索引是有符号 BIGINT。有效性、NULL/EMPTY、填充近似和限制见 H3 函数。
| Signature | Function ID | Result |
|---|---|---|
H3_FromGeo(GEOGRAPHY, INT) |
120500 | BIGINT |
H3_GridDisk(BIGINT, INT) |
120501 | ARRAY<BIGINT> |
H3_ToParent(BIGINT, INT) |
120502 | BIGINT |
H3_ToChildren(BIGINT, INT) |
120503 | ARRAY<BIGINT> |
H3_Resolution(BIGINT) |
120504 | INT |
H3_ToBoundary(BIGINT) |
120505 | GEOGRAPHY |
H3_PolygonToCells(GEOGRAPHY, INT) |
120506 | ARRAY<BIGINT> |
联合覆盖简化(窗口)
两个重载共同处理整个分区,每行返回保留原类型和 CRS 的 XY GEOMETRY。参数必须为可折叠的计划常量,OVER 必需。不支持窗口内 ORDER BY、显式 frame 和普通聚合。拓扑、NULL/EMPTY、容差与资源限制参见 ST_CoverageSimplify。
| 签名 | 返回值 |
|---|---|
ST_CoverageSimplify(GEOMETRY, DOUBLE) OVER (...) |
GEOMETRY |
ST_CoverageSimplify(GEOMETRY, DOUBLE, BOOLEAN) OVER (...) |
GEOMETRY |
未注册 GEOGRAPHY 重载。BE 根据名称及逻辑参数/返回类型在窗口注册表中解析。升级时先升级 BE,再升级 FE。
本文来自 StarRocks 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。
