fix(service-analytics)!: 作者的 where 也 NULL-safe —— $not 下推守卫、{$not:{}} 为零行、{} 析取项吸收 $or (#5325)

[os-zhuang]

Fixes #5325

filter-normalizer.ts 的 buildNode 是 service-analytics 里第二份同缺陷拷贝。第一份(read-scope-sql.ts 的 compileNode,RLS 读作用域)由 #5297 / PR #5326 修好并已合入;这一份编译的是 dashboard widget / dataset 作者自己写的 where,两者是各自独立的函数,所以那一单落地后同样三条仍然在。

现场核对(STALE-PREMISE)

issue 正文写于 26e1029f5 + #5297 的分支。worktree 基于 origin/main,开工后又同步到 c7406b0ec(含 #5319、#5329)。issue 引用的现场逐条仍然成立:

issue 引用的现场	核对结果
buildNode 的 $not 分支 if (inner) children.push(…)	✅ 原样,{$not:{}} 因此整条消失
$and/$or 的 .filter((n) => n !== null)	✅ 原样,{} 析取项被丢
三处 NOT (${inner})	✅ 三个编译器各一处,位置与正文一致
NormalizedFilterNode 只有 leaf | and | or | not	✅ 无 FALSE 表示法
FILTER_LOGIC_CASES 不含 null case	✅ 该表 TSDoc 明写「Nothing here exercises null handling」,所以现有门禁看不见这三条

期间落地的 #5329(#5158 拍板 C 第 2 步)只动 engine 入口与四个驱动,不与本单冲突 —— 但暴露了 analytics 是它漏掉的第五道门,已单独记录(见范围外清单)。

实测(sql.js,fixture 与 driver-sql 的 sql-driver-not-null-safe.test.ts 逐行相同)

行 3、4 的 stage 为 NULL,行 3 的 amount 为 NULL,行 4 的 owner 为 NULL。断言打到 NativeSQLStrategy.generateSql / .execute 这一层(#5297 的教训:缺陷常在编译器与调用方的接缝处)。

where	改前实测	改后实测	应为(JS 家族 / #5296 后的 driver-sql)
{ $not: { stage: 'won' } }	2	2,3,4	2,3,4 ✅
{ $not: { stage: { $in: ['won'] } } }	2	2,3,4	2,3,4 ✅
{ $not: {} }	1,2,3,4	零行	零行 ✅
{ $or: [{ stage: 'won' }, {}] }	1	1,2,3,4	1,2,3,4 ✅
{ $not: { $or: [{stage:'won'},{owner:'u1'}] } }	2	2,4	2,4 ✅

「改前」一列是把三个源文件 git stash 掉后由同一批用例实测出来的,与 issue 正文的「实测行」逐条吻合。

两条裁定的实现

裁定 1 —— 守卫加在 buildNode(normalizer)

nullSafeNegationOperand 重写 $not 的操作数(仍是一个 FilterCondition),把守卫下推到叶子,极性逐算子决定;buildNode 再照常编译它,没有新的分支。

因此守卫是结构而不是 SQL 技巧:{$not: {stage: 'won'}} 的操作数变成 {$and: [{stage: {$null: false}}, {stage: 'won'}]},这份结构经 filterNodeToCondition 交给 ObjectQL 引擎后在任何驱动上都成立。

双重加守卫已用执行验证幂等,不只是推演:测试里 compileScopedFilterToSql(同包另一个 FilterCondition 消费者,#5297 已是 NULL-safe)充当引擎,对本路径已经守卫过的条件再守卫一次,执行后取到的行与 raw-SQL 路径逐行相同(2,3,4),SQL 里出现两层 IS NOT NULL。

裁定 2 —— NormalizedFilterNode 加布尔常量 kind

| { kind: 'const'; value: boolean }。TRUE 保留既有拼法(null = 无约束 = AND 单位元),FALSE 需要一个节点因为它必须活着进 WHERE。四个消费者各自实现:

消费者	FALSE	TRUE
native-sql-strategy.compileFilterNode	1 = 0	1 = 1
objectql-strategy.filterNodeToCondition	{$not: {}}	null(无约束)
objectql-strategy.renderFilterNodeSql(回显)	1 = 0	1 = 1
filter-normalizer.collectFilterLeaves	[]	[]

1 = 0 是仓里两侧已有的拼法(read-scope-sql 的 FALSE_CLAUSE、driver-sql 的 applyFalseConstant,#5134),不绑值、每种方言都合法;引擎路径的 {$not: {}} 是 driver-sql / formula / driver-memory 参考匹配器早已钉住的零行写法,没有另造第二种。

params 绑定错位隐患 —— 三个编译器逐个核查

结论:改前三个都不会发生;但本次新增的「TRUE 吸收 OR」规则会引入它,所以两个 SQL 编译器都按 #5297 的修法处理了。

• 改前为什么不会:每个返回 null 的分支都在 push 任何值之前就决定了 —— buildFilterClause / buildFilterClauseSql 的空值判断全在函数开头,not 的 inner === null 由归纳法保证内层没 push 过,and/or 的 parts.length === 0 同理。被 .filter(Boolean) 丢掉的兄弟子句一定是零绑定的。
• 本次为什么会:吸收规则要丢弃的是一个已经编译、已经绑定的兄弟分支({$or: [{stage:'won'}, {}]} 里 'won' 已进 params)。直接返回 null 会让它留在 params 里没有 $n 消费,把后面每个占位符错位到别人的值上。
• 修法:两个 SQL 编译器进入组合子时记下 params.length,吸收时截断回去;native-sql-strategy 连 joins 一起还原(丢弃的分支可能注册过 LEFT JOIN,留着会在 to-many 关系上放大行数)。不变量写进 TSDoc:返回 null 的调用必须让 params 与进入时逐字节相同,归纳法对每种节点成立。
• filterNodeToCondition 不绑值(产出的是 FilterCondition),无此形状 —— 但它同样有「丢分支」的 bug,已按同样的语义修。

单独 pin:binds NOTHING — the discarded branch takes its comparand with it、keeps the rest of the filter aligned when a later predicate follows(断言 owner = 'u1' 绑到 $1 而不是 $2)、以及回显路径的同名两条。

三个编译器各自的改动

1. native-sql-strategy.compileFilterNode —— 新增 const 分支;not 的空内层从 null 改为 1 = 0(NOT TRUE ≡ FALSE);组合子改为逐子节点循环 + paramBase / joinBase 截断,or 遇到 null 子节点整组返回 null。
2. objectql-strategy.filterNodeToCondition —— 新增 const 分支;not 的空内层从 null 改为 {$not: {}};or 的 .filter(Boolean) 改为「有 null 分支即整组无约束」。
3. objectql-strategy.renderFilterNodeSql —— 与 1 相同的三条,加 paramBase 截断。回显必须复现执行:一条跑成零行、却回显「没有 WHERE」的语句,会让来查「为什么这张图是空的」的人拿到一条返回全表的 SQL。

与本文件算子集的差异(参照实现 vs 这里)

守卫表按 sql-driver.ts / read-scope-sql.ts 抄,差异全部来自本文件自己的 emitter(「每个 guard 匹配自己的 emitter」是 sql-driver.ts 早就写明的不变量):

算子	本文件的 emitter	与参照实现的差异
$null / $exists	按恒等读(=== true / === false),fieldLeaves 就是这么读的	read-scope-sql 按真值读。两者都编译成 null 谓词 → 都是 null-total → guard 'none',不影响结果
$between	lower 成 gte + lte 两个正向比较	driver-sql 的表里没有这个算子;两个正向比较取同一个默认极性
$in: [] / $nin: []	布尔常量(本次新增)	与 read-scope-sql 的 FALSE_CLAUSE / 1 = 1 对齐 → null-total → guard 'none'
$eq / $ne 的 null 比较数	没有 read-scope-sql 的 value === null 两条 arm	因为本文件把 null 比较数 stringifyForCube 成 '',{$eq: null} 在这里是普通值比较。这本身是缺陷,本单不裁定,已单独记录为 #5332,并刻意不在测试里钉住它的行集
$notContains	跟随 formula(NULL 满足)	与 driver-sql / read-scope-sql 一致,不对已归档的分歧投票

本次改动逼出来的两条(不是顺手扩范围)

• 空集合 {$in: []} / {$nin: []} 改为布尔常量。 不改的话 NULL-safe 的 $not 会回归:{$not: {a: {$in: []}}} 从「全部行」变成「只有 NULL 行」,因为被丢掉的合取项在否定里会翻转整条的答案(read-scope-sql 的对应用例钉的是「全部行」)。顺带修掉一条独立的静默放宽:{stage: {$in: []}} 此前画全表。
• 零个操作符的字段约束 {a: {}} 改为拒收,按 { field: {} }(零个操作符的字段约束)在同仓有三个答案:driver-sql 组合子内 TRUE、顶层抛 INVALID_FILTER、formula/driver-memory FALSE #5240 已拍板、fix(driver-sql,driver-memory,formula)!: { field: {} } 四个后端一律拒收 —— 零个操作符的字段约束不再有三个答案 (#5240) #5327 已在 driver-sql / driver-memory / formula 落地的口径。它此前不产出任何 leaf,而「不产出」就是常量 TRUE —— 在新的吸收规则下 {$or: [{a: {}}, {b: 2}]} 会从 b = 2 放宽成全表。三个可能答案里必须选一个,跟随已有拍板而不是另造第三个。

非对象的 $not 操作数 / $and·$or 分支元素同样改为拒收:{$not: null} 此前整条消失(等于不筛),而在吸收规则下把它读成 TRUE 会放宽到全表 —— 垃圾输入的两种读法都不正当,read-scope-sql 拒收同样的形状。

测试

新文件 packages/services/service-analytics/src/__tests__/filter-normalizer-not-null-safe.test.ts,48 条,全部在 sql.js 上取行,不只断言 SQL 字符串:

• 五条实测行逐条断言「应为」那一列(经 NativeSQLStrategy.execute);
• {$not:{}} / {} 析取项 / 常量的组合与嵌套,含 generateSql 层的 WHERE 与 params 断言;
• 逐算子的 NULL 极性($ne / $nin 不被放宽这条单独钉住);
• objectql 路径:filterNodeToCondition 的产出经 compileScopedFilterToSql 执行取行,与 raw-SQL 路径逐条比对;双重加守卫幂等单独钉住;
• renderFilterNodeSql 回显 SQL 的常量、吸收、守卫、占位符对齐;
• 空组合子在同仓有两个对立答案:五个后端归约成布尔单位元,service-analytics 的两个编译器 fail-closed 抛错 —— #5239 的一致性表四条因此进不了表 #5322 钉在抛错这一侧:$and: [] / $or: [] 在 $not 内外都仍然抛 non-empty array;
• { field: {} }(零个操作符的字段约束)在同仓有三个答案:driver-sql 组合子内 TRUE、顶层抛 INVALID_FILTER、formula/driver-memory FALSE #5240 拒收、非对象操作数拒收、未知算子仍然抛。

Test Files  44 passed (44)
      Tests  639 passed (639)          # 全包回归,新增 48 条

反向验证(git stash 掉三个源文件后跑新用例):Tests 36 failed | 11 passed (47),五条实测行的失败原文:

× `{$not: {stage: "won"}}` returns the NULL-stage rows — was `2`
    AssertionError: expected [ '2' ] to deeply equal [ '2', '3', '4' ]
× `{$not: {stage: {$in: ["won"]}}}` returns them too — was `2`
    AssertionError: expected [ '2' ] to deeply equal [ '2', '3', '4' ]
× `{$not: {}}` matches NO row — was the whole dataset
    AssertionError: expected [ '1', '2', '3', '4' ] to deeply equal []
× `{$or: [{stage: "won"}, {}]}` matches EVERY row — was `1`
    AssertionError: expected [ '1' ] to deeply equal [ '1', '2', '3', '4' ]
× `{$not: {$or: […]}}` excludes a NULL row whose OTHER branch matches — was `2`
    AssertionError: expected [ '2' ] to deeply equal [ '2', '4' ]

tsc --noEmit:7 条 error,与改动前 git stash 后的基线逐条相同(全部在既有测试文件里,与本次无关)。eslint packages/services/service-analytics/src --no-inline-config:无输出。turbo run build --filter=@objectstack/service-analytics:成功。

本地跳过/CI 才跑的盲区:无。 grep -rn "skipIf\|describe.skip\|it.skip\|test.skip\|todo(" 在 service-analytics/src 下零命中,44 个测试文件全部在本地真实执行。消费面静态清点:grep -rn "NormalizedFilterNode" 全仓只命中 native-sql-strategy.ts、objectql-strategy.ts、filter-normalizer.ts 三个文件,即本 PR 覆盖的三个编译器 + collectFilterLeaves,无第四个消费者。

与 #5297 的关系

同一组缺陷的第二份拷贝,同一套修法(常量拼法、守卫下推到叶子、每个子节点先编译进自己的 bind 缓冲/可回滚),但落点不同:#5297 修的是 RLS 读作用域(越权面),本单修的是作者的 widget filter(数值面)。两份实现现在对「一个 filter 是什么意思」给出同一个答案,filter-normalizer.ts 的 TSDoc 声明的「两条 SQL 产出路径不得漂移」因此成立。

明确不在范围

• ⛔ 空组合子在同仓有两个对立答案:五个后端归约成布尔单位元,service-analytics 的两个编译器 fail-closed 抛错 —— #5239 的一致性表四条因此进不了表 #5322($and: [] / $or: [] 空组合子)—— 独立裁定,本单只加用例把它钉在抛错这一侧。
• ⛔ packages/spec/** —— FILTER_LOGIC_CASES 补 null case 归 spec 车道([spec] FILTER_LOGIC_CASES 补空组合子的布尔单位元四条 —— 需与 driver-mongodb 的单位元归约同时落地 #5239)。时序建议:本 PR 早于 [spec] FILTER_LOGIC_CASES 补空组合子的布尔单位元四条 —— 需与 driver-mongodb 的单位元归约同时落地 #5239 落地,否则 native-sql-filter-logic-conformance.test.ts 会因本文件未修而单独变红。
• ⛔ read-scope-sql.ts、packages/plugins/**、packages/formula/** —— 一行未改,只读作参照。
• ⛔ content/docs/releases/** —— 一行未改;变更记录只走 .changeset/*.md。

范围外发现(已单独立 issue,unassigned)

• 分析查询的 {field: {$eq: null}} / {$ne: null} 编译成 col = '' / col != '',与同文件里 {field: null} 的 IS NULL 自相矛盾 #5332 —— {field: {$eq: null}} / {$ne: null} 在本文件编译成 col = '' / col != ''(stringifyForCube(null) → ''),与同文件 {field: null} 的 IS NULL 自相矛盾,也与 read-scope-sql / driver-sql 分叉。本 PR 的守卫表因此刻意不含那两条 arm,并注明由该单裁定;测试也刻意不钉它的行集。
• /analytics/sql 回显的 SQL 丢掉 $startsWith / $endsWith 谓词:回显比实际执行的查询更宽,无法复现结果 #5333 —— /analytics/sql 回显的 SQL 丢掉 $startsWith / $endsWith 谓词(SCALAR_SQL_OPS 缺这两个,落到 return null),回显比实际执行更宽,无法复现结果。
• analytics 是 #5158 拍板 C 漏掉的第五道门:where 为数组(FilterArray 糖)时被 normalizeAnalyticsFilterTree 静默丢弃,图表画全表 #5334 —— normalizeAnalyticsFilterTree 对数组 where(FilterArray 糖)return null 静默丢弃 → 画全表。fix(objectql,driver-sql,driver-memory,driver-mongodb)!: FilterArray 在 engine 门下沉,四驱动数组方言删除 (#5158 拍板 C 第 2 步) #5329([engine] driver-sql 编译 spec 未声明的「数组 where 方言」—— 与 Turso remote 的拒收分叉,需一次定调(接纳进 spec 或响亮弃用) #5158 拍板 C 第 2 步)刚把 FilterArray 在 engine 六入口下沉、四驱动改拒收,analytics 是漏掉的第五道门。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01Pbu27iNUfQCHeuS551Rqo7

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 4, 2026 11:39pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-analytics.

8 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/api/data-api.mdx (via @objectstack/service-analytics)
• content/docs/api/index.mdx (via @objectstack/service-analytics)
• content/docs/kernel/services-checklist.mdx (via @objectstack/service-analytics)
• content/docs/permissions/sharing-rules.mdx (via @objectstack/service-analytics)
• content/docs/plugins/packages.mdx (via @objectstack/service-analytics)
• content/docs/releases/implementation-status.mdx (via @objectstack/service-analytics)
• content/docs/releases/v17.mdx (via @objectstack/service-analytics)
• content/docs/releases/v9.mdx (via @objectstack/service-analytics)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.