SonnetDB：空间函数别名的参数与兼容边界

本文介绍 SonnetDB 当前提供的 ST_Distance、ST_Within 与 ST_DWithin 函数别名，重点说明它们实际接受的参数，以及与完整 PostGIS 空间语义的差别。

当前函数表只包含三个别名

SonnetDB 注册了 ST_Distance(point1, point2)、ST_Within(point, center_lat, center_lon, radius_m) 和 ST_DWithin(point, center_lat, center_lon, radius_m)。后两个别名调用同一圆形围栏实现，不能照抄 PostGIS 的几何对象加缓冲区语法。

sql 复制代码

SELECT ST_Distance(
    POINT(39.9042, 116.4074),
    POINT(31.2304, 121.4737)
) AS distance_m;

SELECT time, position
FROM vehicle
WHERE ST_DWithin(position, 31.2304, 121.4737, 1500);

POINT 在 SonnetDB 中使用纬度在前、经度在后。ST_Distance 要求两个 GEOPOINT 并返回 Haversine 距离，单位为米。不要把它改写成未经本轮确认的 ST_MakePoint、::geography 或 geometry 类型转换。

ST_Within 与 ST_DWithin 在这里采用圆形参数

这两个名称在当前注册表中都是四参数 (point, center_lat, center_lon, radius_m) 别名，执行圆心与半径范围判断，半径单位为米。它们不是通用 polygon containment，也不接受 PostGIS 常见的 (geometry, geometry) 两参数形式。

实现要求 radius_m 非负且非 NaN；距离小于等于半径时返回 true。字段应为 GEOPOINT，圆心参数应是纬度和经度数值。迁移前检查实参个数、字段类型、坐标顺序和半径单位，不能只替换函数名。

迁移时逐项保留差异

项目	SonnetDB 当前合同	迁移时要核对
空间字段	时序 measurement 中的 GEOPOINT FIELD	原表类型与时序 TAG/FIELD/time 建模
点构造	POINT(lat, lon)	与来源数据经纬度列顺序
距离	ST_Distance 两个 GEOPOINT，米制 Haversine	PostGIS geometry/geography 模式及其单位
半径过滤	ST_Within/ST_DWithin 四参数圆形围栏	PostGIS 的几何对象、缓冲区和实际谓词语义
矩形过滤	geo_bbox(point, lat_min, lon_min, lat_max, lon_max)	视口边界与经线跨越处理
索引	当前文档描述字面量空间谓词的段内 geohash 剪枝	不等同于 GIST DDL 或所有 PostGIS 索引能力

其他 PostGIS 类型、转换、关系谓词及索引 DDL 不由这三个别名自动提供。别名存在也不证明两种系统结果、边界细节、查询计划或性能等价；迁移需用自己的坐标样本、边界点和目标谓词逐项验证。

本文依据 2026-10-21 当前 FunctionRegistry 与地理空间指南复核，未运行 SQL、PostGIS 对照、数据库迁移或性能测试。封面说明的是函数名称和圆形过滤概念，不是完整兼容证明，也不是运行截图。

依据：FunctionRegistry.cs、GeoPoint.cs 与地理空间指南。