OneUptime API Reference 数据类型详解LessThanOrNull 查询过滤器字段小于指定值或为空【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeLessThanOrNull 是 OneUptime 开放 API 查询体系中的一种比较型查询过滤器query filter data type其匹配语义为目标字段值严格小于指定值或者目标字段本身为空NULL。本文以 API Reference 文档目录下的 LessThanOrNull 代码示例 为切入点结合Common/Types的类型定义、服务端查询转换链路与 ClickHouse 分析数据库的 SQL 生成实现完整讲解该数据类型的请求格式、源码原理、适用场景与验证方式帮助你准确地在 OneUptime API 查询中使用小于或为空的过滤条件。一、从一个请求示例开始关联文档给出的是一段完整的 API 查询请求体示例JSON 格式用于按age字段过滤满足小于 10 或为空条件的记录{ query: { age: { _type: LessThanOrNull, value: 10 } } }在 OneUptime 的 API Reference 中所有查询过滤型数据类型LessThan、LessThanOrEqual、EqualTo、GreaterThanOrNull等都遵循这一统一的嵌套对象结构。逐字段拆解如下字段含义说明query查询根对象整个请求体的查询条件容器每个键对应一个模型字段age目标字段名需要施加过滤条件的模型字段此处以age为例_type类型判别器discriminator声明该查询节点的操作符类型固定为LessThanOrNull服务端据此路由到对应的比较逻辑value比较基准值要与字段值进行比较的数值此处为10需要特别说明的是文档源文件中的\_type带有一个反斜杠这是 Markdown 写作时对下划线_的转义用于防止_type被 Markdown 解析为斜体标记在实际发送的 JSON 请求体中字段名就是_type不带反斜杠。类似地LessThanOrNull中的下划线同样不是嵌套层级而只是类型名称的一部分——同一份代码示例目录下的 LessThan.md、EqualToOrNull.md 等都采用相同的命名约定例如EqualToOrNull的_type值为EqualToOrNullLessThan的_type值为LessThan。二、LessThanOrNull 的语义与应用场景根据 OneUptime API Reference 的数据类型详情页定义见 DataTypeDetail.tsLessThanOrNull 的官方描述为A query filter that matches objects where a field is less than the specified value or is null.即当且仅当目标字段值小于指定值或目标字段值为 NULL 时记录才会被匹配。用关系型数据库的 WHERE 条件表达其等价语义为field :value OR field IS NULL这与单纯的LessThan仅匹配field :value相比多出了包含 NULL 记录这一分支。这一设计在可观测性与监控类系统中非常实用典型的应用场景包括阈值过滤筛选年龄、耗时、响应码等指标低于某阈值或尚未采集到数值NULL的设备与监控目标时间边界查询筛选更新/同步时间早于某个时间点或从未更新过时间字段为 NULL的记录例如找出长期未心跳的探针可选字段过滤业务模型中的可选列如deletedAt、acknowledgedAt经常为 NULL使用 LessThanOrNull 可以一次性覆盖已处理且早于时间点与从未处理两类记录避免因 NULL 参与比较而被关系数据库的三值逻辑排除。三、请求参数详解LessThanOrNull 节点只包含两个必填参数参数类型是否必填说明_typestring枚举判别器是固定为LessThanOrNull用于服务端反序列化时识别操作符类型valuestring \| number \| Date是比较基准值。字段值小于该值或字段值为 NULL 时匹配value的类型约束来自类型系统的CompareType定义见 CompareBase.tsexport type CompareType number | Date | string;也就是说value既可以传数值如示例中的10、ISO 8601 时间字符串/日期也可以是字符串。结合模型列的实际类型服务端会将其绑定为对应数据库类型的字面量参与比较。四、服务端类型实现源码解析前端Dashboard 等客户端与服务端共享同一套数据模型类型。LessThanOrNull 的核心类定义位于 Common/Types/BaseDatabase/LessThanOrNull.ts其继承自 CompareBase再向上继承自QueryOperatorT实现了三个关键行为1.toJSON()以原始值序列化保护 Date 全精度public override toJSON(): JSONObject { return { _type: ObjectType.LessThanOrNull, value: (this as LessThanOrNullT).value, }; }源码注释明确指出这里序列化的是RAW 原始值而不是toString()的结果。原因是toString()会把Date通过OneUptimeDate.asDateForDatabaseQuery折叠成本地时区的仅日期字符串这正是该实现中toString()方法的实际行为见 LessThanOrNull.ts。如果浏览器端发送当前时刻作为比较边界经toString()折叠后到达服务端的会变成当天零点从而把当天的记录全部静默排除。而JSON.stringify会把原始Date输出为完整 ISO 时间戳服务端可以按全精度绑定。因此 API 传输使用原始值序列化。2.fromJSON()严格校验_type判别器public static override fromJSONT extends CompareType( json: JSONObject, ): LessThanOrNullT { if (json[_type] ObjectType.LessThanOrNull) { return new LessThanOrNullT(json[value] as T); } throw new BadDataException(Invalid JSON: JSON.stringify(json)); }反序列化时如果_type不等于ObjectType.LessThanOrNull会抛出BadDataException位于 Common/Types/Exception/BadDataException.ts避免错误的判别器值被静默解析成错误的操作符。3._type判别器的枚举定义_type的值来自 Common/Types/JSON.ts 中的ObjectType枚举其中比较型过滤器统一在此登记GreaterThan GreaterThan, GreaterThanOrEqual GreaterThanOrEqual, GreaterThanOrNull GreaterThanOrNull, LessThanOrNull LessThanOrNull, LessThan LessThan, LessThanOrEqual LessThanOrEqual,同一枚举还收录了IsNull、NotNull、Includes、EqualTo等所有查询节点类型使整个查询 DSL 具有自描述能力。五、从查询对象到 SQL底层转换链路客户端传入的LessThanOrNull节点并不会直接被数据库执行而是要经过服务端查询工具层转换为数据库操作符。这条链路分为两条路径5.1 关系型数据库TypeORM路径在 Common/Server/Types/Database/QueryUtil.ts 中查询对象被逐个字段扫描通过instanceof匹配到LessThanOrNull实例后调用QueryHelper.lessThanOrNull(...)完成转换} else if ( query[key] query[key] instanceof LessThanOrNull tableColumnMetadata ) { query[key] QueryHelper.lessThanOrNull( (query[key] as LessThanOrNullCompareType).toString() as any, ) as any; }而 QueryHelper.ts 中的lessThanOrNull会生成一段带参数绑定的原始 SQL 片段CaptureSpan() public static lessThanOrNullT extends number | Date( value: T, ): FindWherePropertyany { const rid: string Text.generateRandomText(10); return Raw( (alias: string) { return (${alias} :${rid} or ${alias} IS NULL); }, { [rid]: value, }, ) as FindWherePropertyany; }最终生成的 WHERE 条件即为(字段 :随机参数 or 字段 IS NULL)其中参数通过随机占位符绑定既避免了 SQL 注入又完整实现了小于或为空的双分支语义。5.2 分析数据库ClickHouse路径当查询作用于 OneUptime 的分析型数据如指标、日志、追踪数据时SQL 由 Common/Server/Utils/AnalyticsDatabase/StatementGenerator.ts 生成。其对LessThanOrNull的处理为} else if (value instanceof LessThanOrNull) { whereStatement.append( SQLAND (${columnRef(key)} ${{ value: value, type: tableColumn.type, }} OR ${columnRef(key)} IS NULL), ); }注意ClickHouse 路径生成的比较运算符是小于等于而 TypeORM 路径是严格小于。从源码结构看这是两条存储路径在实现上的既有差异使用分析型数据时如需小于等于语义可以依赖该行为但若你的场景对边界极其敏感建议结合 Statement.ts 中的值绑定逻辑自行验证。此外分析数据库还支持对 Map 列内的数值键执行LessThan、LessThanOrEqual等比较过滤见 StatementGenerator.ts为指标标签类数据提供了同样的过滤能力。六、与相关数据类型的对比LessThanOrNull 属于 OneUptime 查询过滤器家族的一员理解它与相邻类型的关系有助于正确选型。以下对比均以当前仓库的代码示例与类型实现为准数据类型匹配语义代码示例类型实现LessThanfield value严格小于LessThan.mdLessThan.tsLessThanOrEqualfield value小于等于LessThanOrEqual.mdLessThanOrEqual.tsLessThanOrNullfield value OR field IS NULLLessThanOrNull.mdLessThanOrNull.tsGreaterThanOrNullfield value OR field IS NULLGreaterThanOrNull.mdGreaterThanOrNull.tsEqualToOrNullfield value OR field IS NULLEqualToOrNull.mdEqualToOrNull.tsIsNullfield IS NULLIsNull.mdIsNull.tsNotNullfield IS NOT NULLNotNull.mdNotNull.ts选用建议只想排除严格小于的普通比较 →LessThan边界需要包含等于 →LessThanOrEqual需要把从未写入过该字段NULL的记录也纳入结果 →LessThanOrNull只关心字段为空本身 →IsNull。另外在文档渲染层面这些类型在 App/FeatureSet/APIReference/Utils/DataTypes.ts 中统一注册LessThanOrNull对应的文档路径slug为less-than-or-null其官方描述与详情页数据保持一致{ name: LessThanOrNull, path: less-than-or-null, description: A query filter that matches objects where a field is less than the specified value or is null., },七、测试验证行为边界有据可查LessThanOrNull 的序列化与反序列化行为由单元测试覆盖见 Common/Tests/Types/Database/LessThanOrNull.test.ts。测试用例完整验证了构造与取值new LessThanOrNull(42)后value返回 42value属性支持 get/set字符串表示toString()对数值返回42JSON 序列化toJSON()返回{ _type: LessThanOrNull, value: 42 }且value携带原始数值而非字符串JSON 反序列化合法的{ _type: LessThanOrNull, value: 42 }可成功还原对象异常路径_type不匹配时抛出BadDataException拒绝无效输入Date 支持value可以接受Date类型。此外Common/Tests/Types/Database/CompareOperatorWireSerialization.test.ts 等测试还覆盖了比较型操作符在 HTTP 传输链路上的序列化行为进一步印证了toJSON使用原始值序列化以保持 Date 精度的设计。八、API Reference 文档系统如何渲染该类型你看到的这份示例并非静态手写页面而是由 API Reference 服务动态组装而成DataType.ts 通过LocalFile.read读取App/FeatureSet/APIReference/CodeExamples/DataTypes/LessThanOrNull.md并用LocalCache.getOrSetString做缓存将代码示例注入页面数据DataTypeDetail.ts 提供类型描述、属性表与 JSON 示例服务端通过 EJS 视图位于 App/FeatureSet/APIReference/views渲染为/reference/less-than-or-null文档页与DataTypes.ts中的 slug 一一对应。这意味着如果你在 OneUptime 的 API 文档站上查看该页面示例区域的 JSON 与本文开头的内容同源当需要扩展文档时修改对应.md示例文件即可本文仅作阅读说明不涉及仓库改动。结语LessThanOrNull 虽然只是 OneUptime API Reference 中一个仅 8 行的 JSON 示例但它背后串联起了查询 DSL 判别器 → 共享类型系统 → 服务端查询转换 → 多数据库 SQL 生成 → 单元测试验证的完整链路。掌握了它的语义field value OR field IS NULL、请求格式_typevalue与底层实现你就能在 OneUptime 的 API 查询、Dashboard 过滤器乃至监控阈值场景中正确处理小于某值或尚未赋值这一类容易被三值逻辑坑掉的需求。配合 LessThan、LessThanOrEqual、GreaterThanOrNull 等同族类型你可以精确组合出覆盖任意边界条件的查询表达式。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考