尧图网站建设 
DataHub SDK Entities 全解析从 Dataset 到 Semantic Model 的实体编程指南【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub本文基于 DataHub 开源仓库中 entities.rst 文档展开系统梳理datahub.sdk下全部核心实体类的构造参数、底层 Aspect 机制与实战用法。你将掌握如何使用 Dataset、Container、DataFlow/DataJob、Chart/Dashboard、MLModel/MLModelGroup、SemanticModel/Metric 等实体构建 DataHub 元数据并理解实体与 URN、Aspect、MCP 之间的底层映射关系可直接将代码模式迁移到自己的元数据管理场景中。一、SDK 实体体系总览DataHub SDK 提供了一组实体Entities用于与 DataHub 元数据交互。正如 entities.rst 所述这些实体覆盖了数据目录中最常见的对象类型数据集、容器、机器学习模型、仪表盘、图表、数据任务、数据流、语义模型与指标。在源码层面所有实体都继承自 entity.py 中定义的抽象基类Entity每个实体对应一种 URN 类型如DatasetUrn、ContainerUrn通过get_urn_type()类方法声明最终由ENTITY_CLASSES字典完成「实体类型名 → 实体类」的注册见 _all_entities.py每个实体内部维护_aspectsAspect 集合对实体的修改本质上是读写对应的 Aspect实体可通过as_mcps()转换为一条条MetadataChangeProposalWrapperMCP再经as_workunits()转为MetadataWorkUnit从而接入 DataHub 的元数据写入管道见 entity.py。Entity基类不允许直接实例化会抛出SdkUsageError必须使用其子类例如Dataset或Container。实体类之间通过 Mixin 复用通用能力例如HasTags标签、HasTerms术语、HasOwnership所有权、HasDomain域、HasContainer父容器、HasSubtype子类型、HasInstitutionalMemory机构记忆、HasStructuredProperties结构化属性等具体定义见 _shared.py。二、Dataset数据目录的核心实体Dataset在 dataset.py 中定义表示 DataHub 中的数据集——一张表、一个视图或一个文件。它是 SDK 中功能最完整的实体同时实现了HasPlatformInstance、HasSubtype、HasContainer、HasOwnership、HasInstitutionalMemory、HasTags、HasTerms、HasDomain、HasStructuredProperties等全部通用能力。2.1 构造参数详解Dataset.__init__的完整签名见 dataset.py如下身份标识platform平台名如mysql、snowflake、name数据集名、platform_instance可选平台实例、env环境默认DEFAULT_ENV即PROD数据集属性description、display_name、qualified_name、external_url、custom_properties字典、created/last_modifieddatetime对象、view_definition视图定义标准 Aspectparent_container父容器默认哨兵值unset、subtype、owners、links、tags、terms、domain数据集专属schemaSchema 定义、upstreams上游血缘、structured_properties、extra_aspects、parse_view_lineage视图血缘解析开关。URN 通过DatasetUrn.create_from_ids(platform_id, table_name, platform_instance, env)构建见 dataset.py。2.2 Schema支持多种输入形式schema参数类型SchemaFieldsInputType支持两种形式见 dataset.py字段元组序列每个字段可以是(name, type)或(name, type, description)SDK 内部会调用resolve_sql_type将原生类型映射为 DataHub 的SchemaFieldDataTypeClass并保留nativeDataType原始字符串见 dataset.py完整的SchemaMetadataClass对象直接透传给 Aspect。字段类型之所以不提供枚举变体是因为那会强制用户在原生类型与 SDK 枚举之间做映射直接传字符串由 SDK 内部解析更符合直觉见 dataset.py。2.3 字段级操作SchemaField通过dataset[field_path]下标访问见 dataset.py可以拿到SchemaField对象它封装了 Schema 字段的读写能力field_path、mapped_type、native_type、description等属性set_description、set_tags、add_tag、remove_tag、set_terms、add_term、remove_term等方法。字段级操作背后是「基础 Schema」与「可编辑 Schema」双轨机制基础字段存在于SchemaMetadataClass而可编辑字段存在于EditableSchemaMetadataClass读取时通过first_non_null合并两者见 dataset.py。2.4 血缘Upstream 与 Column-Level Lineageupstreams参数类型UpstreamLineageInputType见 dataset.py支持三种输入UpstreamLineageClass对象直接透传列表元素可以是DatasetUrn/字符串 URN自动包装为TRANSFORMED类型的UpstreamClass、UpstreamClass或FineGrainedLineageClassSDK 自动将表级与列级血缘拆分到upstreams与fineGrainedLineages字段见 dataset.py字典{上游数据集 URN - {下游列 - [上游列]}}的列级血缘映射由parse_cll_mapping展开为FineGrainedLineageClass见 dataset.py。2.5 View 定义与自动血缘解析这是Dataset最具特色的能力见 dataset.py当传入view_definitionSQL 字符串时SDK 默认自动解析 SQL 提取上游表级血缘行为由parse_view_lineage控制取值行为None默认SDK 模式下自动解析在 ingestion 框架内跳过此时由SqlParsingAggregator处理更准确的血缘True强制解析即使在 ingestion 框架内False永不自动解析需手动设置upstreams解析基于 sqlglot可选依赖需pip install acryl-datahub[sql-parser]具备以下特性与限制见 dataset.py支持 Snowflake、BigQuery、Postgres 等主流 SQL 方言自动过滤 CTECommon Table Expressions不将其误判为上游表解析失败时优雅降级不抛出异常仅提供表级血缘无列级血缘表名按 SQL 原样提取建议视图定义使用db.schema.table全限定名属于尽力而为的提取生产级血缘含 Schema 解析、临时表处理请使用SqlParsingAggregator。典型用法# 默认自动解析view.upstreams 将包含 analytics.raw.sales view Dataset( platformsnowflake, nameanalytics.reporting.sales_summary, view_definitionSELECT * FROM analytics.raw.sales WHERE year 2024, ) # 关闭自动解析手动设置血缘 view Dataset( platformsnowflake, nameanalytics.reporting.sales_summary, view_definitionSELECT * FROM analytics.raw.sales, parse_view_lineageFalse, )三、Container数据集的组织单元Container见 container.py表示数据集的父级组织单元如数据库、Schema、目录、命名空间。其构造函数第一个位置参数是container_key: ContainerKey用于生成ContainerUrn必须提供display_name。构造参数包括身份container_key必填可传ContainerUrn以便图反序列化属性display_name必填、qualified_name、description、external_url、extra_properties自定义属性字典、created、last_modified标准 Aspectparent_container默认值为auto——当不显式提供时SDK 会自动调用container_key.parent_key()推导父容器见 container.py其余包括subtype、owners、links、tags、terms、domain、structured_properties。实现细节ContainerPropertiesClass是核心 Aspect_ensure_container_props强制要求容器必须有name而ContainerKey的属性会被合并写入customProperties用于还原容器层级见 container.py。四、数据管道实体DataFlow 与 DataJobDataFlow 与 DataJob 用于描述数据管道例如 Airflow DAG 及其中的 Task、Spark 作业等。4.1 DataFlow数据流的编排单元DataFlow见 dataflow.py代表一条数据流如 Airflow DAG。构造参数身份name必填、platform必填如airflow、display_name、platform_instance、env默认DEFAULT_ENV属性description、external_url、custom_properties、created、last_modified标准 Aspectsubtype、owners、links、tags、terms、domain、parent_container、structured_properties。值得注意的实现细节是_normalize_env见 dataflow.pyURN 中的 cluster 是自由字符串如 Airflow 默认的prod而DataFlowInfo.env是FabricType枚举字段要求大写值并驱动 Environment 搜索过滤无匹配时该字段置为None并输出 debug 日志Environment 过滤对该实体不生效。4.2 DataJob数据流中的可执行单元DataJob见 datajob.py表示管道中的一个可执行任务。构造时必须提供以下二者之一flowDataFlow对象或flow_urnDataFlowUrn/字符串否则抛出ValueError见 datajob.py。核心参数身份name必填、flow或flow_urn、platform_instance、display_name血缘相关inlets输入数据集列表、outlets输出数据集列表、fine_grained_lineages列级血缘列表底层写入DataJobInputOutputClassAspect属性与标准 Aspectdescription、external_url、custom_properties、created、last_modified、subtype、owners、links、tags、terms、domain、structured_properties。此外DataJob会自动基于所属DataFlow的 Browse Path 扩展自己的BrowsePathsV2Class把 job 挂载到 flow 下见 datajob.py。五、可视化实体Chart 与 Dashboard5.1 Chart单个可视化图表Chart见 chart.py表示单个图表。构造参数见 chart.py身份name必填、platform必填如looker、display_name、platform_instance图表属性description、external_url、chart_url、custom_properties、last_modified、last_modified_by、created_at、created_by、deleted_on、deleted_by、last_refreshed、chart_type、access、input_datasets输入数据集序列可传Dataset对象、URN 或字符串见 chart.py标准 Aspectparent_container、subtype、owners、links、tags、terms、domain。实现上ChartInfoClass是承载核心属性的 Aspect_ensure_chart_props以urn.chart_id兜底标题见 chart.pychart_type与access传入字符串时会通过get_enum_options校验合法性见 chart.py。5.2 Dashboard仪表盘与多级聚合Dashboard见 dashboard.py表示仪表盘支持input_datasets输入数据集、charts图表列表、dashboards子仪表盘列表三种关联对象各自可通过set_*/add_*/remove_*方法维护。这些关联在底层表现为DashboardInfoClass中的datasetEdges、chartEdges、dashboards边列表见 dashboard.py从而构建「数据集 → 图表 → 仪表盘」的完整可视化血缘链。六、机器学习实体MLModel 与 MLModelGroup6.1 MLModel机器学习模型MLModel见 mlmodel.py表示一个已训练的 ML 模型。构造签名与 Dataset 不同身份参数为位置参数id、platform其余为关键字参数身份id必填、platform必填、version、aliases别名列表、platform_instance、env默认DEFAULT_ENV模型属性name、description、training_metrics训练指标、hyper_params超参数、external_url、custom_properties、created、last_modified关联model_group所属模型组MlModelGroupUrn或字符串、training_jobs、downstream_jobs训练/下游任务标准 Aspectowners、links、tags、terms、domain、structured_properties。6.2 MLModelGroup模型分组MLModelGroup见 mlmodelgroup.py用于对模型分组管理。构造参数包括id、platform均为必填位置参数、name、platform_instance、env、description、display_name、external_url、custom_properties、created、last_modified以及training_jobs、downstream_jobsDataProcessInstanceUrn序列和全部标准 Aspect 参数。七、语义层实体SemanticModel 与 MetricSemanticModel 与 Metric 是 SDK 中面向语义层Semantic Layer的实体将物理表映射为可被业务与 AI 直接消费的逻辑模型。7.1 SemanticModel语义模型SemanticModel见 semantic_model.py表示一个语义模型。构造参数身份platform、path、id三个均为必填共同构成SemanticModelUrn属性name、description、created、last_modified、native_definition原生定义如CREATE SEMANTIC VIEW ...、ai_context结构与关联datasets逻辑数据集序列类型为SemanticModelDataset、relationships逻辑数据集之间的 Join 关系。SemanticModelRelationshipInput见 semantic_model.py描述两个逻辑数据集之间的连接路径from_alias/to_alias必须与对应SemanticModelDataset的alias一致配合from_columns/to_columns指定连接列另有可选的name、cardinality、ai_context。SemanticFieldInput见 semantic_model.py描述逻辑字段field_path、type、semantic_type必填expression省略时会自动合成为f{alias}.{field_path}使字段引用自身的逻辑数据集。初始化顺序的细节datasets在所有其它属性之后处理见 semantic_model.py这样add_dataset可以在SemanticModelDataset的alias已填充后正确建立反向引用。SemanticModelDataset是Dataset的子类型见 semantic_model.py但它没有注册进ENTITY_CLASSES——否则每个 dataset URN 都会被反序列化为SemanticModelDataset从图中读回逻辑数据集时保持为Dataset才是正确行为见 _all_entities.py。7.2 Metric语义模型中的指标Metric见 metric.py表示语义模型中的指标定义。构造参数身份platform、path、id必填与semantic_model必填所属语义模型 URN指标属性name、description、created、last_modified、expression指标表达式、derived_from派生来源、upstream_datasets上游数据集、ai_context标准 Aspectowners、links、tags、terms、domain、structured_properties。实现上Metric与SemanticModel构造时会写入StatusClass(removedFalse)作为生产者契约的一部分见 metric.pyderived_from与upstream_datasets即使为空也会显式发射以清除陈旧的父子指标关系与数据集上游见 metric.py。八、实体使用模式与实战示例8.1 标准使用流程实体的通用用法遵循「构造实体 → 挂载 DataHubClient → upsert」三步。datahub.sdk包导出了全部实体类与DataHubClient见init.py其中Dataset、Container、Chart、Dashboard、DataFlow、DataJob、MLModel、MLModelGroup、SemanticModel、Metric等均可在from datahub.sdk import ...下直接导入。8.2 完整示例数据集 Schema 与字段标签以下示例来自仓库 dataset_schema_with_tags_terms.py演示了构造带 Schema 的 Dataset 并对字段添加标签与术语from datahub.sdk import DataHubClient, Dataset, GlossaryTermUrn, TagUrn client DataHubClient.from_env() dataset Dataset( platformhive, namefoodb.barTable, envPROD, schema[ ( address.zipcode, VARCHAR(100), This is the zipcode of the address. Specified using extended form and limited to addresses in the United States, ), ], ) dataset[address.zipcode].add_tag(TagUrn(location)) dataset[address.zipcode].add_term(GlossaryTermUrn(Classification.PII)) client.entities.upsert(dataset)注意schema使用(name, type, description)三元组形式字段级add_tag/add_term依赖dataset[字段路径]下标访问。8.3 完整示例DataFlow DataJob 管道建模以下示例来自仓库 datajob_create_full.py演示了 Airflow 风格管道建模与「DataJob 自动继承 flow 的平台与平台实例」机制from datahub.metadata.urns import DatasetUrn, TagUrn from datahub.sdk import DataFlow, DataHubClient, DataJob client DataHubClient.from_env() dataflow DataFlow( platformairflow, nameexample_dag, platform_instancePROD, descriptionexample dataflow, tags[TagUrn(nametag1), TagUrn(nametag2)], ) datajob DataJob( nameexample_datajob, flowdataflow, # 继承 platform 与 platform_instance inlets[DatasetUrn(platformhdfs, namedataset1, envPROD)], outlets[DatasetUrn(platformhdfs, namedataset2, envPROD)], ) client.entities.upsert(dataflow) client.entities.upsert(datajob)8.4 完整示例Chart 创建以下示例来自仓库 chart_create_simple.pyfrom datahub.metadata.urns import TagUrn from datahub.sdk import Chart, DataHubClient client DataHubClient.from_env() chart Chart( nameexample_chart, platformlooker, descriptionlooker chart for production, tags[TagUrn(nameproduction), TagUrn(namedata_engineering)], ) client.entities.upsert(chart)8.5 完整示例SemanticModel 构建以下示例来自仓库单元测试 test_semantic_model.py演示了语义模型的核心 Aspect 生成from datahub.sdk import SemanticModel model SemanticModel( platformsnowflake, pathanalytics, idorders_model, nameOrders Model, descriptionOrders semantic model, ) assert model.urn SemanticModelUrn( urn:li:dataPlatform:snowflake, analytics, orders_model )构造后实体自动携带statusremovedFalse与semanticModelInfo两个 Aspect当未提供ai_context时不会生成aiContextAspect。九、进阶实体的底层机制9.1 URN 与 Aspect 的映射每个实体类通过get_urn_type()声明自己的 URN 类型如Dataset→DatasetUrnURN 即实体的全局唯一标识。实体的「内容」由一组 Aspect 承载_get_aspect(type)按 Aspect 类型读取_set_aspect(value)写入_setdefault_aspect(default)实现「不存在才写入」的字典式语义见 entity.py。例如 Dataset 的description读写同时涉及DatasetPropertiesClass基础与EditableDatasetPropertiesClass可编辑两个 Aspect。9.2 从实体到 MCP 再到 WorkUnitas_mcps(change_typeUPSERT)将实体当前的全部 Aspect 逐一封装为MetadataChangeProposalWrapperas_workunits()再将每个 MCP 转为MetadataWorkUnit从而无缝接入 DataHub 的 ingestion 管道见 entity.py。这套机制意味着实体的每次修改最终都会转化为对图存储的一次 UPSERT。9.3 图反序列化_new_from_graph所有实体都实现了_new_from_graph(cls, urn, current_aspects)类方法用于从图中已存在的 URN 与 Aspect 重建实体对象如Dataset._new_from_graph见 dataset.py。EntityClient依赖此机制将查询结果水合hydrate为可操作的实体实例从而支持「读取 → 修改 → 回写」的完整生命周期。十、边界说明与最佳实践实验性状态当前datahub.sdk处于实验阶段from datahub.sdk import ...会触发ExperimentalWarning官方提示其稳定后导入路径将变为from datahub import ...见init.py编写代码时应注意版本兼容注意 Sentinel 语义parent_container的unset表示「未显式设置」与None语义不同Container的parent_container使用auto表示「自动从 ContainerKey 推导」三者的差异需在实际使用中区分Ingestion 模式差异Dataset.set_description等方法在 ingestion 归因模式下会警告「覆盖非 ingestion 内容属于反模式」并强制写入基础 Aspect 以让 ingestion 内容可见见 dataset.py环境字段规范化Airflow 等平台的env/cluster 自由字符串与FabricType枚举之间存在映射关系需确保使用PROD、DEV等标准值以支持 Environment 过滤见 dataflow.py。参考资料SDK Entities Reference 源文档实体基类与 Aspect 机制entity.py实体注册表_all_entities.pySDK 包导出init.py单元测试test_semantic_model.py、test_metric.py可运行示例datajob_create_full.py、dataset_schema_with_tags_terms.py、chart_create_simple.py【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DataHub SDK Entities 全解析：从 Dataset 到 Semantic Model 的实体编程指南
DataHub SDK Entities 全解析从 Dataset 到 Semantic Model 的实体编程指南【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub本文基于 DataHub 开源仓库中 entities.rst 文档展开系统梳理datahub.sdk下全部核心实体类的构造参数、底层 Aspect 机制与实战用法。你将掌握如何使用 Dataset、Container、DataFlow/DataJob、Chart/Dashboard、MLModel/MLModelGroup、SemanticModel/Metric 等实体构建 DataHub 元数据并理解实体与 URN、Aspect、MCP 之间的底层映射关系可直接将代码模式迁移到自己的元数据管理场景中。一、SDK 实体体系总览DataHub SDK 提供了一组实体Entities用于与 DataHub 元数据交互。正如 entities.rst 所述这些实体覆盖了数据目录中最常见的对象类型数据集、容器、机器学习模型、仪表盘、图表、数据任务、数据流、语义模型与指标。在源码层面所有实体都继承自 entity.py 中定义的抽象基类Entity每个实体对应一种 URN 类型如DatasetUrn、ContainerUrn通过get_urn_type()类方法声明最终由ENTITY_CLASSES字典完成「实体类型名 → 实体类」的注册见 _all_entities.py每个实体内部维护_aspectsAspect 集合对实体的修改本质上是读写对应的 Aspect实体可通过as_mcps()转换为一条条MetadataChangeProposalWrapperMCP再经as_workunits()转为MetadataWorkUnit从而接入 DataHub 的元数据写入管道见 entity.py。Entity基类不允许直接实例化会抛出SdkUsageError必须使用其子类例如Dataset或Container。实体类之间通过 Mixin 复用通用能力例如HasTags标签、HasTerms术语、HasOwnership所有权、HasDomain域、HasContainer父容器、HasSubtype子类型、HasInstitutionalMemory机构记忆、HasStructuredProperties结构化属性等具体定义见 _shared.py。二、Dataset数据目录的核心实体Dataset在 dataset.py 中定义表示 DataHub 中的数据集——一张表、一个视图或一个文件。它是 SDK 中功能最完整的实体同时实现了HasPlatformInstance、HasSubtype、HasContainer、HasOwnership、HasInstitutionalMemory、HasTags、HasTerms、HasDomain、HasStructuredProperties等全部通用能力。2.1 构造参数详解Dataset.__init__的完整签名见 dataset.py如下身份标识platform平台名如mysql、snowflake、name数据集名、platform_instance可选平台实例、env环境默认DEFAULT_ENV即PROD数据集属性description、display_name、qualified_name、external_url、custom_properties字典、created/last_modifieddatetime对象、view_definition视图定义标准 Aspectparent_container父容器默认哨兵值unset、subtype、owners、links、tags、terms、domain数据集专属schemaSchema 定义、upstreams上游血缘、structured_properties、extra_aspects、parse_view_lineage视图血缘解析开关。URN 通过DatasetUrn.create_from_ids(platform_id, table_name, platform_instance, env)构建见 dataset.py。2.2 Schema支持多种输入形式schema参数类型SchemaFieldsInputType支持两种形式见 dataset.py字段元组序列每个字段可以是(name, type)或(name, type, description)SDK 内部会调用resolve_sql_type将原生类型映射为 DataHub 的SchemaFieldDataTypeClass并保留nativeDataType原始字符串见 dataset.py完整的SchemaMetadataClass对象直接透传给 Aspect。字段类型之所以不提供枚举变体是因为那会强制用户在原生类型与 SDK 枚举之间做映射直接传字符串由 SDK 内部解析更符合直觉见 dataset.py。2.3 字段级操作SchemaField通过dataset[field_path]下标访问见 dataset.py可以拿到SchemaField对象它封装了 Schema 字段的读写能力field_path、mapped_type、native_type、description等属性set_description、set_tags、add_tag、remove_tag、set_terms、add_term、remove_term等方法。字段级操作背后是「基础 Schema」与「可编辑 Schema」双轨机制基础字段存在于SchemaMetadataClass而可编辑字段存在于EditableSchemaMetadataClass读取时通过first_non_null合并两者见 dataset.py。2.4 血缘Upstream 与 Column-Level Lineageupstreams参数类型UpstreamLineageInputType见 dataset.py支持三种输入UpstreamLineageClass对象直接透传列表元素可以是DatasetUrn/字符串 URN自动包装为TRANSFORMED类型的UpstreamClass、UpstreamClass或FineGrainedLineageClassSDK 自动将表级与列级血缘拆分到upstreams与fineGrainedLineages字段见 dataset.py字典{上游数据集 URN - {下游列 - [上游列]}}的列级血缘映射由parse_cll_mapping展开为FineGrainedLineageClass见 dataset.py。2.5 View 定义与自动血缘解析这是Dataset最具特色的能力见 dataset.py当传入view_definitionSQL 字符串时SDK 默认自动解析 SQL 提取上游表级血缘行为由parse_view_lineage控制取值行为None默认SDK 模式下自动解析在 ingestion 框架内跳过此时由SqlParsingAggregator处理更准确的血缘True强制解析即使在 ingestion 框架内False永不自动解析需手动设置upstreams解析基于 sqlglot可选依赖需pip install acryl-datahub[sql-parser]具备以下特性与限制见 dataset.py支持 Snowflake、BigQuery、Postgres 等主流 SQL 方言自动过滤 CTECommon Table Expressions不将其误判为上游表解析失败时优雅降级不抛出异常仅提供表级血缘无列级血缘表名按 SQL 原样提取建议视图定义使用db.schema.table全限定名属于尽力而为的提取生产级血缘含 Schema 解析、临时表处理请使用SqlParsingAggregator。典型用法# 默认自动解析view.upstreams 将包含 analytics.raw.sales view Dataset( platformsnowflake, nameanalytics.reporting.sales_summary, view_definitionSELECT * FROM analytics.raw.sales WHERE year 2024, ) # 关闭自动解析手动设置血缘 view Dataset( platformsnowflake, nameanalytics.reporting.sales_summary, view_definitionSELECT * FROM analytics.raw.sales, parse_view_lineageFalse, )三、Container数据集的组织单元Container见 container.py表示数据集的父级组织单元如数据库、Schema、目录、命名空间。其构造函数第一个位置参数是container_key: ContainerKey用于生成ContainerUrn必须提供display_name。构造参数包括身份container_key必填可传ContainerUrn以便图反序列化属性display_name必填、qualified_name、description、external_url、extra_properties自定义属性字典、created、last_modified标准 Aspectparent_container默认值为auto——当不显式提供时SDK 会自动调用container_key.parent_key()推导父容器见 container.py其余包括subtype、owners、links、tags、terms、domain、structured_properties。实现细节ContainerPropertiesClass是核心 Aspect_ensure_container_props强制要求容器必须有name而ContainerKey的属性会被合并写入customProperties用于还原容器层级见 container.py。四、数据管道实体DataFlow 与 DataJobDataFlow 与 DataJob 用于描述数据管道例如 Airflow DAG 及其中的 Task、Spark 作业等。4.1 DataFlow数据流的编排单元DataFlow见 dataflow.py代表一条数据流如 Airflow DAG。构造参数身份name必填、platform必填如airflow、display_name、platform_instance、env默认DEFAULT_ENV属性description、external_url、custom_properties、created、last_modified标准 Aspectsubtype、owners、links、tags、terms、domain、parent_container、structured_properties。值得注意的实现细节是_normalize_env见 dataflow.pyURN 中的 cluster 是自由字符串如 Airflow 默认的prod而DataFlowInfo.env是FabricType枚举字段要求大写值并驱动 Environment 搜索过滤无匹配时该字段置为None并输出 debug 日志Environment 过滤对该实体不生效。4.2 DataJob数据流中的可执行单元DataJob见 datajob.py表示管道中的一个可执行任务。构造时必须提供以下二者之一flowDataFlow对象或flow_urnDataFlowUrn/字符串否则抛出ValueError见 datajob.py。核心参数身份name必填、flow或flow_urn、platform_instance、display_name血缘相关inlets输入数据集列表、outlets输出数据集列表、fine_grained_lineages列级血缘列表底层写入DataJobInputOutputClassAspect属性与标准 Aspectdescription、external_url、custom_properties、created、last_modified、subtype、owners、links、tags、terms、domain、structured_properties。此外DataJob会自动基于所属DataFlow的 Browse Path 扩展自己的BrowsePathsV2Class把 job 挂载到 flow 下见 datajob.py。五、可视化实体Chart 与 Dashboard5.1 Chart单个可视化图表Chart见 chart.py表示单个图表。构造参数见 chart.py身份name必填、platform必填如looker、display_name、platform_instance图表属性description、external_url、chart_url、custom_properties、last_modified、last_modified_by、created_at、created_by、deleted_on、deleted_by、last_refreshed、chart_type、access、input_datasets输入数据集序列可传Dataset对象、URN 或字符串见 chart.py标准 Aspectparent_container、subtype、owners、links、tags、terms、domain。实现上ChartInfoClass是承载核心属性的 Aspect_ensure_chart_props以urn.chart_id兜底标题见 chart.pychart_type与access传入字符串时会通过get_enum_options校验合法性见 chart.py。5.2 Dashboard仪表盘与多级聚合Dashboard见 dashboard.py表示仪表盘支持input_datasets输入数据集、charts图表列表、dashboards子仪表盘列表三种关联对象各自可通过set_*/add_*/remove_*方法维护。这些关联在底层表现为DashboardInfoClass中的datasetEdges、chartEdges、dashboards边列表见 dashboard.py从而构建「数据集 → 图表 → 仪表盘」的完整可视化血缘链。六、机器学习实体MLModel 与 MLModelGroup6.1 MLModel机器学习模型MLModel见 mlmodel.py表示一个已训练的 ML 模型。构造签名与 Dataset 不同身份参数为位置参数id、platform其余为关键字参数身份id必填、platform必填、version、aliases别名列表、platform_instance、env默认DEFAULT_ENV模型属性name、description、training_metrics训练指标、hyper_params超参数、external_url、custom_properties、created、last_modified关联model_group所属模型组MlModelGroupUrn或字符串、training_jobs、downstream_jobs训练/下游任务标准 Aspectowners、links、tags、terms、domain、structured_properties。6.2 MLModelGroup模型分组MLModelGroup见 mlmodelgroup.py用于对模型分组管理。构造参数包括id、platform均为必填位置参数、name、platform_instance、env、description、display_name、external_url、custom_properties、created、last_modified以及training_jobs、downstream_jobsDataProcessInstanceUrn序列和全部标准 Aspect 参数。七、语义层实体SemanticModel 与 MetricSemanticModel 与 Metric 是 SDK 中面向语义层Semantic Layer的实体将物理表映射为可被业务与 AI 直接消费的逻辑模型。7.1 SemanticModel语义模型SemanticModel见 semantic_model.py表示一个语义模型。构造参数身份platform、path、id三个均为必填共同构成SemanticModelUrn属性name、description、created、last_modified、native_definition原生定义如CREATE SEMANTIC VIEW ...、ai_context结构与关联datasets逻辑数据集序列类型为SemanticModelDataset、relationships逻辑数据集之间的 Join 关系。SemanticModelRelationshipInput见 semantic_model.py描述两个逻辑数据集之间的连接路径from_alias/to_alias必须与对应SemanticModelDataset的alias一致配合from_columns/to_columns指定连接列另有可选的name、cardinality、ai_context。SemanticFieldInput见 semantic_model.py描述逻辑字段field_path、type、semantic_type必填expression省略时会自动合成为f{alias}.{field_path}使字段引用自身的逻辑数据集。初始化顺序的细节datasets在所有其它属性之后处理见 semantic_model.py这样add_dataset可以在SemanticModelDataset的alias已填充后正确建立反向引用。SemanticModelDataset是Dataset的子类型见 semantic_model.py但它没有注册进ENTITY_CLASSES——否则每个 dataset URN 都会被反序列化为SemanticModelDataset从图中读回逻辑数据集时保持为Dataset才是正确行为见 _all_entities.py。7.2 Metric语义模型中的指标Metric见 metric.py表示语义模型中的指标定义。构造参数身份platform、path、id必填与semantic_model必填所属语义模型 URN指标属性name、description、created、last_modified、expression指标表达式、derived_from派生来源、upstream_datasets上游数据集、ai_context标准 Aspectowners、links、tags、terms、domain、structured_properties。实现上Metric与SemanticModel构造时会写入StatusClass(removedFalse)作为生产者契约的一部分见 metric.pyderived_from与upstream_datasets即使为空也会显式发射以清除陈旧的父子指标关系与数据集上游见 metric.py。八、实体使用模式与实战示例8.1 标准使用流程实体的通用用法遵循「构造实体 → 挂载 DataHubClient → upsert」三步。datahub.sdk包导出了全部实体类与DataHubClient见init.py其中Dataset、Container、Chart、Dashboard、DataFlow、DataJob、MLModel、MLModelGroup、SemanticModel、Metric等均可在from datahub.sdk import ...下直接导入。8.2 完整示例数据集 Schema 与字段标签以下示例来自仓库 dataset_schema_with_tags_terms.py演示了构造带 Schema 的 Dataset 并对字段添加标签与术语from datahub.sdk import DataHubClient, Dataset, GlossaryTermUrn, TagUrn client DataHubClient.from_env() dataset Dataset( platformhive, namefoodb.barTable, envPROD, schema[ ( address.zipcode, VARCHAR(100), This is the zipcode of the address. Specified using extended form and limited to addresses in the United States, ), ], ) dataset[address.zipcode].add_tag(TagUrn(location)) dataset[address.zipcode].add_term(GlossaryTermUrn(Classification.PII)) client.entities.upsert(dataset)注意schema使用(name, type, description)三元组形式字段级add_tag/add_term依赖dataset[字段路径]下标访问。8.3 完整示例DataFlow DataJob 管道建模以下示例来自仓库 datajob_create_full.py演示了 Airflow 风格管道建模与「DataJob 自动继承 flow 的平台与平台实例」机制from datahub.metadata.urns import DatasetUrn, TagUrn from datahub.sdk import DataFlow, DataHubClient, DataJob client DataHubClient.from_env() dataflow DataFlow( platformairflow, nameexample_dag, platform_instancePROD, descriptionexample dataflow, tags[TagUrn(nametag1), TagUrn(nametag2)], ) datajob DataJob( nameexample_datajob, flowdataflow, # 继承 platform 与 platform_instance inlets[DatasetUrn(platformhdfs, namedataset1, envPROD)], outlets[DatasetUrn(platformhdfs, namedataset2, envPROD)], ) client.entities.upsert(dataflow) client.entities.upsert(datajob)8.4 完整示例Chart 创建以下示例来自仓库 chart_create_simple.pyfrom datahub.metadata.urns import TagUrn from datahub.sdk import Chart, DataHubClient client DataHubClient.from_env() chart Chart( nameexample_chart, platformlooker, descriptionlooker chart for production, tags[TagUrn(nameproduction), TagUrn(namedata_engineering)], ) client.entities.upsert(chart)8.5 完整示例SemanticModel 构建以下示例来自仓库单元测试 test_semantic_model.py演示了语义模型的核心 Aspect 生成from datahub.sdk import SemanticModel model SemanticModel( platformsnowflake, pathanalytics, idorders_model, nameOrders Model, descriptionOrders semantic model, ) assert model.urn SemanticModelUrn( urn:li:dataPlatform:snowflake, analytics, orders_model )构造后实体自动携带statusremovedFalse与semanticModelInfo两个 Aspect当未提供ai_context时不会生成aiContextAspect。九、进阶实体的底层机制9.1 URN 与 Aspect 的映射每个实体类通过get_urn_type()声明自己的 URN 类型如Dataset→DatasetUrnURN 即实体的全局唯一标识。实体的「内容」由一组 Aspect 承载_get_aspect(type)按 Aspect 类型读取_set_aspect(value)写入_setdefault_aspect(default)实现「不存在才写入」的字典式语义见 entity.py。例如 Dataset 的description读写同时涉及DatasetPropertiesClass基础与EditableDatasetPropertiesClass可编辑两个 Aspect。9.2 从实体到 MCP 再到 WorkUnitas_mcps(change_typeUPSERT)将实体当前的全部 Aspect 逐一封装为MetadataChangeProposalWrapperas_workunits()再将每个 MCP 转为MetadataWorkUnit从而无缝接入 DataHub 的 ingestion 管道见 entity.py。这套机制意味着实体的每次修改最终都会转化为对图存储的一次 UPSERT。9.3 图反序列化_new_from_graph所有实体都实现了_new_from_graph(cls, urn, current_aspects)类方法用于从图中已存在的 URN 与 Aspect 重建实体对象如Dataset._new_from_graph见 dataset.py。EntityClient依赖此机制将查询结果水合hydrate为可操作的实体实例从而支持「读取 → 修改 → 回写」的完整生命周期。十、边界说明与最佳实践实验性状态当前datahub.sdk处于实验阶段from datahub.sdk import ...会触发ExperimentalWarning官方提示其稳定后导入路径将变为from datahub import ...见init.py编写代码时应注意版本兼容注意 Sentinel 语义parent_container的unset表示「未显式设置」与None语义不同Container的parent_container使用auto表示「自动从 ContainerKey 推导」三者的差异需在实际使用中区分Ingestion 模式差异Dataset.set_description等方法在 ingestion 归因模式下会警告「覆盖非 ingestion 内容属于反模式」并强制写入基础 Aspect 以让 ingestion 内容可见见 dataset.py环境字段规范化Airflow 等平台的env/cluster 自由字符串与FabricType枚举之间存在映射关系需确保使用PROD、DEV等标准值以支持 Environment 过滤见 dataflow.py。参考资料SDK Entities Reference 源文档实体基类与 Aspect 机制entity.py实体注册表_all_entities.pySDK 包导出init.py单元测试test_semantic_model.py、test_metric.py可运行示例datajob_create_full.py、dataset_schema_with_tags_terms.py、chart_create_simple.py【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考