本页记录 SQL 录入功能:支持的 SELECT 子集、解析器与解析器,以及把语句转换回可移植查询图的应用路径。阶段 A-D 已实现;阶段 E 推迟。
范围: MAD/Source/sql/ 中新增的解析器/解析器/编译器、MADocument 上的应用路径、
MADDesigner 中的 SQL 浮出、持久化的源文本(§8,它增加了存储的第一次
版本化步骤),以及锁定这一切的测试。
日期: 2026-10-22,读取于 cf0fe3acd;2026-10-22 因持久化决策(§8)修订。
状态: 已实现——阶段 A–D 于 2026-10-22 落地,并以 c48a39fb7 合并进 master
(内部任务队列 §16)。阶段 E(§9)仍推迟;§8.1–§8.2 载有按实现所作的修订。
今天构建查询的唯一方式是可视化设计器:选择表、逐字段联接它们、添加筛选器、添加分组—— 全部通过标签页 UI 完成。用户想要第二种入口:
“…a user could hit a button and it flips around and shows a multiline text view where they can paste the SQL… when that SQL is saved, it manually creates the query in the backend of the report… it does everything it already would do with the user selecting all the details… the software still recognizes what fields are used what joins are used what tables are used, and it completely setups the document in the proper way, and then allows the user to even use the query designer with the fields entered by the standard query (if they wish to).”
因此:粘贴的 SQL 会被编译进文档的查询模型(Rptq 对象图),
经由可视化设计器所调用的完全相同的工厂。应用之后,可视化查询
设计器、可视化画布和报表设计器都会像查询是手工构建的那样看待它——
且用户可以继续在那里编辑。必须有一个校验阶段。
Rptq 图文档的查询以普通 Rptq* 对象的形式存在于可移植存储中
(MAD/Source/rptq/);MADModel* 层是它们的只读视图
(MADModel_Layer.md)。导入器只写 Rptq 行,别无其他。
RptqQuery(MAD/Source/rptq/autogen/RptqQuery.h:30-34):hasQueryTables、
hasQueryLinks、hasQueryPredicate(注意是单数名称)、hasQueryGroups。RptqQueryTable——一个架构表引用加一个别名;别名是计算出来的:
第一份副本用架构表名,之后为名称 + drop index
(Customer、Customer0、……——MADModelQueryTable.m:119-129)。RptqQueryField——两个 id:inQueryTable + databaseSchemaField。每个查询表的每个字段都会有一行
(添加表流程每个架构字段创建一行,
MADQueryViewController.m:762-770)。RptqQueryLinks——一个联接:hasLeftField/hasRightField(各为一个 RptqQueryField)、
type(MADLinkType,MADQueryLinkType.h:inner / equi / natural / cross / left / right
/ full outer)。每个联接恰好一对字段;生成器总是发出 ON l = r
(MADQueryFull.m:366-380)。RptqQueryPredicate——comparson(MADPredicateOperator:=、<>、>、>=、<、
<=——MADPredicateOperator.h、RptqQueryPredicate+Extras.m:245-265),加上一个
左侧/右侧,要么是 RptqQueryField,要么是带类型的值字符串
(leftFieldID/rigthFieldID)。所有谓词都以 AND 连接,每个写成 (left op right)
(MADQueryPredicate.m:43-93)。无 OR、无 LIKE、无 IN、无函数。RptqQueryGroup——hasField、sort(MADSortOrder)、weight 和 hasSection:
报表的分组头/尾带区(RptqQueryGroup.h:24-29)。模型不持有什么——导入器必须尊重的边界:
MADQueryActiveQueryFields.m:37-97、MADQuerySelectExpressionActiveFields.m)。RptqQueryGroup.sort)。MADQueryFull 从模型构建执行的 SQL
(SQLOnlyActiveFields:managedObjectContext:error:,MADQueryFull.m:143-273):
SELECT 部分来自驱动,然后是活动字段,按列别名排序,写出时
不带 AS:"Table0"."Field"(MADQuerySelectExpressionActiveFields.m:32-38, 46-53)。FROM——对联接图做 DFS:tableName <connector> queryAlias,然后
每个联接 LEFT OUTER JOIN tableName <connector> queryAlias ON l.field = r.field
(MADQueryFull.m:275-426,联接文本来自 RptqQueryLinks SqlForLinkType:,
RptqQueryLinks+Extras.m:76-86)。WHERE——以 AND 连接的谓词三元组(MADQueryPredicate.m)。GROUP BY/ORDER BY——分组和排序在
.maddb 缓存上应用(MADParameters+QueryCacheAggregate、MADQueryCacheSelectGroupKeys)。LIMIT 子句。因此导入器的契约是:粘贴的语句恰好在它能成为某个模型的 MADQueryFull 输出时
被接受。 这正是往返诚实的原因——SQL 浮出的 View 侧显示从导入模型重新生成的 SQL,
读起来就像用户所粘贴的。
MADOperationRefresh.m:60-172:用操作依赖提供的凭据连接,
在主队列上构建 SQL(存储上下文归主队列所有——BUGS.md),然后
[database executeSQL:fieldKeys:onConnection:intoResultTable:withError:]
(MADDatabaseProtocol.h:33)和 dataTableMakeCache。校验探查是同样的
操作形态,减去缓存构建。
写入 Rptq 行并保存就够了;MADModel* 层通过存储通知把变更镜像进
UI(MADModel_Layer.md §3.3)。要调用的工厂,逐字取自
今天的 UI 代码:
[RptqQueryTable newQueryTableForSchemaTable:database:forManagedObjectContext:]
然后每个架构字段一个 [RptqQueryField newQueryField:context],接线到该表,
表加入 query.hasQueryTables,保存(MADQueryViewController.m:744-799)。[RptqQueryLinks newQueryLinksWithLeftField:rightField:joinType:managedObjectContext:]
然后 [document.activeDocumentModel addQueryLink:link],保存
(MADQueryLinkBuilderController.m:112-122)。[RptqQueryPredicate newQueryPredicateFactoryWithLeftFieldID:…] /
…WithLeftValue:… 变体(MADQueryAddPredicateController.m:142-162、
RptqQueryPredicate+Extras.h:20-39)。[document addQueryGroupWithQueryField:andSortOrder:]
(MADocument.m:728-792)。这一个调用创建分组行以及报表的分组
头/尾带区以及它们的带区布局管理器——“completely sets up the
document”,为 GROUP BY 免费做到。removeGroupWitObjectID:fromManagedObjectContext:
(MADocument.m:1130)、deleteDatafieldsRelatedToTable:inContent: 和
deleteAggregateFieldRelatedToTable:inContent:(MADocument.h:91-95),以及查询 UI 中既有的
联接/谓词移除路径。阶段 B 会盘点这些;任何缺失的
对称联接/谓词辅助方法都会在那里添加。查询构建器分栏视图控制器已有一个 barButtonItemSQL 工具栏项,它会
呈现一个只读的 MADViewControllerSQL 浮出(MADQueryBuilderSplitViewController.m:31,
106-111;MADQuery.storyboard;MADViewControllerSQL.m:27-56 显示
[doc.mainQuery SQLOnlyActiveFields:…])。该功能是同一界面的一个模式,因此
按钮、浮出和导航都已存在。
MADQueryFull 此刻从模型构建出的 SQL(今天的
浮出内容,保留为默认标签)。RptqQuery.sqlSourceText,§8);当查询从未由粘贴的 SQL 构建过时
隐藏或为空。
两个标签都是只读的——“看到你粘贴了什么,以及它变成了什么”界面。sqlSourceText 时以它作为初始内容
(用户重新编辑他们自己的文本,格式和注释保持不变),否则以生成的
SQL 为初始内容;一个 Revert to generated 按钮从生成形式重新播种。sqlSourceText(§8)。浮出关闭;查询表
列表、可视化画布和报表设计器都显示导入的结构。
设计器的字段选择器照常工作。pasted SQL
→ MADSQLTokenizer dialect-aware lexer; quotes per driver; tracks line:column
→ MADSQLParser recursive descent; produces a MADSQLStatement parse tree
→ MADSQLStatementResolver binds names to RptqDatabaseSchemaTable / RptqDatabaseSchemaField
→ [MADOperationValidateSQL] server probe, when connected (§7); never writes
→ MADSQLQueryCompiler the write plan: deletes + creates Rptq rows via the §2.4 factories
→ store save → model notifications → query UI / visualization / designer update
位置。 除探查操作和编辑器 UI 之外的一切都位于 MAD
框架中,纯 Foundation,无 UIKit——因此它能在 MAD 测试套件和 Linux
镜像中运行。新文件加入 Linux/cmake/MADSources.cmake,./Linux/build.sh 保持通过。
探查操作(需要驱动、凭据、UIKit 警报)和浮出 UI 位于
MADDesigner/Source。
新文件。 MAD/Source/sql/MADSQLTokenizer.{h,m}、MADSQLParser.{h,m}、
MADSQLStatement.{h,m}(树及其值类型:MADSQLColumnReference、
MADSQLPredicateTerm、……)、MADSQLStatementResolver.{h,m}、MADSQLQueryCompiler.{h,m}、
MADSQLCompileError.{h,m}。应用:MADOperationValidateSQL.{h,m}(镜像
MADOperationRefresh),再加上 MADViewControllerSQL 中的编辑器改动,或同一 storyboard 接缝中的兄弟
编辑器控制器。
一处小的 API 新增。 词法器需要在连接存在之前获得每种方言的标识符引用符(MySQL
反引号、T-SQL 方括号、双引号)。给 MADDatabase 添加
+ (NSString *)identifierQuoteCharacters(默认:双引号),并在
MADMySQL/MADTdsClient 中按驱动覆盖(MADPostgres 使用默认双
引号)——或者,如更偏好,在通过
MADDatabaseDriverRegistry 解析的驱动协议上添加类方法。无论哪种都是三个方法的新增。
导入器接受恰好是模型能承载的语言——一个 SELECT,任何地方都无
子查询,且每个子句都在 §2.1 的限制内:
col、tbl.col、schema.tbl.col、alias.col,
带引号或不带,加上 alias.* / schema.tbl.*。该列表被校验并用于
表/列发现,而非存储(模型没有 SELECT 列表——§2.1):每一列
都必须可解析,且限定列所命名的表必须出现在 FROM 中。表达式、
聚合、别名(AS x)和 DISTINCT 会被拒绝,并指向阶段 E(§9),
即通过合成设计器元素让粘贴的列列表成真的阶段。
输入的文本本身会逐字存储在 sqlSourceText(§8)中——校验形态
与输入文本是两回事。[schema.]name [AS alias],然后是一条链/树:
[INNER] JOIN、LEFT [OUTER] JOIN、RIGHT [OUTER] JOIN、FULL [OUTER] JOIN,每个
恰好一个等值条件 l.col = r.col(裸列、两段式或三段式 schema.tbl.col
列;无歧义时允许裸列)。
name0、name1、schema.name0 或去点形式的 schemaname0,匹配
RptqQueryTable -queryAlias)——模型自行计算
别名,无法承载重命名(Customer AS c 被拒绝:“the designer names
tables itself”)。JOIN;同一对之间的两个联接线会使别名
加倍)。NATURAL/CROSS 联接(联接模型恰好持有一对字段,
且生成器总是写 ON …),FROM/ON 中无子查询。left op right 的合取(AND),op ∈
{ =, <>, >, >=, <, <= }(MADPredicateOperator 集合),每侧是列引用
或字面量。括号仅在不会改变扁平 AND 形态之处被接受。
其他一切——OR、IN、BETWEEN、LIKE、NOT、函数、子查询——都会被
拒绝:谓词模型只以 AND 连接扁平三元组,别无其他。MADocument 辅助方法成为一个分组,该方法还会创建报表的分组带区。MADDocument.limitResultsDesignMode、MADQueryFull.limitResults)。字面量在生成时按方言处理(newSafeLiteral:,
MADDatabaseSQLProtocol.h);导入器只记录值字符串和字段的数据
类型,与谓词 UI 完全一致(MADQueryPredicate.m:74-88)。
拒绝从不静默:每一次都说明构造、子句、原因(它触及哪项 模型限制)以及行:列。
RptqDatabaseSchemaTable。
未知 → 错误“unknown table”。RptqDatabaseSchemaField:限定列必须存在于其表上;裸列必须在
整个 FROM 集合中唯一,否则“ambiguous column”。解析器输出是一个值对象计划:有序表列表、联接列表(每个联接一个 MADLinkType)、
谓词列表(MADPredicateOperator + 左/右项)、带排序顺序的分组列表。
计划在写入任何东西之前整体校验。
应用替换查询(粘贴的 SQL 就是查询——这就是该功能)。写入之前,
检查新计划不包含的每张表是否被设计器元素引用——即
MADQueryActiveQueryFields 所知的三种形态
(MADQueryActiveQueryFields.m:37-68:标签数据、聚合、条形码引用),加上任何会被删除的
分组带区。若被丢弃表的字段被引用,则中止
并给出错误,说明涉及的元素(“this field is used by … in the designer”);不删除任何东西,
不写入任何东西,旧查询仍可运行。这是导入无法做到
原子且静默的唯一情形,因此它会大声失败。
按反向依赖顺序使用 §2.4 的辅助方法:移除联接和谓词,移除
分组(通过既有的分组移除路径,它会分离其带区和布局
管理器),移除不在计划中的表(通过既有的
deleteDatafieldsRelatedToTable: 家族),然后通过 UI 所调用的相同工厂创建表 → 联接 → 谓词 → 分组。
一次保存;随后调用方把文档标脏
并自动保存,如添加表流程所做(MADQueryViewController.m:796-799)。
不触碰 UI:存储通知路径会更新模型层和两个查询界面
(MADModel_Layer.md §3.3)。编译器返回一个摘要(表 / 联接 / 谓词 /
分组数量)供浮出使用。
结构(始终,离线)。 解析 + 解析,§5–§6。错误是
MADSQLCompileError 域的 NSError,带代码、行、列和消息。当
文档的数据库不可达时,这就是全部功能。
服务器探查(当能建立连接时)。 包装语句:
SELECT * FROM (<user sql>) AS _mad_probe WHERE 1=0
派生表别名在 MySQL 中是必需的,在 T-SQL 中有效;WHERE 1=0 会被折叠,因此
探查编译查询并返回列元数据而不读取行。通过
MADOperationRefresh 形态运行它(MADOperationRefresh.m:104-162):用操作依赖的凭据连接,
存储读取编组到主队列,结果经由
驱动的 executeSQL:…intoResultTable:…,使 MADDataColumn 给出名称和类型。随后探查
捕获静态解析无法捕获的东西——服务器端名称解析(大小写敏感性、
视图、保留字)、方言差异,以及服务器自身的语法错误,这些
会带服务器消息浮现。列名/类型会与解析出的
架构字段比较,不匹配会作为警告报告,而非失败。
离线时,或凭据不可用时,探查被跳过,UI 提示 “validated by structure only.”
RptqQuery.sqlSourceText编译后的模型仍是执行的真相来源,但用户粘贴的文本
是文档的一部分:RptqQuery 上新增一个可空文本属性 sqlSourceText,
逐字保存最后一次成功应用的语句。删除用户的文字从来不是
一个选项——文档保留输入及其编译结果。用户选择了单一
属性而非历史数组(2026-10-22);修订历史以后可以作为
有序的 to-many 添加,并从当前文本回填,无数据丢失。
持久化规则:
该属性落在架构交叉检查的两侧:编译后的模型和
手工维护的 MADStoreSchema 描述符,加上 RptqQuery autogen 属性
(MAD/Source/rptq/autogen/)。MAD_FORMAT.md 的字段列表新增该列。
修订(阶段 A,2026-10-22)。 模型变更是新的 MAD 4.xcdatamodel
版本,而非就地编辑 MAD 3:已发布模型版本的哈希固定了每个
在野文档的存储元数据,编辑它会使它们成为孤儿。MAD 4 还移除了
RptqDocumentElementBarcode.barcodeBorderType 中已死的 elementID="type"(没有早于 MAD 3
的版本拥有条形码实体;BUGS.md)。
可移植存储今天没有版本化(MADStore.m 不携带 user_version pragma)。
该阶段添加该机制,刻意保持最小:
MADStoreSchema 获得一个版本常量和一个有序的迁移步骤列表。今天
该列表有一项:版本 1(在野的架构——user_version 缺失或为 0)
→ 版本 2(ALTER TABLE 添加 sqlSourceText)。MADStore 读取 PRAGMA user_version,在一个
事务中应用缺失的步骤,并写入新版本。全新存储以当前版本创建
(createSchemaSQL 已生成整个架构)。MADLegacyStoreConversion 的流程不受影响——转换后的 Core Data 文档通过同一个 MADStore 打开路径
以当前版本创建。MADStore 代码,因此现有文档在镜像中
同样打开;迁移测试也在那里运行。修订(阶段 A,2026-10-22)。 MADStoreConverter 现在以
匹配其元数据的 momd 版本打开每个遗留存储,绝不通过自动迁移:Core Data 无法
为该模型家族推断映射(条形码 elementID 冲突,BUGS.md),且
momd 当前模型不再是在野存储写入时所依据的版本。
guts 目录中随存储一起携带的元数据 plist 可以完全不动架构地
保存该文本。否决:查询数据属于存储的查询部分
(MADStorePartQuery——存储的契约是“三个部分,别无其他”,
MADStoreSchema.h:12-13),且无头引擎读取的是存储,而非 plist。
存储的已输入文本是产品地平线上由代理驱动的查询设计的天然输入面
(MAD_FUTURE.md):一个代理——或一个人——写出语句,
下面的编译器把它变成文档,sqlSourceText 保留作为记录的提示词。
严格的编译模型架构正是让这一步可逐步推进的原因:当写入者
变成代理时,编译器没有任何变化。
阶段 A——持久化源文本:存储版本化(仅 MAD;Linux 通过)。
RptqQuery 上的 sqlSourceText:编译模型 + MADStoreSchema 描述符 + autogen
属性,一次改动(否则交叉检查测试会失败)。user_version
读取/应用/写入、全新存储以当前版本创建。MADStoreSchemaTests 两侧保持通过;新增迁移测试(§10.2);
MAD_FORMAT.md 更新。验收:本阶段之前创建的文档能干净打开、获得该列、保留其 数据,并在 Linux 上往返;全新文档以当前版本诞生。本 阶段自包含——它在解析器之前且独立于解析器落地。
阶段 B——黄金测试,然后解析器(仅 MAD;Linux 通过)。
MADQueryFull 每方言确切输出的黄金 SQL 测试(§10.1)——先写,
使解析器针对真实生成器构建。MADSQLTokenizer/MADSQLParser/MADSQLStatement + 标识符引用 API(§4)。MADSQLParserTests——§5 的接受/拒绝矩阵、错误代码、行:列。验收:MADQueryFull 能发出的每个受支持构造都能解析;每个被拒绝的
构造都以带代码、带位置的错误失败;MAD 套件和 ./Linux/build.sh 通过。
阶段 C——解析器 + 编译器(仅 MAD;Linux 通过)。
MADSQLStatementResolver、带原子应用(§6)和
成功时写入 sqlSourceText(§8)的 MADSQLQueryCompiler。MADSQLQueryCompilerTests + 不动点往返测试(§10.4)。验收:应用一条语句产生与可视化设计器完全相同的 Rptq 行, 并逐字存储文本;在既有查询上应用不留下孤儿;冲突情形中止, 存储——及先前文本——不受触碰;不动点测试 通过。
阶段 D——应用(MADDesigner)。
MADOperationValidateSQL 探查、摘要视图。验收:粘贴 → 校验 → 应用后,查询设计器和可视化中显示表/联接/谓词, 报表设计器中显示分组带区,刷新运行查询;View 显示生成的 SQL 和输入的文本;关闭并重新打开文档保留 输入的文本。
阶段 E——推迟,有其自身的决定。
sqlSourceText 回填的有序 to-many(§8)——§8.4 由代理驱动的查询设计的天然
伴侣。MAD/MADTests 中的黄金 SQL 测试(扩展 MADQueryFullTests.m,它今天
只断言片段,MADQueryFullTests.m:140-162):固定存储 fixture → 确切的
期望 SQL 字符串,按驱动方言(MySQL、TDS 和 PostgreSQL 配置),覆盖别名命名
和 drop-index 形式、每种联接类型、每个带字面量引用符的谓词运算符,
以及活动字段排序。这些锁定解析器必须往返的生成器,且
它们也在 Linux 镜像中运行。MADStoreSchemaTests——既有的交叉检查现在断言描述符和
编译模型在 sqlSourceText 上一致(正是它迫使 §8.1 的两侧
一起落地的测试)。MADStoreMigrationTests(MAD):在版本 1 构建一个带行的磁盘存储
(即今天的架构,user_version 缺失)→ 用新 MADStore 打开 → 该
列存在,user_version 读出当前版本,且每个既有的行和
关系都保留;全新存储以当前版本创建;打开两次是
幂等的。这些也在 Linux 镜像中运行,因为无头引擎共享
迁移代码。MADSQLParserTests(MAD)--、/* */)、数字、运算符、大小写不敏感的关键字;错误位置。MADSQLQueryCompilerTests(MAD)带架构 fixture 的内存存储(MADModelQueryTableTests 所用的模式):
MADLinkType 和左/右字段,谓词带
正确的 comparson 和值字符串,分组带排序/权重以及创建的分组
头/尾带区和布局管理器;保存一次;sqlSourceText 与输入
语句完全相等(包括注释和空白)。sqlSourceText 被替换。sqlSourceText。MADQueryFull 生成 SQL → 解析 → 编译进全新存储 → 再次生成 SQL → 两个 SQL
字符串相等。正是这个测试定义了“the software recognizes what was
pasted.”WHERE 1=0 折叠——用伪造数据库,无服务器。MADMySQLLiveTests.m 风格的实时测试(无服务器时跳过):有效的粘贴 SQL
以期望的列名/类型干净探查;坏列返回服务器的
错误;读取零行。MADDesignerUITests使用样本 .mad(sqlite3 驱动):打开 SQL 浮出,切到 Edit,粘贴一个
带筛选器和分组的两表联接,Apply,然后断言查询表列表显示
两张表,可视化画布显示两个框和一个连接器,设计器显示
分组带区,且 View 模式显示重新生成的 SQL。然后关闭并重新打开
文档:As entered 标签仍显示确切的粘贴文本,Generated
标签仍显示编译查询的 SQL——文档保留了两者。
NSError(MADSQLCompileError);测试断言代码。Linux/cmake/MADSources.cmake;./Linux/build.sh 保持通过。MADStore 代码中,带测试可引用的版本常量——
绝不在仅 Apple 的路径中——使 Linux 套件能运行它。MADocument 辅助方法做这件事,并保持原样。确认。RptqQuery 上的 sqlSourceText,一个
属性保存最后一次成功应用的语句(§8),显示为 As entered
在 Generated 旁边。生成形式仍是刷新所执行的内容;存储文本
不改变执行。曾考虑历史数组并搁置
(§8,阶段 E)。本页为英文原文的简体中文翻译;如有出入,以英文原文为准。