fix(driver-memory): analytics 面的 $notContains 编译成真正排除行的谓词,而不是不约束任何行的裸 {$not: 'x'} (#5374)

[os-zhuang]

Fixes #5374

MemoryAnalyticsService 把每个 cube 算子映射成一个 mingo 算子的名字,调用点再把这个名字填成 matchStage[field] = {[name]: comparand}。这个形状只能表达「拿这个字段和这个值比」,别的都表达不了 —— 于是那两个需要包装比较数的算子被硬塞了进去。

notContains → '$not' 编译出 {name: {$not: 'et'}}。mingo 的 $not 期望正则或算子表达式,给它一个裸标量时它不构成约束,所以谓词生成了、在管线里看得见、然后放过了全表:3 行,而 find() 是 2 行。对作者而言,一个「生成了但不起作用」的谓词和一个正确的谓词完全不可区分 —— 与 #3948 同一个放大方向,只是第三次从另一个地方到达。

这也是同一张面上第三个独立的层:#5345 裁的是没有映射的算子,#5373 裁的是比较数编码,这一条是有映射但指向了错的目标。#5431 没有让它变小:那个调用点现在收到的是真实值而不是字符串化的值,但那与算子层做了什么正交。

采用的路线

issue 给了两条:调用点包装,或者让映射表返回一个结构而不是算子名。选了后者 —— issue 本身倾向它,代码也确实支撑得起。

CUBE_OPERATOR_TO_MONGO_PREDICATE 每个算子持有一个 builder,返回整个 {$op: …} 对象。于是 notContains 可以说 {$not: {$regex: …}},而「这个算子需要一个结构,可表里只放得下一个名字」这一类问题消失了,而不只是这一个实例。调用点原本为 $in / $nin / $lte / $exists 长出来的那串 if,现在都是这张表里的普通行。

实测(issue 的 3 行固定数据,analytics vs find())

where	修复前	修复后	find()
{name: {$notContains: 'et'}}	3	2	2
{name: {$notContains: 'a'}}	3	0	0
{name: {$contains: 'a.p'}}	1	0	0
{name: {$contains: 'ALPHA'}}	0	1	1
{name: {$notContains: 'ALPHA'}}	3	2	2
{made_at: {$contains: '(完整 ISO)'}}	1	0	0
{code: {$in: []}}	3	0	0
{code: []}	3	0	0

同一调用点上另外三处,一并关掉了

不是扩范围 —— 要写出一个正确的 notContains,这三条每一条都必须先裁掉:

• contains 的比较数是原样进去的。 算子映射本身没错,但比较数既没转义(. 变成了通配符)也没折叠大小写,而 live query path 是 escapeRegex + /…/i。只修 notContains 而不管这个,两者会以一种新的方式不互补 —— alpha 会同时出现在两边的答案里。所以子串规则改成向 driver 借(新增窄接口 filterSubstringPattern,与 filterComparandStorageForm 并列),而不是在这里重新推导一遍({ field: {} }(零个操作符的字段约束)在同仓有三个答案:driver-sql 组合子内 TRUE、顶层抛 INVALID_FILTER、formula/driver-memory FALSE #5240)。
• 不是比较数的操作数也走了存储形式转换。 于是在声明为 datetime 的列上,$contains 的模式串本身被改写成了 canonical 形式,然后匹配上了 find() 匹配不到的行。builder 的入参因此带两份列表,与 normalizeFieldOperators 做的是同一个切分(driver-memory / driver-mongodb：Field.datetime 无单一存储形态，跨类型比较恒 false —— #3912 的非 SQL 版 #4047)。
• 调用点的 values.length > 0 守卫让空 $in 一个谓词都不生成,直接放大到全表。一个「取整个列表」的算子没有什么可守的。

issue 里标为「未实测」的两条,已经裁了

• 'inDateRange': '$gte':今天什么都编译不出来。没有任何 MONGO_TO_CUBE_OPERATOR 条目降级到这个名字,timeDimensions 走的是 Stage 2、根本不经过这个函数,而两个出口都只消费 normalizeFilters 的输出。所以它是死的 —— 并且万一被走到还是错的(用单边 >= 回答一个双端区间,这一点它自己的注释也承认了 "Will need special handling")。删掉了,同时删掉旁边同样是死的、并且方向反了的 'notSet': '$exists'。
• opMap[operator] || '$eq':出于同样的理由不可达 —— 但只是在有人拓宽词表之前,而 driver-memory 的 analytics 面静默丢弃大半个 filter:$or/$not 整条丢,$between/$startsWith/$null/$regex 因无 cube 映射而丢 —— 聚合结果被放大 #5345 恰恰刻意把拓宽做成了对 MONGO_TO_CUBE_OPERATOR 的一行编辑。所以不只是删掉:那张表现在是 as const,谓词表的键类型是从它派生出来的算子 union,于是那一行拓宽编辑编译不过,直到对应的谓词写出来为止。剩下的那个 throw 是全域性的兜底(totality floor),不是 fallback。

这一点是本 PR 长期价值的所在:兜底不再是「不可达」,而是「不必要」—— 全域性被证明了,而不是被防守。对 AI 写的元数据尤其重要:宽容的消费端正是 AI 生成的错误藏身并繁殖的地方。

测试

放在共享的 conformance 文件里,紧挨着 #5345 的 shape 表和 #5373 的比较数类型表,作为第三条轴,持有同一个不变量:与 find() 一致,或者拒收,绝不给出第三个更安静的答案。

外加「declared = enforced」那一半:ANALYTICS_FILTER_CAPABILITIES 声明的每一个算子都被驱动着走两条路并必须一致,且探针必须至少排除一行(否则「一致」什么也证明不了 —— 那正是本 bug 的形状)。往词表里加算子却没有可用的降级,现在会在这里失败,而不是发布一个安静的错数字。

只回退源码改动(保留测试),新断言失败 14 条:

 × $notContains excludes the rows that contain the comparand
 × a $notContains that matches every row selects none of them
 × $contains treats a metacharacter as a literal
 × $contains is case-insensitive, as the live path is
 × $notContains is case-insensitive, as the live path is
 × $contains matches a mixed-case comparand
 × $contains does not rewrite its pattern into a datetime storage form
 × $notContains does not rewrite its pattern either
 × $notContains over a column holding nulls
 × an empty $in selects nothing
 × an empty implicit-equality list selects nothing
 × $contains and $notContains partition the table for every comparand
 × every operator this face DECLARES compiles to a predicate that agrees with find()
 × the emitted $match wraps the negation around a pattern instead of a bare scalar
 Tests  14 failed | 74 passed (88)

各门实际输出:

pnpm --filter @objectstack/driver-memory typecheck   -> tsc --noEmit, 无输出
npx eslint packages/plugins/driver-memory/src        -> LINT OK
pnpm --filter @objectstack/driver-memory test        -> Test Files 17 passed (17) / Tests 512 passed (512)
pnpm --filter @objectstack/service-analytics test    -> Test Files 47 passed (47) / Tests 745 passed (745)

packages/runtime 的 suite 在本 worktree 里因为工作区依赖未构建而整文件 import 失败(Failed to resolve entry for package "@objectstack/objectql" 等)。把本改动 stash 掉后失败完全相同,与本 diff 无关。

范围之外,已单独立项

• driver-memory analytics 面:同一字段上的多个算子互相覆盖,{qty: {$gte:150, $lte:250}} 只剩最后一个 —— 区间塌成单边,结果被放大 #5440 —— 同一字段上的多个算子互相覆盖({qty: {$gte:150, $lte:250}} 取到 [1,2],find() 取到 [2])。在 $match 组装层,本 PR 之后依然完整存在;正确的修法需要一份等价于 live path _multiRegex → $and 的提升,是独立的一块。
• driver-memory analytics 面:flattenFilterCondition 对所有算子一律摊平数组比较数,{qty: {$eq: [100]}} 变成 $eq: 100(find() 取 0 行,analytics 取 1 行) #5442 —— flattenFilterCondition 对所有算子一律摊平数组比较数,{qty: {$eq: [100]}} 变成 $eq: 100(find() 0 行,analytics 2 行)。在更上游的降级层。
• driver-memory analytics 面的 generateSql 把 contains 回显成 LIKE 'et'(没有 % 通配符)—— 回显的是等值匹配,执行的是子串匹配 #5444 —— generateSql 把 contains 回显成 LIKE 'et'(没有 % 通配符),回显的是等值匹配、执行的是子串匹配。作为 driver-memory analytics 面的 generateSql 对 in/notIn/set/notSet 输出错误 SQL:回退成 = 且只取第一个值($in: ['100','200'] → WHERE code = '100') #5433 的 sub-issue,因为修复落点完全在 driver-memory analytics 面的 generateSql 对 in/notIn/set/notSet 输出错误 SQL:回退成 = 且只取第一个值($in: ['100','200'] → WHERE code = '100') #5433 的完成范围内(同一个 operatorToSql + 同一个 WHERE 构建循环)。

operatorToSql 与 generateSql 一个字节都没动 —— #5433 是同一类缺陷在另一个出口上,刻意不打包在一起。packages/spec、service-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 5, 2026 11:55am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/driver-memory.

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

• content/docs/data-modeling/drivers.mdx (via @objectstack/driver-memory)
• content/docs/deployment/vercel.mdx (via @objectstack/driver-memory)
• content/docs/getting-started/glossary.mdx (via @objectstack/driver-memory)
• content/docs/kernel/services-checklist.mdx (via @objectstack/driver-memory)
• content/docs/permissions/authentication.mdx (via @objectstack/driver-memory)
• content/docs/plugins/index.mdx (via @objectstack/driver-memory)
• content/docs/plugins/packages.mdx (via @objectstack/driver-memory)
• content/docs/protocol/objectql/query-syntax.mdx (via @objectstack/driver-memory)
• content/docs/releases/implementation-status.mdx (via @objectstack/driver-memory)

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.