SonnetDB：KNN 查询的距离语义与维度边界

本文介绍 SonnetDB 的 knn() 表值函数，重点是查询向量、距离方向与实际检索路径的边界。

假设 documents 已有三维 VECTOR FIELD 列 embedding，以及 title TAG：

sql 复制代码

SELECT time, title, distance
FROM knn(documents, embedding, [1.0, 0.0, 0.0], 2, 'cosine');

knn 位于 FROM 中。向量列需要是 VECTOR FIELD，查询向量的分量数量必须与列声明一致；不能用省略号替代实际向量数据。k 表示最多取回多少个最近邻，候选不足时结果可以少于 k。

cosine 距离是 1-cosine_similarity；当前数据库 KNN 距离入口遇到任一零向量时返回 1。这个返回值不是嵌入质量验证，业务仍应检查零向量和模型输出。

l2 使用欧氏距离，即差值平方和的平方根。归一化向量的 L2 与 cosine 可以有相同排序，但数值不相等，不能直接共用同一个阈值。

knn 的 inner_product 使用负点积，点积越大，返回距离越小。SQL 标量 inner_product 返回正点积，这是另一条接口；不能把它与 KNN distance 混为同一种升序分数。

"距离小于 0.2 就一定相关"不是通用标准。阈值受模型、向量归一化、领域分布、度量和业务代价影响，应使用自己的相关性样本评估。

当前执行器同时处理内存层和持久段，并存在段内 HNSW 加速与精确扫描等路径。是否使用索引、索引度量是否匹配、时间与 TAG 过滤、逻辑删除及替换记录都会影响实际执行，不能单凭函数名宣称固定延迟或百分之百召回。

直接查询的投影和过滤也应按当前入口合同使用；复杂子查询、聚合或特定物化预算的组合需要分别验证。查询结果、真实模型质量、固定硬件性能和生产服务验收是不同证据。

封面是三维邻近与度量选择的概念图，不是模型或检索性能实测。本文依据 2026-10-17 当前源码复核；SQL 为复现示例，本轮未执行数据库、真实模型或基准测试。