Files
AgentLab/docs/zh-CN/data-catalog.md
T
ThearchyHelios 46a2988dc1 问数据双轨重构:快速直查与深度分析分流、可点击数字证据闭环及双语文档
- 重构问数据执行架构为「快速直查(fast)」与「深度分析(deep)」双模式,内置语义预命中(Grounding)注入指标卡片、标准实体编码与表目录血缘
- 快速直查免工作流生成单节点执行,新增零额外模型调用的数字证据归一与封存(direct_evidence),打通可点击数字溯源与 /verify 校验
- 深度分析与助手编排接入跨源本体穿透(自动升级重跑与一键沿本体排查关联数据源),优化数据源范围智能收敛与往返缓存
- 补齐端到端回归测试矩阵与中英文全量文档说明
2026-11-12 12:58:42 +08:00

215 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
[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 列补上数据里没出现的取值;日期列写明排除了几个无效日期。
- 表清单有「剖析」一列,表详情里有上次剖析的结果。
- 剖析记下的日期范围对每天整表重灌的表靠不住,所以查询区间里有没有数据是运行时现查的;剖析和取值观察记下的范围只在现查不成时当退路(见[查询区间里没有数据](evidence.md#查询区间里没有数据))。
缺省只剖析「需要剖析的表」:从没剖析过、上次没做完,或者之后又出现了待核实的关联、新的码值列或日期列的。同一个数据源上,起草和剖析排队串行;范围在开始剖析时按当时的目录定,所以起草完接着点剖析就行。
### 取值观察
剖析范围选「取值观察」或定时维护时,还会观察取值:行数、码值分布(包括人工确认过的码值列)、最新业务日期、最近 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),通知走「设置 → 通知」的渠道订阅。
## 标准业务实体桥
不同业务库常对同一类对象使用不同表名、列名与编码前缀(例如车间库的产线码 `L1` 与设备主数据里的 `EQ-L1`)。数据目录页顶部提供「标准实体」(`?view=entities`)入口,统一登记跨源标准业务实体(`CanonicalEntity`):
- **双栏治理**:左侧管理标准实体标识(如 `prod_line`)、名称与状态;右侧维护该实体在各数据源物理表列上的绑定(`bindings`)、口径入口参数映射(`caliber_params`)与跨源编码字典(`members`)。
- **候选审阅与运行期门禁**:文档自动起草或协作者提交的跨源映射可先标为待确认(`proposed`),由维护者在「标准实体」页逐条确认或驳回;只有已确认(`confirmed` / `verified`)的绑定和参数映射才会参与问数运行期的跨源自动翻译(`align_caliber_inputs`)与助手查看时的实体桥提示。
- **口径语义引用**:在口径详情的问数语义配置中,可直接为维度选择已登记的 `entity_key`,避免各口径重复手填跨库键值映射。
### Agent 辅助维护与业务文档联动
在「标准实体」页,除了手工表单编辑,还可以通过交互式助手和后台扫描维护跨源实体:
- **实体助手**:点击页顶「实体助手」展开右侧对话抽屉(`POST /api/ontology/entities/assistant`)。默认只将当前进入的数据源纳入分析范围(避免混入其他独立业务域的表和口径),需要跨库对齐时可在抽屉顶部点「跨源选择」按需勾选关联库。助手可在选定源内读取数据目录与口径参数(`inspect_sources`)、执行脱敏只读查询核对真实枚举值(`run_query`)、检索挂载的业务文档(`read_document`),并输出结构化变更提案(`propose_entity_changes`)。提案不会自动落库,维护者可在抽屉中逐条保留或移出,点击「保存修改」后经乐观锁校验(`POST /api/ontology/entities/apply-patch`)以 `confirmed` 状态生效。
- **扫描发现候选实体**:点击页顶「扫描发现候选实体」(`POST /api/ontology/discovery-jobs`),默认勾选当前数据源(支持按需多选同域数据源),后台任务会跨所选数据源、关联口径与文档自动识别同义主键、外键与编码映射。扫描产出的绑定与口径参数一律记为 `proposed`(来源 `ai`),绝不覆盖人工已确认或已驳回项,也不会直接参与线上问数穿透,须经人工审阅确认后生效。
- **业务文档与主数据对照表附件**:在「实体助手」与「扫描发现候选实体」弹窗中,均可直接上传 `.md`、`.docx`、`.pdf`、`.xlsx`、`.csv` 等业务制度或跨系统编码对照表(`POST /api/ontology/entities/attachments`),也可勾选已有知识库文档。上传时可按需勾选「同时存入知识库供后续复用」(`save_to_kb`)并指定知识库集合,一次上传即可同时服务实体对齐与后续问数检索。