DataHub项目：扩展元数据模型完全指南

前言

在现代数据治理平台DataHub中，元数据模型是核心基础架构。本文将深入讲解如何扩展DataHub的元数据模型，包括创建新实体和扩展现有实体的详细步骤。通过本指南，您将掌握DataHub元数据扩展的核心概念和实践方法。

扩展决策：是否要fork代码库？

在开始扩展元数据模型前，需要做一个重要决策：

• 开源分支方案：直接修改主代码库中的模型文件
• 自定义仓库方案：在独立仓库中维护扩展模型

绿色路径代表长期维护成本较低的方案，红色路径则可能带来未来代码冲突风险。DataHub团队正在努力将大多数模型扩展用例迁移到无代码/低代码路径，以减少维护负担。

元数据模型扩展详解

实体组成要素

在DataHub中，一个实体由两部分组成：

1. 关键方面(Key Aspect)：唯一标识实体实例
2. 其他方面(Aspects)：附加到实体的相关属性组

扩展步骤详解

步骤1：定义实体关键方面

关键方面包含唯一标识实体的字段。这些字段将被转换为URN的组成部分。

以Dashboard实体为例：

namespace com.linkedin.metadata.key

@Aspect = {
  "name": "dashboardKey",
}
record DashboardKey {
  @Searchable = { ... }
  dashboardTool: string
  
  dashboardId: string
}

生成的URN格式为：urn:li:dashboard:(<tool>,<id>)

关键点：

• 必须使用@Aspect注解
• 可以添加@Searchable和@Relationship注解
• 每个字段必须是String或Enum类型

步骤2：创建新实体并关联关键方面

在entity-registry.yml文件中定义实体：

- name: dashboard
  doc: 相关数据资产的容器
  keyAspect: dashboardKey

步骤3：定义或附加方面

可以创建新方面或重用现有方面（如Ownership、GlobalTags等）。

以DashboardInfo方面为例：

@Aspect = {
  "name": "dashboardInfo"
}
record DashboardInfo includes CustomProperties, ExternalReference {
  @Searchable = { ... }
  title: string
  
  @Relationship = { ... }
  charts: array[ChartUrn] = [ ]
  
  // 其他字段...
}

核心注解：

1. @Aspect：声明记录是一个方面
2. @Searchable：使字段可被搜索
3. @Relationship：创建实体间的边关系
4. @UrnValidation：对URN字段实施约束

步骤4：选择模型扩展存储位置

根据之前的选择：

• 开源分支方案：模型文件放在主代码库的metadata-models模块
• 自定义仓库方案：使用独立仓库管理模型文件

步骤5：将非关键方面附加到实体

在entity-registry.yml中添加：

entities:
  - name: dashboard
    keyAspect: dashBoardKey
    aspects:
      - dashboardInfo

步骤6（仅开源分支方案）：重建DataHub

执行以下命令重建：

./gradlew build

然后重新部署相关服务（gms、mae-consumer、mce-consumer）。

可选步骤7：在Python SDK中使用自定义模型

有两种方式：

1. 本地CLI：使用本地开发模式安装
2. 自定义模型包：生成可分发安装包

生成自定义包示例：

./gradlew customPackageGenerate -Ppackage_name=my-company-datahub-models -Ppackage_version="0.0.1"

可选步骤8：扩展前端支持

如果需要自定义UI展示：

1. 扩展GraphQL图
2. 添加React组件

核心注解详解

@Entity（传统注解）

标识实体快照记录，参数：

• name：实体唯一标识名

@Aspect

标识方面记录，参数：

• name：方面唯一标识名
• type：可选，设为"timeseries"表示时间序列方面
• autoRender：是否自动在UI中展示
• renderSpec：UI展示配置

@Searchable

使字段可被搜索，参数：

• fieldType：字段类型，决定如何索引

@Relationship

创建实体间的关系边，应用于URN类型字段

@UrnValidation

对URN字段实施约束

最佳实践建议

1. 优先考虑自定义仓库方案，减少未来冲突
2. 合理设计关键方面，确保URN唯一性
3. 充分利用现有方面，减少重复开发
4. 谨慎使用@Searchable，避免索引膨胀
5. 考虑UI自动渲染，减少前端工作

通过本指南，您应该已经掌握了DataHub元数据模型扩展的核心方法和最佳实践。根据实际需求选择合适的扩展路径，可以高效地定制DataHub以满足组织的特定需求。