DataHub 核心概念全解析：URN、策略、角色与元数据建模模型

DataHub 核心概念全解析：URN、策略、角色与元数据建模模型

【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub

数据资产治理的第一步是理解平台的核心抽象。DataHub（The Context Platform for your Data and AI Stack）以一套"实体 + 属性（Aspect）+ 关系（Relationship）"的元数据模型为骨架，通过 URN 唯一标识每个资源，并用 Policy、Role、Access Token 构建细粒度的权限体系。本文以仓库文档 docs/what-is-datahub/datahub-concepts.md 为主线，结合源码与配套文档，系统讲解 DataHub 的核心概念，读完后你将能准确理解 URN 的构成与限制、掌握 Policy/Role/PAT 的权限设计思路，并深入理解 Entity/Aspect/Relationship 元数据模型及其在查询与存储中的实际行为。

一、通用概念（General Concepts）

URN（Uniform Resource Name）

URN 是 DataHub 中唯一标识任意资源的 URI 方案，其形式为：

urn:<Namespace>:<Entity Type>:<ID>

典型示例：urn:li:dataset:(urn:li:dataPlatform:hive,fct_users_created,PROD)、urn:li:corpuser:jdoe。完整的 URN 规范可参考 docs/what/urn.md。

从源码结构看，URN 的三段式组成由 li-utils/src/main/javaPegasus/com/linkedin/common/urn/ 目录下的Urn.java基类及各类实体 URN 实现共同定义：

• Namespace（命名空间）：DataHub 内置所有 URN 统一使用li作为命名空间；如果你 fork DataHub，可以整体更换为自己的组织命名空间。
• Entity Type（实体类型）：即资源的对象类型，例如dataset、corpuser、dataPlatform。它不限于元数据图中的实体，数据平台等资源也可以有自己的 URN。
• ID（标识符）：在特定命名空间、特定实体类型下唯一。ID 可以是单字段，也可以是多字段（复杂 URN）。复杂 URN 的字段甚至可以嵌套其他 URN，称为嵌套 URN；非 URN 类型的字段值可以是字符串、数字或 Pegasus Enum。

以 DatasetUrn.java 为例，DatasetUrn extends Urn，包含三个 ID 字段：platform（另一个 URN，即DataPlatformUrn）、name、origin（FabricType枚举，如PROD、EI）。构造时调用super(ENTITY_TYPE, TupleKey.create(platform, name, origin))完成嵌套 URN 的序列化，示例：

urn:li:dataset:(urn:li:dataPlatform:kafka,PageViewEvent,PROD) urn:li:dataset:(urn:li:dataPlatform:hdfs,PageViewEvent,EI)

URN 的字符限制（创建或生成 URN 时必须遵守，建议对受限字符做 URL 编码）：

1. 圆括号(或)是保留字符，不允许出现在 URN 的任何位置；
2. Unicode "单元分隔符"␟（U+241F）不允许出现；
3. 在 URN 元组内部，逗号,是保留字符。例如urn:li:dashboard:(looker,dashboards.thelook)合法，而urn:li:dashboard:(looker,dashboards.the,look)非法。

Policy（访问策略）

访问策略定义"谁（Actors）能对哪些资源（Resources）做什么操作（Privileges）"。完整指南见 docs/authorization/policies.md，几个通俗示例：

• Dataset 的 Owner 可以编辑文档，但不能编辑 Tag；
• 数据管家 Jenny 可以为任意 Dashboard 编辑 Tag，但不能动其他元数据；
• 数据分析师 James 只能编辑他下游消费的特定数据管道的 Links；
• 数据平台团队可以管理用户与组、查看平台分析、管理策略本身。

Policy 分为两类：

• Platform Policies（平台策略）：授予平台级权限，如管理用户与组、查看 Analytics 页面、管理策略本身。它只有"Actors + Privileges"两部分，没有目标资源。
• Metadata Policies（元数据策略）：控制对元数据实体的读写，由"Resources（哪个）+ Privileges（做什么）+ Actors（谁）"三部分组成。

资源可以按以下方式圈定（多个条件是交集/AND关系，例如同时限定 resource type 为 dataset 且带myTag标签，则策略只作用于被该标签标记的 dataset）：

1. 资源类型（如 dataset、chart、dashboard）；
2. 资源 URN（指定具体实体）；
3. Tag（带特定标签的资产）；
4. Domain（特定业务域内的资产，递归包含嵌套子域）；
5. Container（特定容器内的资产，递归包含嵌套子容器）；
6. Glossary Term / Term Group（被特定业务术语或术语组标注的资产，术语组递归覆盖其全部子项）。

Actors 支持三种定义方式（注意与资源不同，Actor 之间是并集/OR关系）：用户列表（或全部用户）、组列表（或全部组）、实体的 Owner。

策略默认启用。若想完全关闭策略功能（隐藏策略管理 UI、默认放行所有操作），可在datahub-gms容器的环境变量（如docker/datahub-gms的 docker.env）中设置AUTH_POLICIES_ENABLED=false。策略仅当 GMS 设置REST_API_AUTHORIZATION=true时才约束 REST API。系统内置的默认策略定义在metadata-service/war/src/main/resources/boot/policies.json，其中datahub根账号拥有不可变超级用户权限，避免误删所有策略后无法登录。完整权限清单（Platform 级、Entity 级、Aspect 级如 Edit Tags / Edit Owners / Edit Lineage 等）见 PoliciesConfig.java。

Role（角色）

DataHub 提供 Role 机制来批量管理权限。开箱即用的内置角色（Admin、Editor、Reader 等）会与 Policy 共同生效——例如在启用基于视图的访问控制（VBAC）时，Admin/Editor/Reader 角色会覆盖视图级策略限制，因此不应给需要受限发现能力的用户分配 Editor/Reader。详见 docs/authorization/roles.md。

Access Token（个人访问令牌，PAT）

Personal Access Token（PAT）让用户以代码形式代表自己，在启用安全的部署环境中以编程方式调用 DataHub API。它与启用认证的元数据服务配合使用，为自动化操作增加一层保护。使用 PAT 需要两个前提：

1. GMS 已启用元数据认证；
2. 用户已通过 DataHub Policy 被授予Generate Personal Access Tokens或Manage All Access Tokens权限。

生成后，在 HTTP 请求头中以 Bearer 方式携带令牌。生产环境推荐经前端代理（9002 端口）访问，也可直接访问 GMS（8080 端口）：

# 经前端代理（生产推荐） curl 'http://localhost:9002/api/gms/entities/urn:li:corpuser:datahub' -H 'Authorization: Bearer <access-token>' # 直接访问元数据服务 curl 'http://localhost:8080/entities/urn:li:corpuser:datahub' -H 'Authorization: Bearer <access-token>'

令牌的可用有效期选项来自 GMS 配置authentication.accessTokens.allowedDurations（ISO-8601 时长，默认PT1H、P1D、P7D、P30D、P90D、P180D、P365D）；默认禁用永不过期令牌，如需开启可设置ACCESS_TOKEN_ALLOW_NO_EXPIRY=true。若未启用元数据认证，未携带令牌的编程请求会收到 401。详见 docs/authentication/personal-access-tokens.md。

View（视图）

View 允许你保存并共享一组过滤条件，在浏览 DataHub 时复用。一个 View 可以是公共的（Public）或私人的（Personal）。

Deprecation（弃用状态）

Deprecation 是描述实体弃用状态的一个 Aspect，通常以布尔值表达，用于标记数据资产已废弃。

Ingestion Source（采集源）

Ingestion Source 指我们从中抽取元数据的外部数据系统，例如 BigQuery、Looker、Tableau 等。完整的 Source 清单见 metadata-ingestion/README.md。

Container（容器）

Container 是一组相关数据资产的容器，例如数据库、Schema、项目等。容器本身也是元数据图中的实体，可用于策略的资源圈定。

Data Platform（数据平台）

Data Platform 是包含 Dataset、Dashboard、Chart 及其他各类数据资产的系统或工具。内置数据平台的完整清单定义在启动时的引导配置文件>namespace com.linkedin.metadata.key /** * Key for a CorpUser */ @Aspect = { "name": "corpUserKey" } record CorpUserKey { /** * The name of the AD/LDAP user. */ @Searchable = { "fieldName": "ldap", "fieldType": "WORD_GRAM", "boostScore": 2.0, "enableAutocomplete": true } username: string }

由此生成的 URN 形式为urn:li:corpuser:<username>。例如用户johnsmith的 Key Aspect JSON 为{"username": "johnsmith"}，对应 URN 为urn:li:corpuser:johnsmith。同时可以看到@Searchable注解把username映射到搜索索引的ldap字段并提升权重，印证了"Key Aspect 中的字段通常也是搜索常用字段"的设计。

Entity Registry（实体注册表）

元数据模型的"Schema"集中定义在Entity Registry中——它是构成元数据图的实体及各自 Aspect 的目录。自 2022 年 1 月起，DataHub 已弃用通过 Snapshot 模型新增实体的方式，改为在 YAML 配置文件entity-registry.yml（metadata-models/src/main/resources/entity-registry.yml）中声明：启动时元数据服务会校验注册表结构，并确保能为每个 Aspect 名称找到对应的 PDL Schema（通过@Aspect注解）。这让模型演变更简单——新增 Entity/Aspect 只需向 YAML 增加条目，而无需创建新的 Snapshot / Aspect 文件。

查询元数据图的三种方式

DataHub 的建模语言允许按查询模式优化元数据持久化，官方支持三种查询方式（详见 docs/modeling/metadata-model.md）：

1. 主键查找（按 URN 取实体）：调用entities端点并传入 URL 编码的 URN，返回该实体最新版本的 Aspect 集合：

   curl --location --request GET 'http://localhost:8080/entities/urn%3Ali%3Achart%3Acustomers'

   也可以指定 Aspect 名与版本号按版本读取，或通过aspects?action=getTimeseriesAspectValues读取时序型 Aspect。

2. 搜索查询：按任意字符串搜索实体，input指定查询词、entity指定实体类型：

   curl --location --request POST 'http://localhost:8080/entities?action=search' \ --header 'X-RestLi-Protocol-Version: 2.0.0' \ --header 'Content-Type: application/json' \ --data-raw '{"input": "\"customers\"", "entity": "chart", "start": 0, "count": 10}'

3. 关系查询：沿指定类型的边查找与源实体相连的实体，例如查询某 Chart 的所有者：

   curl --location --request GET --header 'X-RestLi-Protocol-Version: 2.0.0' \ 'http://localhost:8080/relationships?direction=OUTGOING&urn=urn%3Ali%3Achart%3Acustomers&types=List(OwnedBy)'

两类 Aspect：Versioned 与 Timeseries

1. Versioned Aspects（版本化 Aspect）：每个版本化 Aspect 都关联一个数字版本号。字段变化时自动生成新版本并存储在关系型数据库中（可备份恢复），支撑了 UI 中的大部分体验（Ownership、描述、Tag、业务术语等）。示例：Ownership、GlobalTags、GlossaryTerms。

2. Timeseries Aspects（时序 Aspect）：每个时序 Aspect 关联一个时间戳，用于表示实体随时间有序变化的事件，如数据集画像（profiling）结果、每日数据质量检查结果。要点：

• 时序 Aspect不存入关系型存储，而是持久化在搜索索引（如 Elasticsearch）与消息队列（Kafka）中，因此灾备恢复相对更具挑战；
• 必须声明"type": "timeseries"并包含 TimeseriesAspectBase（内含timestampMillis字段）；
• 可以通过时间范围查询，这是它与版本化 Aspect 最大的区别；
• 字段可附加@Searchable与@Relationship注解，也可附加@TimeseriesField/@TimeseriesFieldCollection注解以支持聚合查询。

以 DatasetProfile.pdl 为例，它includes TimeseriesAspectBase，定义了rowCount（总行数）、columnCount（总列数）、fieldProfiles（每列画像）、sizeInBytes（存储字节数）等可搜索统计字段，@Aspect注解中"type": "timeseries"表明其类型。

时序 Aspect 的摄入有两种方式：通过 GMS REST 端点aspects?action=ingestProposal以 JSON 方式提交（entityType、entityUrn、changeType=UPSERT、aspectName、aspect.value为转义的 JSON 字符串），或通过 Python SDK 的MetadataChangeProposalWrapper配合DatahubRestEmitter/DatahubKafkaEmitter发送。聚合查询则通过analytics?action=getTimeseriesStats完成：metrics支持LATEST、SUM、CARDINALITY三种聚合，buckets支持DATE_GROUPING_BUCKET（时间窗口分组，配合毫秒时间戳）与STRING_GROUPING_BUCKET（按字符串字段唯一值分组），返回一个类 SQL 的table（columnNames/columnTypes/rows）。相关测试可参考metadata-io/src/test/java/com/linkedin/metadata/timeseries/search/TimeseriesAspectServiceTestBase.java中的getAggregatedStats测试组。

三、总结：概念如何串联成体系

DataHub 的核心概念是层层咬合的：URN是贯穿一切的唯一标识（urn:li:<entity-type>:(...)），Entity/Aspect/Relationship构成可查询的元数据图（Entity 是节点、Aspect 是可独立写入的属性面、Relationship 是双向可遍历的边），Data Platform / Dataset / Chart / Dashboard / Data Job / Data Flow / Container / CorpUser / CorpGroup等则是图中预定义的核心实体，Tag / Glossary Term / Domain / Owner / Deprecation提供对资产的标注、组织与治理维度，而Policy / Role / Access Token则在实体与操作之上定义了完整的授权边界。理解这套概念模型，是使用 DataHub 管理数据资产、设计权限策略、编写采集与查询程序的基础。

进一步阅读：元数据建模详见 docs/modeling/metadata-model.md，URN 规范详见 docs/what/urn.md，Aspect 概念详见 docs/what/aspect.md，策略授权详见 docs/authorization/policies.md，个人访问令牌详见 docs/authentication/personal-access-tokens.md。

【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub