12.1 数据资产、术语与元数据目录：让搜索结果能够被正确使用

业务负责人问“上季度任务完成率是多少”，搜索结果出现七张同名表。有人选更新时间最新的一张，却不知道它只覆盖北部区域；也有人找到权威表，却把“已结算”当成“已完成”。目录若只展示表名和列类型，只会让错误数据更容易被发现。

元数据目录的目标不是收集最多信息，而是帮助使用者判断：这是什么、能否用于当前问题、由谁负责、现在是否健康。

本课目标

• 区分技术、业务、运行、质量与使用元数据；
• 为数据资产设计稳定身份和版本；
• 连接业务术语、物理字段与指标口径；
• 建立可搜索、可验证、可持续维护的目录。

1. 目录中的“资产”是什么

数据资产可以是：

• 表、视图、文件集合和流；
• 字段、schema 与分区；
• 指标、特征、模型输入和报告；
• 管道 job、代码版本和运行实例；
• 业务术语、规则与数据产品。

每个资产需要稳定标识，而不是只靠显示名称。例如：

platform://production/logistics/table/missions

标识应包含环境和命名空间；重命名要保留别名或迁移关系。开发表与生产表、逻辑指标与物理列不能因为同名而混为一个对象。

上例是自定义逻辑资产 ID，另存 asset_version=v3、schema 版本和存储快照 ID；不要让每次快照都变成毫无关联的新资产。重命名保留逻辑身份，而删除后重建是否沿用身份要有规则，避免把不同数据的历史拼到一起。

2. 五类元数据回答不同问题

技术元数据

schema、类型、键、分区、存储格式、位置和兼容版本。回答“怎样读取”。

业务/语义元数据

定义、单位、粒度、口径、允许用途、owner 与术语关系。回答“怎样解释”。

运行元数据

job/run、开始结束时间、代码版本、输入输出版本、状态和资源。回答“这次怎样生成”。

质量与可靠性元数据

SLI、规则结果、事件、认证状态、新鲜度和已知限制。回答“现在能否信任”。

使用元数据

查询、下游、访问频率、活跃消费者和最后使用时间。回答“谁依赖它”。

分类只是组织视角，同一事实可以跨类。核心是共同资产身份和时间版本。

3. 业务术语不等于字段备注

“任务完成率”应先成为有 owner 的业务术语：

名称：任务完成率
定义：观察窗口内满足完成条件的任务数 / 符合纳入条件的任务数
分子：状态在版本化完成集合中的去重任务
分母：已到观察截止且不属于测试/取消原因集合的任务
粒度：全局、区域、任务类型
事件时间与截止规则：……
单位：比例
owner：运营分析负责人

然后把术语连接到指标实现、字段和报告。一个术语可有多个物理实现，但必须标出权威版本；同一列名也可能承载不同术语。

术语表还需要同义词、弃用词和冲突关系。搜索“成功率”时应提示它是否与“完成率”不同，而不是静默合并。

4. 自动采集与人工维护各有边界

可以自动采集：

• catalog/schema 中的列、类型、分区和约束；
• 调度器和查询引擎中的 job、run 与依赖；
• 质量平台中的检查状态；
• 审计系统中的访问和使用统计。

需要领域判断：

• 指标为什么这样定义；
• NULL、默认值和状态的业务含义；
• 哪些用途被允许或禁止；
• 谁拥有最终解释权；
• 已知偏差和决策限制。

用 pd.read_parquet() 把整份数据读入内存来“采集元数据”，会把扫描成本误当目录成本。优先读取 catalog、schema 或文件 footer；行数也要标明是精确统计还是估计。

下面使用 PyArrow 读取一个文件的 footer 与 schema，不调用表数据读取接口：

from pathlib import Path
from tempfile import TemporaryDirectory
import pyarrow as pa
import pyarrow.parquet as pq

with TemporaryDirectory(prefix="atlas-metadata-") as directory:
    file = Path(directory) / "part.parquet"
    fixture = pa.table({"mission_id": ["m1", "m2", "m3"], "resources": [10, 20, None]})
    pq.write_table(fixture, file, row_group_size=2)
    with pq.ParquetFile(file) as parquet:
        record = {"row_count": parquet.metadata.num_rows,
                  "row_groups": parquet.metadata.num_row_groups,
                  "fields": parquet.schema_arrow.names}
    print(record)
# {'row_count': 3, 'row_groups': 2, 'fields': ['mission_id', 'resources']}

这只是单个文件的精确物理行数。数据集总行数需要可信文件清单，并考虑删除向量、过滤视图和快照规则；不能随意累加目录里所有旧文件。footer 的统计信息也可能含敏感值，读取元数据仍需权限。接口见 PyArrow ParquetFile。

5. 样例值可能泄露数据

目录展示样例值很方便，也可能把姓名、设备标识、稀有诊断或密钥暴露给本无权读原表的人。

可采用：

• 默认不采集敏感列样例；
• 使用批准的合成示例或格式模板；
• 让 profile 结果继承源数据访问策略；
• 对基数、最小/最大值等聚合做小群体保护；
• 记录谁触发采样、采样版本和删除时间。

目录应按字段和内容分级授权：普通术语可广泛可见，位置、schema、profile 和样例按风险与源数据策略限制。即使只显示“资产存在但需申请”，也可能泄露调查项目或租户身份；能否公开存在性需要单独决定。

6. 认证与弃用状态

搜索结果应区分：

• draft：仍在设计；
• verified/certified：已通过定义、owner、质量和用途审查；
• deprecated：只为迁移保留；
• quarantined：发生严重质量问题，不应继续消费；
• retired：停止生产，按政策保留或删除。

认证不是永久徽章。schema、逻辑、owner、SLO 或用途发生重大变化时应重新评审。弃用必须带替代资产、迁移期限和活跃消费者清单。

这些状态名称是示例生命周期，不是跨产品通用枚举。语义认证与运行健康也应分开保存：一个定义已认证的产品，今天的分区仍可能被隔离。搜索结果需要同时显示认证范围与最近质量状态，不能让一个绿勾盖住另一个红灯。

7. 搜索与排序要防止“最热门即权威”

相关性可综合：

• 名称、同义词和业务定义匹配；
• 权威/认证状态；
• 数据新鲜度与质量；
• 对当前用户可见的用途；
• 组织上下文和真实使用；
• 弃用与事件状态。

高查询量可能只是历史债务，不能压过权威状态。搜索结果页至少显示粒度、时间覆盖、owner、新鲜度、认证和限制，让使用者无需点开十层页面才能判断。

8. 元数据质量也需要 SLO

可监控：

• CDE 的 owner/定义/分类覆盖率；
• 生产资产运行元数据延迟；
• 已弃用资产仍有活跃查询的数量；
• 无 owner、过期认证和失效链接；
• 术语冲突解决时间；
• 目录搜索后成功访问或放弃率。

“目录有十万条资产”不表示好用。更有意义的是关键资产能否被正确找到、理解和处置。

常见误区

• 抓取 schema 就完成目录：技术结构不能替代业务口径。
• 展示真实样例最直观：目录可能因此成为敏感信息旁路。
• 最常用表就是权威表：流行度会固化历史债务。
• 认证一次永久可信：定义和上下文变化会使认证过期。

练习

1. 为任务完成率写完整术语，并连接两个物理实现。
2. 设计生产表、开发表和逻辑指标的稳定资产 ID。
3. 审查一个目录 profile 页面，找出可能泄露的小群体信息。
4. 为 deprecated 资产设计迁移状态和消费者追踪。

小结

目录只有把资产身份、业务语义、运行状态和使用限制连在一起，才能帮助读者做正确选择。可发现性不是终点；可解释、可验证和可退役同样重要。

运行时血缘进一步回答某个版本实际读了什么、写了什么，以及一次变更会影响哪些列、作业和决定。