AgentLab/docs/zh-CN/data-catalog.md

English | 简体中文

数据目录

这篇讲数据目录：它记什么、怎么起草和审阅、数据剖析、SQL 检查、大库的探查范围，以及结构和取值变化。给搭建者和管理员看。接入数据源见数据源与表格导入。

为什么要数据目录

表名和字段名说不清业务：一行代表一张门票还是一次检票，visitor_count 能不能按天相加，两张表按哪一列连、连上之后会不会一对多。助手建图、agent 写 SQL 时只能猜；猜错了，查询照样能跑，数却是错的。

数据目录把这些事实记下来，交给三处读：

• 助手建图：系统提示里每个库只有一行概览（表数、几张有目录、有没有遮罩），不列表名和字段。助手要看表时自己查看，服务端一次给齐（见按需查看）。
• 运行时查结构：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，在封存范围内）。
• 审阅改了影响数字的那几项（有效记录条件、去重、业务日期、关联、业务主键、度量类型），或者表结构删了表、删了列、改了列类型时，用过它的答案标「依据有变」（见口径账本）。

SQL 检查

按目录检查七类问题：

1. 一对多关联后重复计算；
2. 存量跨时间相加；
3. 比率被相加或平均；
4. 漏了有效记录条件；
5. 码值不存在；
6. 没用约定的业务日期；
7. 关联条件对不上已知关系。

检查用在四处：助手自查时交回修正；受管模板发布时挡住；运行时标在查询快照上；契约指标的来源查询有错误时，出具降档。

解析不了的写法一律跳过：宁可漏报，不误报。错误级规则只用已验证、已确认的目录项。

大库：探查范围与按需加入

几千张表的库不必全部读进来。

• 探查先建一份全库的对象索引：每种数据库一条字典查询，记名字、类型、注释、估算行数。
• 再按「探查范围」的规则读范围内的表：支持通配，排除优先；缺省最多 500 张，上限 2,000。
• 有数据目录的表、已发布模板写死的 SQL 用到的表，一律在范围内。
• 超过 500 张表、又没设探查范围的库，第一次探查会被拒绝，并说出命中了多少张。先在「探查范围」里设规则，或调高上限。

运行时和助手查看都先检索：

• 助手查看和运行时的 db_schema__ 先按需求检索（BM25；遮罩列只用列名）。
• db_schema__ 不传表名时只列前 50 张，并说清另有多少张；可以用 keyword 检索。
• 点名范围外的表，会当场只读地读结构、加进范围并留痕（每次运行最多 8 张）。
• 「表已不在」只在表真被删了时说；范围外、读不到结构、索引里从来没有，各自分开说。
• 剖析得到的行数和日期范围也交给助手和 agent，附一句「只供写查询参考，不能作为回答里的数」。遮罩按当时的设置重新过滤。

结构变化与取值变化

• 结构变化：探查时每张表记一个结构版本，和上一次读到的比：加删列、改类型、改可空、改注释、主键 / 唯一约束 / 外键的增删。疑似改名只说「可能是改名」，不下结论。一张表第一次被探查时只建基线，不出变化。
• 取值变化：取值观察和同一口径的历史比。大表照实写口径（整表、窗口、块采样、前 N 行），口径不同不比。

两种变化记在同一份变化记录里。

在哪看、怎么处理

• 数据目录的「变化」视图按「要处理 / 提醒 / 说明」分组；数据源卡片上的角标是要处理的条数；表详情里有「结构与取值变化」一节。
• 每条写明影响面：说到这些列的目录项和它们的状态、写死了这一列的已发布模板、哪条 SQL 现在会报列不存在。
• 处理动作：「清理目录项」「加入码值」「重新起草」「重新剖析」「知道了」「误报」（误报必须写理由）。动作都落到目录已有的写入上，记下目录版本或建的任务。
• 机器自己只做一件事：数据证明码值表不再列全时，撤销「已列全」。
• 有「要处理」的变化时，可以推通知「数据源有变化要处理」，消息里只有源名、条数和链接，不放表名、列名和取值（见通知）。也可以作为定时任务的触发事件。

定时维护

数据源卡片上的「定时维护」：

• 选步骤（探查结构、剖析需要的表、取值观察，可多选）和低峰时段，存成一条目标为这个数据源的定时任务。缺省没有。
• 和起草、剖析在同一个数据源上排队；没执行的步骤照实记原因。
• 这类定时任务不收 Webhook（回 422），通知走「设置 → 通知」的渠道订阅。