DataHub 元数据模型实体文档编写指南深入解析 modelDocGen 文档生成管线【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub本指南讲解 DataHub 开源仓库中元数据模型实体参考文档的编写规范与生成机制metadata-models/docs/entities/目录下的手写实体说明文件如何与实体注册表、Avro Schema 一起经:metadata-ingestion:modelDocGenGradle 任务自动拼装成完整的实体参考页面。读完本文你将掌握实体文档的命名与内容约定、{{ inline }}指令与 SEO 描述文件的高级用法、底层生成逻辑以及修改后如何重新生成并在本地预览文档站点。一、总览手写实体描述是文档生成的输入而非产物metadata-models/docs/entities/目录存放的是 DataHub 各元数据实体的手写描述文档。这些文件如dataset.md、dashboard.md、chart.md并不会被文档站点直接发布而是作为modelDocGen构建步骤的输入材料它们提供的叙述性文字会被拼接到自动生成的实体参考页面中与程序化抽取的 Aspect、Relationship 等技术信息合并最终形成一张既有人类撰写的业务解读、又有机器生成的字段级参考的完整实体页面。这一点是理解整个体系的关键写作者只需要专注描述实体是什么、有哪些关键 Aspect、与其他实体如何关联剩下的字段表格、关系图谱、类型定义等机械性内容全部由构建管线自动补齐。二、工作原理三方输入合成一张实体参考页根据 AGENTS.md 的说明Gradle 任务:metadata-ingestion:modelDocGen实际执行 metadata-ingestion/scripts/modeldocgen.py会合并以下三个来源为每个实体生成参考页面输入源仓库位置作用实体注册表 Entity registrymetadata-models/src/main/resources/entity-registry.yml声明每个实体的名称、分类core/internal、keyAspect、关联的 Aspect 列表、一句话 doc 描述Avro Schemas构建期间由 PDL 文件生成位于metadata-events/mxe-schemas/src/mainGeneratedAvroSchema/avro/提供每个 Aspect 的字段结构、类型、Searchable/Relationship/Deprecated 等注解是字段表格的数据来源实体文档 Entity docsmetadata-models/docs/entities/*.md即本指南管辖的目录提供实体的人性化叙述被拼接到生成页面的开头生成结果输出到docs/generated/metamodel/entities/该目录被 gitignore属于构建产物不直接提交。从源码看三个来源在 modeldocgen.py 中依次加载--extra-docs参数指向metadata-models/docs脚本用正则/docs/entities/(.*)/*.md解析出每个实体对应的 markdown 文件内容存入entity_extra_docs同时加载 entity_descriptions.yaml 作为页面的 SEO 描述load_registry_file(registry)通过 Pydantic 模型EntityRegistry/EntityDefinition解析entity-registry.yml见 modeldocgen.py遍历schemas_root下所有.avsc文件仅加载MetadataChangeEvent.avsc与带Aspect属性的 Schema构建aspect_registry见 modeldocgen.py。最后entity_registry中每个实体的doc_file_contents被替换为手写文档内容进入后续生成流程。三、编写一篇实体文档命名规则与内容约定3.1 文件命名每个实体文档文件必须命名为{entityName}.md其中entityName与实体注册表entity-registry.yml中entities[].name完全一致。例如注册表中的dataset实体对应dataset.mddataJob对应dataJob.md。当前仓库 metadata-models/docs/entities/ 目录下已有 44 个实体文档包括dataset.md、dashboard.md、chart.md、container.md、dataProduct.md、domain.md、glossaryTerm.md、incident.md、mlModel.md、structuredProperty.md等覆盖核心实体core与平台内部实体internal两大类。新增实体文档时可参照 AGENTS.md 推荐的三个范本dataset.md、dashboard.md、chart.md。3.2 内容形态自由格式的叙述性 markdown文档内容是自由格式的 markdown核心职责是回答三个问题该实体代表什么业务语义它有哪些关键 Aspect它与其他实体如何关联。以 dataset.md 为例其结构展示了典型的写作范式## Identity解释实体如何被标识。Dataset 由 platform如hive、bigquery、redshift、name如db.schema.table和 environment/fabricPROD/STAGING/QA三段式标识并给出真实 URN 示例urn:li:dataset:(urn:li:dataPlatform:redshift,userdb.public.customer_table,PROD)## Important Capabilities分小节深入讲解关键能力Schemas、Field Paths、Tags and Glossary Terms、Ownership 等并穿插可直接运行的 Python SDK 代码示例各小节通过details折叠块组织代码示例保证页面整洁。3.3 在文档中嵌入仓库代码{{ inline }}指令实体文档中经常需要展示可运行的示例代码。与其复制粘贴容易与源码漂移正确做法是使用{{ inline }}指令按绝对路径引用仓库内的真实文件。以 dataset.md 为例details summaryPython SDK: Add a schema to a dataset/summary python {{ inline /metadata-ingestion/examples/library/dataset_schema.py show_path_as_comment }}指令语法为{{ inline 绝对仓库路径 [show_path_as_comment] }}。该指令会被 modeldocgen.py 中的expand_inline_directives函数展开从仓库根目录脚本上溯三级读取目标文件并把每一行加上原始缩进后内联进文档实现单点维护、多处引用。需要注意的是只有 DataHub 优化的文档变体会展开该指令详见下文 §5.2。内联路径必须以/开头否则会抛出inline path must be absolute异常。四、配套文件SEO 描述与实体注册表的 doc 字段4.1 entity_descriptions.yamlmetadata-models/docs/entity_descriptions.yaml 为每个实体提供 80–155 字符的 SEO meta description被 modeldocgen.py 读取后写入生成页面的 frontmatter见 modeldocgen.py 与写入逻辑 modeldocgen.py。示例如下# SEO meta descriptions for DataHub metadata model entity reference pages. # Each description should be 80-155 characters. dataset: Datasets represent tables, views, streams, or files in platforms like Snowflake, BigQuery, Kafka, and S3 — the core asset type tracked in DataHub. dataJob: DataJobs represent individual tasks within a pipeline — Airflow tasks, dbt models, Spark jobs — and capture their inputs, outputs, and lineage.新增或修改实体文档时应同步为该实体补充符合字数约束的描述否则生成页面的 frontmatter 中将缺少description字段。4.2 entity-registry.yml 中的 doc 字段实体注册表 metadata-models/src/main/resources/entity-registry.yml 中每个实体可带一个doc字段作为后备描述。例如- name: dataset doc: Datasets represent logical or physical data assets stored or represented in various data platforms. Tables, Views, Streams are all instances of datasets. category: core keyAspect: datasetKey aspects: - schemaMetadata - ownership - globalTags ...从 modeldocgen.py 的生成逻辑可知页面标题段的内容优先级是手写文档文件doc_file_contents优先若无手写文档则回退到注册表的doc字段拼接为# 实体名 doc 文本。也就是说只要编写了entities/{entityName}.md注册表中的doc就只作为兜底。此外注册表中的categorycore/internal与keyAspect会直接影响文档的分组展示与 URN 主键说明。五、生成器源码剖析一页参考文档是如何拼装出来的5.1 Docusaurus 变体完整版make_entity_docs(entity_display_name, graph)modeldocgen.py生成面向 docs 站点Docusaurus的完整页面组装顺序为手写文档doc_file_contents或注册表docTabs 组件导入自动注入import Tabs from theme/Tabs等两行供 Aspect 字段表格使用Technical Reference Guide 章节讲解 Aspect 与 Relationship 的基本概念并给出字段表格中Annotations列的阅读约定⚠️ Deprecated字段已废弃可能在未来版本移除Searchable字段已建索引可在 DataHub 搜索界面检索Searchable (fieldname)字段以不同的名字建索引例如dashboardTool实际索引为tool→ RelationshipName字段持有指向其他实体的 URN 引用箭头指示关系类型如→ Contains、→ OwnedByAspects 章节遍历实体的 Aspect 列表为每个 Aspect 生成#### 名称 (Deprecated)/(Timeseries)小节包含对应的 Python 类名通过ASPECT_NAME_MAP反查避免 PDL 记录名与 Aspect 注解名不一致导致错误如mlModelTrainingData → TrainingDataClassTabs双标签页Fields字段表格与Raw SchemaAspect 的完整 Avro JSON字段表格由extract_fields_from_schemagenerate_field_table生成列为Field | Type | Required | Description | Annotations复杂类型如Edge、AuditStamp自动链接到 Common Types 章节Common Types 章节identify_common_types统计各 Aspect 中重复出现的 record 类型出现次数 1 或属于AuditStamp、Edge、Urn、DataPlatformInstance等已知类型单独成节并链接回字段表格Relationships 章节基于RelationshipGraph自环/出边/入边三类邻接表分别渲染 Self、Outgoing、Incoming 关系及其来源字段路径Global Metadata Model嵌入整库元数据模型图链接。5.2 DataHub 优化变体摄入用make_entity_docs_datahub(entity_display_name)modeldocgen.py生成的是摄入到 DataHub 产品内的精简版本与 Docusaurus 版本的关键差异展开{{ inline }}指令DataHub 产品不会处理该指令将相对 markdown 链接转换为绝对 URLconvert_relative_links_to_absolutemodeldocgen.py把./xxx.md、../xxx.md等相对引用解析为https://docs.datahub.com/...绝对地址因为相对链接在 DataHub UI 中无法正常跳转剔除技术章节字段、可搜索性、关系等细节在 DataHub 产品的 Columns 页签中已经提供因此只保留一个指向Columns 页签的简短指引避免信息重复。两种变体分别写入docs/generated/metamodel/entities/{entityName}.md带sidebar_position与descriptionfrontmatter与docs/generated/metamodel/entities/.datahub-variant/{entityName}-datahub.md见 modeldocgen.py。CORE 实体在前、INTERNAL 实体在后各分类内按priority值升序再按名称字母序排列get_sorted_entity_namesmodeldocgen.py。5.3 文档的消费路径既生成页面也生成元数据除生成文档页面外modelDocGen还会产出metadata_model_mces.json文件——它把每个实体的文档作为DatasetProperties描述、把 Aspect 字段映射为SchemaMetadata含urn主键字段、Aspect/Searchable/Temporal 标签、外键关系以 MetadataChangeProposalMCP形式描述元数据模型的元数据。这解释了为何 metadata-ingestion/build.gradle 中该任务同时指定--generated-docs-dir文档输出与--fileMCE JSON 输出一套实体文档既服务文档站点也服务 DataHub 自身的元数据模型浏览体验。六、编辑后重新生成与预览按照 AGENTS.md 的操作指引修改任何实体文档后需要重新生成参考页面并预览文档站点./gradlew :metadata-ingestion:modelDocGen # 重新生成实体参考页面 scripts/dev/datahub-dev.sh docs # 本地预览文档站点第一条命令会触发 modelDocGen 任务它声明了完整的增量构建输入与输出inputsscripts/modeldocgen.py、metadata-models/docs/entities/**/*.md、metadata-models/docs/entity_descriptions.yaml、metadata-ingestion/examples/**/*.pyinline 指令引用的示例代码、metadata-events/mxe-schemas/src/**/*.avscoutputs../docs/generated/metamodel执行命令python scripts/modeldocgen.py schemasRoot --registry entity-registry.yml --generated-docs-dir docsOutdir --file metadata_model_mces.json --extra-docs metadata-models/docs。这意味着任何输入文件的变化都会触发重新生成——包括实体文档本身、被{{ inline }}引用的示例代码、以及底层的 Avro Schema。Gradle 的增量构建特性会确保只重跑必要的部分。其他相关任务lineageGenmetadata-ingestion/build.gradle复用同一脚本以--lineage-output参数生成src/datahub/ingestion/autogenerated/lineage.json该文件是从 Aspect Schema 中递归提取带isLineage/Relationship注解字段得到的血缘关系清单modelDocUploadmetadata-ingestion/build.gradle依赖modelDocGen调用scripts/modeldocupload.sh将生成的文档元数据上传到 DataHub 服务端CLI 还支持--server直接把 MCP 事件推送到 GMS、--dot/--png输出实体关系图、--lineage-output生成血缘 JSON等可选参数见 modeldocgen.py。七、写作自查清单编写或修改实体文档时建议按以下清单自检文件名entities/{entityName}.mdentityName与 entity-registry.yml 中的实体名完全一致大小写敏感内容完整性至少覆盖实体代表什么、关键 Aspect、与其他实体的关系三要素可参考 dataset.md、dashboard.md、chart.md 三个范本代码示例优先使用{{ inline /绝对路径 show_path_as_comment }}引用仓库内真实示例文件如metadata-ingestion/examples/library/下的脚本保持文档与源码同步SEO 描述同步更新 entity_descriptions.yaml保持 80–155 字符否则生成页面缺少descriptionfrontmatter相对链接实体文档内指向其他实体页的链接如 dataset.md 中的./dataPlatform.md在 Docusaurus 版本中会被原样保留在 DataHub 摄入变体中会被自动转换为绝对 URL编写时使用相对于entities/目录的路径即可验证运行./gradlew :metadata-ingestion:modelDocGen后检查docs/generated/metamodel/entities/下对应页面确认手写内容、Aspects 字段表格、Relationships 章节均正确生成再用scripts/dev/datahub-dev.sh docs在本地预览。掌握以上约定你就能以只写业务叙述、不碰机械细节的方式为 DataHub 元数据模型贡献高质量、可持续维护的实体参考文档。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DataHub 元数据模型实体文档编写指南：深入解析 modelDocGen 文档生成管线
DataHub 元数据模型实体文档编写指南深入解析 modelDocGen 文档生成管线【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub本指南讲解 DataHub 开源仓库中元数据模型实体参考文档的编写规范与生成机制metadata-models/docs/entities/目录下的手写实体说明文件如何与实体注册表、Avro Schema 一起经:metadata-ingestion:modelDocGenGradle 任务自动拼装成完整的实体参考页面。读完本文你将掌握实体文档的命名与内容约定、{{ inline }}指令与 SEO 描述文件的高级用法、底层生成逻辑以及修改后如何重新生成并在本地预览文档站点。一、总览手写实体描述是文档生成的输入而非产物metadata-models/docs/entities/目录存放的是 DataHub 各元数据实体的手写描述文档。这些文件如dataset.md、dashboard.md、chart.md并不会被文档站点直接发布而是作为modelDocGen构建步骤的输入材料它们提供的叙述性文字会被拼接到自动生成的实体参考页面中与程序化抽取的 Aspect、Relationship 等技术信息合并最终形成一张既有人类撰写的业务解读、又有机器生成的字段级参考的完整实体页面。这一点是理解整个体系的关键写作者只需要专注描述实体是什么、有哪些关键 Aspect、与其他实体如何关联剩下的字段表格、关系图谱、类型定义等机械性内容全部由构建管线自动补齐。二、工作原理三方输入合成一张实体参考页根据 AGENTS.md 的说明Gradle 任务:metadata-ingestion:modelDocGen实际执行 metadata-ingestion/scripts/modeldocgen.py会合并以下三个来源为每个实体生成参考页面输入源仓库位置作用实体注册表 Entity registrymetadata-models/src/main/resources/entity-registry.yml声明每个实体的名称、分类core/internal、keyAspect、关联的 Aspect 列表、一句话 doc 描述Avro Schemas构建期间由 PDL 文件生成位于metadata-events/mxe-schemas/src/mainGeneratedAvroSchema/avro/提供每个 Aspect 的字段结构、类型、Searchable/Relationship/Deprecated 等注解是字段表格的数据来源实体文档 Entity docsmetadata-models/docs/entities/*.md即本指南管辖的目录提供实体的人性化叙述被拼接到生成页面的开头生成结果输出到docs/generated/metamodel/entities/该目录被 gitignore属于构建产物不直接提交。从源码看三个来源在 modeldocgen.py 中依次加载--extra-docs参数指向metadata-models/docs脚本用正则/docs/entities/(.*)/*.md解析出每个实体对应的 markdown 文件内容存入entity_extra_docs同时加载 entity_descriptions.yaml 作为页面的 SEO 描述load_registry_file(registry)通过 Pydantic 模型EntityRegistry/EntityDefinition解析entity-registry.yml见 modeldocgen.py遍历schemas_root下所有.avsc文件仅加载MetadataChangeEvent.avsc与带Aspect属性的 Schema构建aspect_registry见 modeldocgen.py。最后entity_registry中每个实体的doc_file_contents被替换为手写文档内容进入后续生成流程。三、编写一篇实体文档命名规则与内容约定3.1 文件命名每个实体文档文件必须命名为{entityName}.md其中entityName与实体注册表entity-registry.yml中entities[].name完全一致。例如注册表中的dataset实体对应dataset.mddataJob对应dataJob.md。当前仓库 metadata-models/docs/entities/ 目录下已有 44 个实体文档包括dataset.md、dashboard.md、chart.md、container.md、dataProduct.md、domain.md、glossaryTerm.md、incident.md、mlModel.md、structuredProperty.md等覆盖核心实体core与平台内部实体internal两大类。新增实体文档时可参照 AGENTS.md 推荐的三个范本dataset.md、dashboard.md、chart.md。3.2 内容形态自由格式的叙述性 markdown文档内容是自由格式的 markdown核心职责是回答三个问题该实体代表什么业务语义它有哪些关键 Aspect它与其他实体如何关联。以 dataset.md 为例其结构展示了典型的写作范式## Identity解释实体如何被标识。Dataset 由 platform如hive、bigquery、redshift、name如db.schema.table和 environment/fabricPROD/STAGING/QA三段式标识并给出真实 URN 示例urn:li:dataset:(urn:li:dataPlatform:redshift,userdb.public.customer_table,PROD)## Important Capabilities分小节深入讲解关键能力Schemas、Field Paths、Tags and Glossary Terms、Ownership 等并穿插可直接运行的 Python SDK 代码示例各小节通过details折叠块组织代码示例保证页面整洁。3.3 在文档中嵌入仓库代码{{ inline }}指令实体文档中经常需要展示可运行的示例代码。与其复制粘贴容易与源码漂移正确做法是使用{{ inline }}指令按绝对路径引用仓库内的真实文件。以 dataset.md 为例details summaryPython SDK: Add a schema to a dataset/summary python {{ inline /metadata-ingestion/examples/library/dataset_schema.py show_path_as_comment }}指令语法为{{ inline 绝对仓库路径 [show_path_as_comment] }}。该指令会被 modeldocgen.py 中的expand_inline_directives函数展开从仓库根目录脚本上溯三级读取目标文件并把每一行加上原始缩进后内联进文档实现单点维护、多处引用。需要注意的是只有 DataHub 优化的文档变体会展开该指令详见下文 §5.2。内联路径必须以/开头否则会抛出inline path must be absolute异常。四、配套文件SEO 描述与实体注册表的 doc 字段4.1 entity_descriptions.yamlmetadata-models/docs/entity_descriptions.yaml 为每个实体提供 80–155 字符的 SEO meta description被 modeldocgen.py 读取后写入生成页面的 frontmatter见 modeldocgen.py 与写入逻辑 modeldocgen.py。示例如下# SEO meta descriptions for DataHub metadata model entity reference pages. # Each description should be 80-155 characters. dataset: Datasets represent tables, views, streams, or files in platforms like Snowflake, BigQuery, Kafka, and S3 — the core asset type tracked in DataHub. dataJob: DataJobs represent individual tasks within a pipeline — Airflow tasks, dbt models, Spark jobs — and capture their inputs, outputs, and lineage.新增或修改实体文档时应同步为该实体补充符合字数约束的描述否则生成页面的 frontmatter 中将缺少description字段。4.2 entity-registry.yml 中的 doc 字段实体注册表 metadata-models/src/main/resources/entity-registry.yml 中每个实体可带一个doc字段作为后备描述。例如- name: dataset doc: Datasets represent logical or physical data assets stored or represented in various data platforms. Tables, Views, Streams are all instances of datasets. category: core keyAspect: datasetKey aspects: - schemaMetadata - ownership - globalTags ...从 modeldocgen.py 的生成逻辑可知页面标题段的内容优先级是手写文档文件doc_file_contents优先若无手写文档则回退到注册表的doc字段拼接为# 实体名 doc 文本。也就是说只要编写了entities/{entityName}.md注册表中的doc就只作为兜底。此外注册表中的categorycore/internal与keyAspect会直接影响文档的分组展示与 URN 主键说明。五、生成器源码剖析一页参考文档是如何拼装出来的5.1 Docusaurus 变体完整版make_entity_docs(entity_display_name, graph)modeldocgen.py生成面向 docs 站点Docusaurus的完整页面组装顺序为手写文档doc_file_contents或注册表docTabs 组件导入自动注入import Tabs from theme/Tabs等两行供 Aspect 字段表格使用Technical Reference Guide 章节讲解 Aspect 与 Relationship 的基本概念并给出字段表格中Annotations列的阅读约定⚠️ Deprecated字段已废弃可能在未来版本移除Searchable字段已建索引可在 DataHub 搜索界面检索Searchable (fieldname)字段以不同的名字建索引例如dashboardTool实际索引为tool→ RelationshipName字段持有指向其他实体的 URN 引用箭头指示关系类型如→ Contains、→ OwnedByAspects 章节遍历实体的 Aspect 列表为每个 Aspect 生成#### 名称 (Deprecated)/(Timeseries)小节包含对应的 Python 类名通过ASPECT_NAME_MAP反查避免 PDL 记录名与 Aspect 注解名不一致导致错误如mlModelTrainingData → TrainingDataClassTabs双标签页Fields字段表格与Raw SchemaAspect 的完整 Avro JSON字段表格由extract_fields_from_schemagenerate_field_table生成列为Field | Type | Required | Description | Annotations复杂类型如Edge、AuditStamp自动链接到 Common Types 章节Common Types 章节identify_common_types统计各 Aspect 中重复出现的 record 类型出现次数 1 或属于AuditStamp、Edge、Urn、DataPlatformInstance等已知类型单独成节并链接回字段表格Relationships 章节基于RelationshipGraph自环/出边/入边三类邻接表分别渲染 Self、Outgoing、Incoming 关系及其来源字段路径Global Metadata Model嵌入整库元数据模型图链接。5.2 DataHub 优化变体摄入用make_entity_docs_datahub(entity_display_name)modeldocgen.py生成的是摄入到 DataHub 产品内的精简版本与 Docusaurus 版本的关键差异展开{{ inline }}指令DataHub 产品不会处理该指令将相对 markdown 链接转换为绝对 URLconvert_relative_links_to_absolutemodeldocgen.py把./xxx.md、../xxx.md等相对引用解析为https://docs.datahub.com/...绝对地址因为相对链接在 DataHub UI 中无法正常跳转剔除技术章节字段、可搜索性、关系等细节在 DataHub 产品的 Columns 页签中已经提供因此只保留一个指向Columns 页签的简短指引避免信息重复。两种变体分别写入docs/generated/metamodel/entities/{entityName}.md带sidebar_position与descriptionfrontmatter与docs/generated/metamodel/entities/.datahub-variant/{entityName}-datahub.md见 modeldocgen.py。CORE 实体在前、INTERNAL 实体在后各分类内按priority值升序再按名称字母序排列get_sorted_entity_namesmodeldocgen.py。5.3 文档的消费路径既生成页面也生成元数据除生成文档页面外modelDocGen还会产出metadata_model_mces.json文件——它把每个实体的文档作为DatasetProperties描述、把 Aspect 字段映射为SchemaMetadata含urn主键字段、Aspect/Searchable/Temporal 标签、外键关系以 MetadataChangeProposalMCP形式描述元数据模型的元数据。这解释了为何 metadata-ingestion/build.gradle 中该任务同时指定--generated-docs-dir文档输出与--fileMCE JSON 输出一套实体文档既服务文档站点也服务 DataHub 自身的元数据模型浏览体验。六、编辑后重新生成与预览按照 AGENTS.md 的操作指引修改任何实体文档后需要重新生成参考页面并预览文档站点./gradlew :metadata-ingestion:modelDocGen # 重新生成实体参考页面 scripts/dev/datahub-dev.sh docs # 本地预览文档站点第一条命令会触发 modelDocGen 任务它声明了完整的增量构建输入与输出inputsscripts/modeldocgen.py、metadata-models/docs/entities/**/*.md、metadata-models/docs/entity_descriptions.yaml、metadata-ingestion/examples/**/*.pyinline 指令引用的示例代码、metadata-events/mxe-schemas/src/**/*.avscoutputs../docs/generated/metamodel执行命令python scripts/modeldocgen.py schemasRoot --registry entity-registry.yml --generated-docs-dir docsOutdir --file metadata_model_mces.json --extra-docs metadata-models/docs。这意味着任何输入文件的变化都会触发重新生成——包括实体文档本身、被{{ inline }}引用的示例代码、以及底层的 Avro Schema。Gradle 的增量构建特性会确保只重跑必要的部分。其他相关任务lineageGenmetadata-ingestion/build.gradle复用同一脚本以--lineage-output参数生成src/datahub/ingestion/autogenerated/lineage.json该文件是从 Aspect Schema 中递归提取带isLineage/Relationship注解字段得到的血缘关系清单modelDocUploadmetadata-ingestion/build.gradle依赖modelDocGen调用scripts/modeldocupload.sh将生成的文档元数据上传到 DataHub 服务端CLI 还支持--server直接把 MCP 事件推送到 GMS、--dot/--png输出实体关系图、--lineage-output生成血缘 JSON等可选参数见 modeldocgen.py。七、写作自查清单编写或修改实体文档时建议按以下清单自检文件名entities/{entityName}.mdentityName与 entity-registry.yml 中的实体名完全一致大小写敏感内容完整性至少覆盖实体代表什么、关键 Aspect、与其他实体的关系三要素可参考 dataset.md、dashboard.md、chart.md 三个范本代码示例优先使用{{ inline /绝对路径 show_path_as_comment }}引用仓库内真实示例文件如metadata-ingestion/examples/library/下的脚本保持文档与源码同步SEO 描述同步更新 entity_descriptions.yaml保持 80–155 字符否则生成页面缺少descriptionfrontmatter相对链接实体文档内指向其他实体页的链接如 dataset.md 中的./dataPlatform.md在 Docusaurus 版本中会被原样保留在 DataHub 摄入变体中会被自动转换为绝对 URL编写时使用相对于entities/目录的路径即可验证运行./gradlew :metadata-ingestion:modelDocGen后检查docs/generated/metamodel/entities/下对应页面确认手写内容、Aspects 字段表格、Relationships 章节均正确生成再用scripts/dev/datahub-dev.sh docs在本地预览。掌握以上约定你就能以只写业务叙述、不碰机械细节的方式为 DataHub 元数据模型贡献高质量、可持续维护的实体参考文档。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考