[English](../en/data-catalog.md) | 简体中文 # 数据目录 这篇讲数据目录：它记什么、怎么起草和审阅、数据剖析、SQL 检查、大库的探查范围，以及结构和取值变化。给搭建者和管理员看。接入数据源见[数据源与表格导入](data-sources.md)。 ## 为什么要数据目录 表名和字段名说不清业务：一行代表一张门票还是一次检票，`visitor_count` 能不能按天相加，两张表按哪一列连、连上之后会不会一对多。助手建图、agent 写 SQL 时只能猜；猜错了，查询照样能跑，数却是错的。 数据目录把这些事实记下来，交给三处读： - **助手建图**：系统提示里每个库只有一行概览（表数、几张有目录、有没有遮罩），不列表名和字段。助手要看表时自己查看，服务端一次给齐（见[按需查看](ask-data.md#按需查看)）。 - **运行时查结构**：`db_schema` 返回表结构时附上目录。**遮罩列只给列名和类型**：它的注释、目录里这一列的中文名、码值和说明都不交给模型。助手查看、`db_schema`、`/api/datasources/{id}/schema?table=` 是同一份说法；代价是运行时 agent 看到的目录少了遮罩列那部分。 - **SQL 检查**：按目录查出会算错数的写法（见下文）。 ## 目录记什么 - 每张表：中文名、粒度、表类型、业务主键、业务日期、有效记录条件、去重规则。 - 每个字段：含义、单位、度量类型、码值。 - 表与表的关联。 目录只记数据事实，不记计算公式。「在园人数是存量，不能跨天相加」进目录；「环比 =（本月 − 上月）÷ 上月」进口径卡。这也是不另做一层指标语义层的原因：口径已经由口径卡和版本固定在管，再造一层就会出现两份口径。 ### 来源和状态 目录里每一项都带来源和状态： | | 取值 | |---|---| | 来源 | 数据库注释、外键、命名推断、数据剖析、模型起草、人工 | | 状态 | 推断、已验证、已确认、已驳回 | - 推断的项只作提示；已验证、已确认的才进入错误级检查。 - 驳回的项保留编号，下一次起草或推断不会把它带回来。 - 码值表可以标「已列全」。 ## 起草 - 探查时读外键和唯一约束；按 `xxx_id`、`xxxId` 推断关联，表名带业务前缀的也认。 - 可以让模型起草：中文名、粒度、表类型、业务主键、业务日期，以及每列的含义、单位、度量类型。 - 导入表格的数据源已有系统按核对结果生成的说明，目录不重复、也不改写它。 - 数据库注释就是表名、列名本身，或者是标识符写法的，不记进目录（不当中文名，也不当说明、含义）。 - 数据源上存的「起草要求」和这次的补充说明一起交给模型，帮它理解业务、统一用词。它们不能推翻「只记数据事实」的规矩，交回的内容照样逐项校验。 - 用哪个模型：在「设置 → 偏好设置」的「起草模型」里选，空着跟随助手的模型。 ### 模型起草 - 作为后台任务逐表进行，每张表记下状态和原因。写完一张就并入目录；宽表每写完一段就并入。 - 关掉对话框不停。可以停止，也可以只重试失败的表；清单上标出上次起草失败或只完成一部分的表。 - 停止、服务重启时，已经写进目录的段保留。服务重启时没跑完的任务标成中断，不会自己续跑；点「重试」重新起草这些表，已写进的不会丢。 - 同步起草和后台任务互斥。 - 每次调用最多 40 列。宽表先起草表级的项，再把列均分成几段起草；按表的先后排队，不插到窄表前面。 - 保留模型的思考，输出额度 32768；服务方不收时退回 8192。 - 重新起草时，模型这次留空或没通过校验的项，不删以前起草的。 - 模型拿不准、留空的列（目录里还没有中文名和含义的）逐表记下，可以补充起草要求后重起草。 ### 起草的止损规则 起草不设总时长上限，靠止损规则和手动停止： - 额度用完或超时，就把这一段拆小再问。超时的两半同时问；拆到每段 10 列仍接连超时，就不再拆。 - 累计拆小两次后，新开始的段减半，最低 10 列。 - 每段连同它分开、拆小的各块，最多调用 8 次。进度上看得到一段被分成了几块。 - 缺的表和列只补问缺的；被截断的回复先留下已经写完整的部分。 - 最近 10 次调用有 7 次没写出来时，后面的段不再拆小；同一张表接连 3 段都没写出来，就跳过它剩下的段。 - 最近 6 次调用有 4 次没写出来时，提醒换模型。 - 没写出来的原因写清是第几段、哪几列；「已拆小重试」只跟在真拆过的段后面。 ### 防错事实的提议 模型起草时，另外提议「有效记录条件」（一段 SQL 条件）和「去重规则」，各带依据。开了剖析的数据源，会把目录里的码值一起交给模型（遮罩列不给）。 - 条件按数据源的方言用 sqlglot 解析。只能引用这张表的列，不能有子查询、聚合、窗口函数，只允许几个常用函数；不符合的不收，逐表说明里写原因。 - 开了剖析的数据源上，经只读守卫数出排除比例。排除 0% 或 100% 的不收；收下的在说明里写「剖析核对：排除 x% 的行」。 - 这些都记为推断。SQL 检查的错误级规则只认人确认过的；这些提议在审阅队列里排在前面。 ## 审阅与修改 ### 审阅队列 - 只列推断的项，按「表被运行用到的次数 × 这一项多影响数字 × 来源」排序：有效记录条件、去重规则、业务日期、关联关系最前，业务主键、度量类型次之，中文名、含义、单位靠后。每项写明排在这里的理由。 - 可以按类别和表筛选，多选后批量确认、驳回或撤销审阅。逐表加乐观锁，冲突逐条标出。 - 看得到一张表被哪些运行用过，以及常用表、全部表和影响数字的项各确认了多少。 ### 表助手 在表详情页里和助手对话，完善这一张表： - 它看得到表结构、目录现状（每项的来源和状态）、关联关系、剖析结果、起草要求和上次起草留空的列。遮罩列只给列名。 - 它按你的指示成批提出修改，每项带改前、改后和依据，校验规则和目录相同（公式不收，列名要在表结构里）；拿不准的会反过来问你。 - 只在开了剖析的数据源上，它才经只读守卫跑查询核实：每次请求最多 5 条，结果先遮罩。 - 提案攒在「待保存的修改」里，确认后一次保存（一次最多 200 项），记为人工确认。每项的依据另存为这一项「确认时的依据」，和备注分开，在表详情里看得到；撤销审阅回到推断时去掉。 - 对话不存服务端。它只改目录，不碰业务库。 ### 在对话里纠正 在对话里说「status=9 表示作废」，助手会给出一条目录修改提案，列出改前、改后和理由。人确认后才保存，理由记为这一项「确认时的依据」。公式不收，留给口径卡。 ## 导出与导入 把目录导出成一个 JSON 文件（全部表的目录、各项状态和起草要求），在另一个实例或数据源上导入： 1. 先预览：哪些表、列对得上；每一项会新增、更新还是保留；冲突和跳过的逐条列出。 2. 人确认、驳回过的项照带。目标里已经确认过、但值不同的，保留目标的，记成冲突。文件里推断的项只填空缺。表结构里没有的列跳过，写明原因。 3. 起草要求只在目标没有时写入。 有起草或剖析在进行时不能导入。 ## 数据剖析 剖析用只读查询核对目录里的推断、补上统计事实。默认关闭，按数据源开启。 - 作为后台任务逐表进行：每张表看得到检查项进度、查询数、用时和正在核对哪一项。关掉对话框不停；可以停止，也可以只重试没做完的表。服务重启时没跑完的任务标成中断，不会自己续跑。 - 预算按表算，缺省每张表最多 40 条查询、60 秒。一张表用完只停它自己，下一张照样满额。 - 整次不设上限，靠止损和手动停止：连续 3 条查询失败，或最近 10 条有 7 条超时，就停下，不给业务库加压。 - 缺省一张表做完再做下一张。数据源设置里可以改成同时剖析 2–3 张，同一时刻对业务库最多这么多条查询。 - 每张表的查询一条一条发，只读，经过守卫。大表用统计信息估算行数；遮罩的列不取样。 - 发过的每条查询都留痕，取值换成「?」，抽到的键值不进 AgentLab 的库。 - 抽样核实推断出的关联，补上覆盖率和基数，站得住的升为已验证。状态列给出码值候选，含义等人填写。 - 剖析设置里的「核对键值数」：`DISTINCT … LIMIT` 取的不是随机样本。 - MySQL / MariaDB 上，文字列的剖析说明写明排序规则；ENUM 列补上数据里没出现的取值；日期列写明排除了几个无效日期。 - 表清单有「剖析」一列，表详情里有上次剖析的结果。 缺省只剖析「需要剖析的表」：从没剖析过、上次没做完，或者之后又出现了待核实的关联、新的码值列或日期列的。同一个数据源上，起草和剖析排队串行；范围在开始剖析时按当时的目录定，所以起草完接着点剖析就行。 ### 取值观察 剖析范围选「取值观察」或定时维护时，还会观察取值：行数、码值分布（包括人工确认过的码值列）、最新业务日期、最近 35 天每天的行数。 - 和同一口径（同样的取样方式）的历史比，比出新码值、比例剧变、断档、缺天、量跌、行数大起大落，记进变化记录（见下文）。 - 标了「已列全」的码值表出现目录里没有的取值时，系统撤销「已列全」，目录升一版。这是机器唯一会自己写进目录的事；新取值的含义仍要人填。 - 遮罩列不观察。 ## 版本与提醒 - 目录随表结构快照冻结进证据，每次运行用的是哪一版查得到。 - 发布时记下模板引用的表的目录版本；正式运行时目录有变化就提醒。agent 运行时才写 SQL 的，按「可能涉及」单独提醒。只提醒，不拦运行。 - 从发布版本发起的正式运行，这一版引用的表结构在发布之后变了时，运行里多一条「表结构变化」提醒（`schema.drift`，在封存范围内）。 - 审阅改了影响数字的那几项（有效记录条件、去重、业务日期、关联、业务主键、度量类型），或者表结构删了表、删了列、改了列类型时，用过它的答案标「依据有变」（见[口径账本](evaluation-and-ledger.md#召回)）。 ## SQL 检查 按目录检查七类问题： 1. 一对多关联后重复计算； 2. 存量跨时间相加； 3. 比率被相加或平均； 4. 漏了有效记录条件； 5. 码值不存在； 6. 没用约定的业务日期； 7. 关联条件对不上已知关系。 检查用在四处：助手自查时交回修正；受管模板发布时挡住；运行时标在查询快照上；契约指标的来源查询有错误时，出具降档。 解析不了的写法一律跳过：宁可漏报，不误报。错误级规则只用已验证、已确认的目录项。 ## 大库：探查范围与按需加入 几千张表的库不必全部读进来。 - 探查先建一份全库的对象索引：每种数据库一条字典查询，记名字、类型、注释、估算行数。 - 再按「探查范围」的规则读范围内的表：支持通配，排除优先；缺省最多 500 张，上限 2,000。 - 有数据目录的表、已发布模板写死的 SQL 用到的表，一律在范围内。 - 超过 500 张表、又没设探查范围的库，第一次探查会被拒绝，并说出命中了多少张。先在「探查范围」里设规则，或调高上限。 运行时和助手查看都先检索： - 助手查看和运行时的 `db_schema__` 先按需求检索（BM25；遮罩列只用列名）。 - `db_schema__` 不传表名时只列前 50 张，并说清另有多少张；可以用 `keyword` 检索。 - 点名范围外的表，会当场只读地读结构、加进范围并留痕（每次运行最多 8 张）。 - 「表已不在」只在表真被删了时说；范围外、读不到结构、索引里从来没有，各自分开说。 - 剖析得到的行数和日期范围也交给助手和 agent，附一句「只供写查询参考，不能作为回答里的数」。遮罩按当时的设置重新过滤。 ## 结构变化与取值变化 - **结构变化**：探查时每张表记一个结构版本，和上一次读到的比：加删列、改类型、改可空、改注释、主键 / 唯一约束 / 外键的增删。疑似改名只说「可能是改名」，不下结论。一张表第一次被探查时只建基线，不出变化。 - **取值变化**：取值观察和同一口径的历史比。大表照实写口径（整表、窗口、块采样、前 N 行），口径不同不比。 两种变化记在同一份变化记录里。 ### 在哪看、怎么处理 - 数据目录的「变化」视图按「要处理 / 提醒 / 说明」分组；数据源卡片上的角标是要处理的条数；表详情里有「结构与取值变化」一节。 - 每条写明影响面：说到这些列的目录项和它们的状态、写死了这一列的已发布模板、哪条 SQL 现在会报列不存在。 - 处理动作：「清理目录项」「加入码值」「重新起草」「重新剖析」「知道了」「误报」（误报必须写理由）。动作都落到目录已有的写入上，记下目录版本或建的任务。 - 机器自己只做一件事：数据证明码值表不再列全时，撤销「已列全」。 - 有「要处理」的变化时，可以推通知「数据源有变化要处理」，消息里只有源名、条数和链接，不放表名、列名和取值（见[通知](schedules.md#通知)）。也可以作为定时任务的触发事件。 ### 定时维护 数据源卡片上的「定时维护」： - 选步骤（探查结构、剖析需要的表、取值观察，可多选）和低峰时段，存成一条目标为这个数据源的定时任务。缺省没有。 - 和起草、剖析在同一个数据源上排队；没执行的步骤照实记原因。 - 这类定时任务不收 Webhook（回 422），通知走「设置 → 通知」的渠道订阅。