返回正文目录第 3 章读者视角自审记录
自审日期：2026 年 10 月 15 日。正文：语义层的作用与代价。状态：已按用户意见改为产品无关的概念章，完成自审，待复审。
原稿自审记录
- 从前两章已经确认的销售额定义进入，先给指标定义卡，再解释 TM、QM，避免先堆术语。
- 区分固定口径与本次查询条件；六月、客户分组、前三名不固化为销售额定义。
- 明确说明文字不能自动实现分转元、状态过滤和权限，规则需要落实为可执行配置。
- 保留上一章的粒度问题：声明关联关系不等于自动解决重复累计，模型仍需按原始发票验证。
- 将开头的“按地区统计”改为“按月份统计”，不引入小销售库尚无的地区字段。
- 为首次出现的 DSL 补充简短解释；图中说明箭头表示映射和引用，避免误读成 ETL 数据搬运。
- 客户数量例子补充“原始样例的全部数据范围”，明确 5 和 4 的计算前提。
- ETL 只解释职责与无数仓时的起步方式；实际模型文件、CLI 操作留到应用篇。
事实核对
对照本地 TM/QM 定义总览核对：TM 映射来源、字段和关联；QM 基于一个或多个 TM 定义查询字段及治理边界；DSL 引用当前 QM 公开字段，宿主系统提供身份与权限上下文。
在独立 SQLite 内存库载入原始 seed.sql：客户档案总数为 5；筛选 ISSUED、开票日期大于等于 2025-06-01 且小于 2025-07-01，按 customer_id 去重，结果为 4。与正文一致，未修改样例数据。
本章为概念说明，定义卡不是已经部署的模型，未声称完成 Runtime 验证。已核对正文引用文件存在、Mermaid 代码块闭合。
2026 年 10 月 15 日，用户要求继续完成技术篇后统一审阅。本章与第 4 至 8 章一并待审，不将继续写作视为本章已获通过。
概念章改写复审
用户指出第三章过早引入 Foggy，要求聚焦语义层的含义、收益与新增问题。本轮重写正文，TM/QM 的具体职责移到第四章。
- 用“物理数据 → 业务对象、维度和指标 → 查询使用者”的映射解释概念，不使用产品术语。
- 保留销售额定义卡、固定口径与本次查询条件的区别，承接第二章而不重复错误 SQL。
- 解释复用业务定义、减少物理细节与集中约束的作用；区分模型作为上下文和模型参与查询编译，避免暗示所有语义层都会自动执行规则。
- 新增口径确认、变更维护、集中传播错误、查询能力范围、调试与性能成本，不将语义层描述成万能解法。
- 保留 ETL 与无数仓起步、客户数量练习；未新增字段、数据或可运行模型，5 与 4 的已核对结果不变。
- 通读后收短开头，保留“字段名留在幕后”“统一算错”的轻微自嘲，不重复第二章完整笑话。
概念参考本次读取的 Databricks 指标视图、Snowflake 语义视图及 Looker 实践建议。前两者支持业务对象、指标和维度的集中定义与映射；后者支持模型元数据、硬要求和 Agent 说明的职责区分。成本与取舍按架构机制分析，不作为厂商性能测试结论。
合订稿、章节入口和写作方案同步更新；正文保留产品无关的表述，外部链接仅供延伸阅读。
改写后约 1700 个中文字。已检查正文不含 Foggy、TM、QM 或 CLI；定义卡与原稿一致，第四章全部代码块未变，合订稿保留其他章节与本地链接。未改动任何数据或查询，不重复运行原样例。
补足可执行机制后的复审
用户指出概念章仍容易被理解成提示词或表结构 Markdown。本轮保留产品无关的范围，重点补上模型怎样进入查询执行，而非继续增加抽象定义。
- 开头明确本章讨论业务模型与查询处理机制共同构成的语义层，说明文件格式不能决定规则是否真正执行。
- 保留供人审核的定义卡，新增产品无关的 YAML 模型示意，展示来源、主键、类型、单位计算、聚合规则和关联关系；明确不是现有产品可直接加载的配置。
- 沿同一个六月查询展示字段绑定、权限校验、规则展开、关联和聚合规划、物理 SQL 编译及数据库执行；补充没有 LLM 时，报表或应用仍能使用这条执行路径。
- 自审时将模型中的金额定义拆为单票金额表达式及 sum 汇总规则，与第四章 salesAmount 的含义保持一致，避免将已聚合指标再次求和。分转元只出现在模型计算中。
- 用平均每张发票金额解释指标依赖、分组范围及重新聚合，避免把指标当成字段别名或可随意求和的现成数值。
- 保留一对多粒度与查询能力限制，不暗示声明关联就自动消除重复累计。权限仍需可信身份及执行策略，元数据说明不等于授权。
- 保留收益、建模维护代价、ETL、客户数量练习与轻微幽默，第四章负责具体接口和完整请求，未引入产品术语。
新增机制对照本次读取的 Cube 语义查询改写解释、Databricks 指标查询和 Snowflake 语义查询与粒度约束。仅参考机制，不复制厂商语法或宣称各产品能力一致。
本轮为教学机制说明，未编写或运行新的语义编译器，未加载实际模型。示意 SQL 表达式与第四章已核对的物理查询一致，原始数据和既有查询文件保持原样。
补全 LLM 查询元数据交付
用户指出结构化模型源文件还需要转成适合 LLM 的元数据，上一版缺少这一步。本轮作如下调整：
- 将建模源文件、系统加载的模型、导出查询元数据及查询执行机制分开解释。沿本书链路，LLM 接收导出并组织后的查询说明，不直接把完整源文件当作最终上下文。
- 新增同一模型导出的 Markdown 说明示例，包含适用问题、语义字段名、单位、分组和筛选用途、模型固定规则与能力范围。字段名标为产品无关示意，不提前使用具体产品语法。
- 说明导出格式可以是 Markdown、JSON 或工具响应，避免将某一种序列化格式写成行业统一要求。模型与导出元数据同源，变更后需要同步。
- 流程图改为纵向，展示“模型导出元数据供 LLM 理解”和“模型直接供引擎校验编译”两条支路。LLM 生成查询意图，引擎继续落实计算、固定过滤和权限。
- 用“LLM 未主动填写有效状态，模型固定过滤仍应生效”作具体说明，不承诺 LLM 的任意误选或额外运算都会自动纠正。
对照本次读取的 Looker 查询生成机制核对元数据支持字段选择、过滤和排序，而模型用于查询组合；Cube 元数据 API说明模型可导出维度、指标、类型等公开元信息。正文采用产品无关的教学链路，不声称这些产品都会输出 Markdown。
本次仅补充正文与图示，不改动原始数据、SQL 或第四章。源文件与 Markdown 都是说明示例，未声称运行过导出程序。
按用户补充，YAML 示意增加 name 与 caption；导出 Markdown 增加模型标识 SalesInvoiceQueryModel 和模型名称“有效开票销售分析”，与第四章的查询目标保持一致，并说明模型标识用于指定查询目标。
将主要代价改为 DSL 协议适配
用户指出口径整理与模型审查是可通过工程实践处理的共同工作，不适合作为本章主要矛盾；本轮重写“它又带来了哪些问题”，聚焦自定义 DSL 的熟悉度与接入成本。
- 将开头和小结的重心一并调整，避免正文改了、首尾仍以建模成本作主要结论。
- 区分模型元数据“查什么”与查询协议“怎样查”，说明字段列表不足以教会请求结构、操作符、聚合阶段和分页用法。
- 流程图增加协议、工具 Schema 和示例到 LLM 的独立输入；它们不被误画成业务模型自动包含的全部信息。
- 用 SQL WHERE 与 DSL slice 的区别举例，不提前提供具体产品接口；合法 JSON 不等于请求合法或业务选择正确。
- 将提示词、工具 Schema、示例和题库作为适配方法，不宣称任何 LLM 在任何 DSL 上必然弱于 SQL，也不把 DSL 适配代价推广为所有语义层的固有问题。
- 保留 DSL 结构约束与校验的作用，结尾自然引出第四章 DSL、第五章语义 SQL 的对照。
本次重读 Cube 的查询语言设计讨论，将其作为 SQL 熟悉度与新接口适配这一取舍的产品实践观点，不作为跨模型准确率实验结论。未改模型、元数据示例、SQL 或样例数据。
按 AI 正确、如实问数的目标复审（2026-10-15）
本轮将总纲、写作方案、章节索引与第三章统一到用户明确的目标：建立让 AI 正确、如实回答问数问题的语义层。
- 开头从规则复用进一步落到 AI 的理解、查询和回答；保留模型、元数据与引擎的职责，以及自定义 DSL 适配的主要矛盾。
- 流程图补全执行结果、口径、范围与状态返回到 LLM 回答的环节。这是本书要求的返回信息设计，不宣称现有各产品均已提供全部字段。
- 新增前三名合计与全体客户合计的对照，说明查询正确仍可能回答失实。12700 元与 13600 元已对照现有 chapter-01-results.json 核对；未重新运行数据库，也未修改样例数据或 SQL。
- 读者视角检查：避免暗示语义层保证所有回答正确；强调澄清、执行失败、无记录、零值和解释依据；不增加产品接入细节。
- 同步技术篇合订稿，检查八章齐全、代码围栏闭合、元数据示例内标题保留，第一、二及第四至八章正文保持原样。
语义层概念图复审（2026-10-16）
- 在“语义层是什么”中增加 Mermaid 图，用 AI 提问、语义模型与底层表关联三个部分展示业务含义和物理映射。
- 使用发票到客户、客户到地区的简化雪花式关联。地区表与地区 ID 明确为扩展示意，不冒充现有样例结构，不改动 YAML 或查询数据。
- 图示保留有效发票、金额分转元和发票粒度，说明关联关系之外仍需要指标、维度和执行规则；按地区分析必须另行建模并公开维度。
- 明确可直接基于业务库建模，避免读者误以为语义层必须先建设数仓或雪花模型。
- 自审并同步合订稿；检查代码围栏闭合、八章齐全、其他章节正文不变。未验证渲染器中的实际图形布局。
替换为典型模型图片（2026-10-16）
用户认为原概念图过于技术化。本轮搜索典型图片，选用 Microsoft Learn 星型模型概念图，替换开头同时混合 AI、语义规则和物理关联的 Mermaid 图。
按逻辑星型分析结构调整定义（2026-10-16）
- 重写“语义层是什么”的定义，将底层数据向以事实为中心、由维度与指标组成的逻辑分析模型整理，作为本节主线。
- 星型图之后直接对应本例：一张发票的粒度、客户与开票日期维度、有效开票销售额指标，随后衔接定义卡。
- 说明这种对齐发生在逻辑分析层，底层保留业务表，日期可以直接取自发票字段，不要求另建日期表或数仓。
- 保留多个分析主题组成关系网络的边界，引用已查阅的 dbt 语义图文档；不将任意复杂分析都描述成一颗星。
- 读者视角自审：区分事实、维度、指标、粒度；保留模型、导出元数据与引擎分工，避免退回到仅有表结构说明的理解。删去原定义中与后文重复的机制列表，保持概念节精练。
- 已同步合订稿；检查自“先把销售额定义清楚”起的正文与其他章节保持原样，八章齐全、代码围栏闭合，本地图片及文档链接存在。
从 LLM 元数据示例移除规则段（2026-10-16）
- 按用户意见，删除导出 Markdown 示例中的“规则”及其三项内容，保留模型标识、适用范围和字段含义、单位与可用操作。
- 固定过滤、分转元与权限继续由模型及执行部分说明，避免读者误以为需要把这些执行规则改写成提示词交给 LLM 保证。
- 将“LLM 未填写有效状态，固定过滤仍生效”的例子移到查询执行部分，保留系统职责的具体说明。
- 已自审并同步合订稿，检查元数据示例不含规则段，代码围栏闭合，其他章节保持原样。
拆分建模与用户问数图（2026-10-16）
- 按用户意见，将原完整流程图拆成两张角色时序图：建模人员准备与验证模型；用户通过 LLM 问数。
- 第一张围绕口径、粒度、模型提交、系统校验加载及元数据与试查结果核对，说明 AI 可以辅助、结果仍需审核。
- 第二张区分用户、LLM、语义层与数据库，明确语义层编译物理 SQL、数据库执行、语义层返回数据与执行信息、LLM 依据结果回答。
- 保留查询协议、工具 Schema 与示例的接入说明，避免误以为业务元数据已经包含完整查询协议；不再将准备工作与每次提问混在同一流程中。
- 自审检查：元数据示例未重新加入执行规则，正文保留可信身份与权限执行要求；合订稿已同步，其他章节正文不变，代码围栏闭合。未验证编辑器中的时序图实际布局。
调整两张图位置并通篇精简（2026-10-16）
- 建模图移到“从定义卡到可执行模型”末尾，减少为提交已审核模型、校验加载、样例试查、返回结果四个交互；口径确认与结果审核保留在配文中。
- 用户问数图保留在“一次查询怎样使用模型”，删除原先夹在查询段落中的建模过程。图中的用户问题明确为“前三名”，与正文的 limit 意图一致。
- 将指标聚合一节移到回答如实一节之前，连续说明执行与聚合，再转入回答依据。
- 删除概念开头提前重复的模型、元数据与引擎职责段落；合并元数据选择模型的说明，压缩重复的规则执行、DSL 取舍和小结。
- 保留逻辑星型分析思想、AI 问数目标、固定过滤与权限的执行边界、自定义 DSL 适配的主要矛盾、ETL 简介及字段命名幽默。
- 核对 YAML、Markdown 元数据和指标公式示例与原稿一致；保留正式元数据需要字段类型的说明，元数据示例未重新加入执行规则。
- 已逐段读回，检查章节过渡、两个时序图的角色归属及语法结构，核对本地链接与图片存在；同步合订稿，第一、二及第四至八章正文保持原样。未重新运行 SQL，也未检查编辑器实际渲染布局。
明确“模型”的指代（2026-10-16）
- 逐处检查正文、标题、两张时序图、表格及元数据示例，将业务数据与计算定义统一写为“语义模型”；首次出现时说明这一简称。
- 用“查询元数据”“这些定义”“业务规则”等短语减少重复，保留已有“语义层模型”和明确的“星型模型”称谓；大语言模型继续使用 LLM。
- 元数据示例的标签改为“语义模型标识”“语义模型名称”；标识值 SalesInvoiceQueryModel 与字段不变，未添加执行规则。
- 核对 YAML、指标公式与上一版一致；同步合订稿，其他章节正文不变，代码围栏闭合，本地图片与文档链接存在。
对照第二章说明语义层价值（2026-10-16）
- 将“它解决了哪些问题”改为“回看第二章：哪些工作交给了语义层”，逐项对照金额单位与口径、关联粒度、字段整理、权限和复核。
- 开头明确第二章已经使用 SQL 修正重复累计，视图、公共表达式与数据库策略同样能复用规则；比较工作组织与执行入口，不宣称直接 SQL 缺少这些能力。
- 表中保留引擎支持范围、无法可靠处理时拒绝的边界；结尾强调可信身份、业务审核及结果验证仍需落实，保留字段命名的轻微幽默。
- 从前文执行与如实回答回看第二章，再以“规则统一执行后，LLM 仍需掌握接口”衔接 DSL 协议适配；未重复展开 SQL 示例或权限方案。
- 自审并读回相邻章节内容，核对表格结构；已有代码、两张时序图与元数据示例保持原样，合订稿已同步，其他章节正文不变。
补充 SQL、语义 DSL 与虚拟语义 SQL 的取舍小结（2026-10-16）
- 在查询接口代价一节末尾对照两条路线：直接物理 SQL 的语言熟悉度与业务复杂度；语义 DSL 的业务清晰度与协议适配成本。
- 用“缓解上述取舍的一条路线”引出虚拟语义 SQL，不将其历史来源归结为 LLM 或单一困境，也不描述为所有产品必经的演进顺序。
- 本次重读 Cube《How Semantic SQL Works》的查询语言设计讨论，参考其对 SQL 生态、LLM 熟悉度、自定义接口适配的说明；不把厂商观点当作跨模型准确率实验。
- 将“SQL 万能”收束为“表达能力很强”，点出合适的 DSL 在部分分阶段、多维分析中可以更简洁，详细比较留在高级篇。
- 替换原有语义 SQL 过渡段，避免重复引入；检查与第四、五章的分工及术语一致，已同步合订稿，其他章节与代码示例保持原样。
补入对 DSL 潜力的个人判断（2026-10-17）
- 按用户观点，在 SQL 与 DSL 取舍小结后加入第一人称判断：LLM 理解协议、拆解分析步骤的能力增强，有望降低 DSL 适配门槛，发挥其复杂分析表达优势。
- 用“我个人认为”“有望”和能力条件明确区分作者判断与已验证结论，延续高级篇展开的安排，不新增实际性能或准确率承诺。
- 已读回相邻段落，核对单章与合订稿内容一致，合订稿更新日期改为 2026-10-17。
进入第四章前的读者视角复审（2026-10-17）
结论：第三章主线连贯，没有需要重写的结构问题，可以进入第四章审阅；这不是代替用户确认通过。
- 概念到案例：星型图解释事实、维度和指标，随后以同一发票口径进入定义卡与可执行语义模型，逻辑结构与物理表结构的区别清楚。
- 角色与信息：建模准备与用户问数分开；语义模型、导出元数据、LLM 和执行引擎的职责明确，元数据示例未混入执行规则。
- 正确与如实：聚合上下文、一对多粒度和前三名合计的例子分别说明计算与回答的边界；对照第二章承认直接 SQL 的处理能力，再讨论集中定义和执行的价值。
- 取舍与篇章：DSL 适配是本章主要新增门槛；虚拟语义 SQL 仅作过渡，复杂分析留高级篇，作者对 DSL 的判断有明确主观标识。保留轻微幽默，未继续增加抽象总结。
- 小修：在首次引入 DSL 时补明“领域专用语言”；第四章字段名与第三章的产品无关示意不同，补一句说明其对应关系，避免后文拒绝 customerName 时造成前后矛盾。
- 核对两章示例与图示未改变，本地引用存在，合订稿已同步，其他章节正文不变。本轮未重新运行 SQL，也未检查编辑器实际渲染布局。
后续章节迁移说明（2026-10-17）
原第五、六章移至高级篇第十九、二十章。第三章只保留语义 SQL 入口的简短说明，详细讨论指向第十九章；前文按八章核对合订稿的记录属于迁移前状态，当前技术篇合订稿为六章。
补充基础概念与整体复审（2026-10-17）
- 用基本构成表归纳业务对象、粒度、主键、维度、属性、指标与关联；不再在星型图后重复逐项解释。
- 把原有一对多提醒收拢为字段组合约束，用发票金额与商品维度说明不能任意组合，避免重复第二章的错误 SQL 推演。
- 保留平均金额示例，分别说明聚合规则与维度适用范围；缩短 DSL 门槛段的细节，具体筛选阶段交给第四章。
- 去掉正文的具名语义层产品举例，保留通用概念和已有来源链接；结构化定义与元数据示例没有新增执行规则提示词。
- 与前两章及第四、五章通读核对，基本构成、查询表达、系统组合各有侧重。新增内容已自审，待用户审阅。
实战篇合并后的对应关系（2026-10-17）
原第六、七章合并为现第六章《认识 Foggy，准备第一个问数项目》；原第八至二十二章顺移为第七至二十一章。语义 SQL 与统一执行计划现为第十八、十九章。上文保留当时的审阅记录，现行结构以总大纲 v7 为准；未开展环境搭建。
