DataHub Structured Properties 实战指南从 YAML 定义到 CLI 与 Python SDK 的元数据治理【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub导读本文基于 DataHub 仓库中 structured_properties 示例目录 的完整配套示例系统讲解 DataHub 结构化属性Structured Properties的定义、注册与赋值全流程你将掌握如何用一份 YAML 文件声明带类型、基数、枚举取值与实体范围约束的属性字典如何通过datahub properties系列 CLI 命令完成创建与查询如何借助datahub dataset命令把属性值挂到数据集、字段乃至 Topic 上以及如何用 Python SDK 以编程方式创建、更新和枚举属性。读完本文你可以直接基于仓库内的示例文件为你的元数据治理场景如数据保留期、复制 SLA、废弃日期、数据责任人搭建一套可复用的属性体系。一、什么是 Structured Properties给元数据加上自定义字段DataHub 的元数据模型虽然内置了描述、标签、术语表等标准能力但真实业务往往需要带类型的自定义元数据字段例如该数据集的数据保留期是多少天副本延迟不得超过多少小时数据责任人是谁。Structured Properties结构化属性正是为此设计的一等公民它是一套先声明、后赋值的元数据扩展机制属性本身拥有明确的类型字符串、数字、日期、URN、富文本与基数单值/多值并能限定可挂载的实体类型和允许的取值枚举。从源码看结构化属性在底层以StructuredPropertyDefinition这一 Aspect 落盘见 structuredproperties.py 的generate_mcps()方法每个属性对应一个形如urn:li:structuredProperty:id的 URN属性定义通过MetadataChangeProposalWrapperMCP写入 GMS之后再以 MCP 形式把属性值附加到目标实体上。整个链路与 DataHub 其他元数据写入通道完全一致因此既可以用 CLI 操作也可以用 REST/Kafka Emitter 编程驱动。二、用 YAML 声明属性字典字段全解与完整示例仓库中的 structured_properties.yaml 是一份可直接运行的属性声明文件定义了 7 个覆盖不同数据类型的属性。其结构如下节选并标注注释- id: io.acryl.privacy.retentionTime # 可选显式指定 URN 时qualified_name 必须与 URN 中的 id 一致 # urn: urn:li:structuredProperty:io.acryl.privacy.retentionTime qualified_name: io.acryl.privacy.retentionTime # 提供 urn 时为必填 type: number version: 1.0.0 cardinality: MULTIPLE display_name: Retention Time entity_types: - dataset # 或 urn:li:entityType:datahub.dataset - dataFlow description: Retention Time is used to figure out how long to retain records in a dataset allowed_values: - value: 30 description: 30 days, usually reserved for datasets that are ephemeral and contain pii - value: 90 description: Use this for datasets that drive monthly reporting but contain pii - value: 365 description: Use this for non-sensitive data that can be retained for longer - id: io.acryl.dataManagement.replicationSLA type: number display_name: Replication SLA description: SLA for how long data can be delayed before replicating to the destination cluster entity_types: - dataset - id: io.acryl.dataManagement.deprecationDate type: date display_name: Deprecation Date entity_types: - dataset - dataFlow - dataJob - id: io.acryl.dataManagement.steward type: urn type_qualifier: allowed_types: # 仅允许用户和用户组 URN 作为值 - corpuser - corpGroup display_name: Steward entity_types: - dataset - dataFlow - dataJob - id: io.acryl.dataManagement.certifier type: urn display_name: Person Certifying the asset entity_types: - dataset - schemaField - id: projectNames type: string cardinality: MULTIPLE display_name: Project names entity_types: - dataset allowed_values: - value: Tracking description: test value 1 for project - value: DataHub description: test value 2 for project - id: namespace type: string display_name: Namespace entity_types: - dataset字段语义与取值范围对照 StructuredProperties 数据模型各字段含义如下字段是否必填说明id与urn二选一属性短名构成urn:li:structuredProperty:idurn与id二选一完整 URN提供时必须同时给出qualified_name且两者 id 必须一致源码fqn属性会强制断言见 structuredproperties.pyqualified_name提供urn时必填属性的全限定名type必填值类型合法值为string、rich_text、number、date、urn对应源码AllowedTypes枚举见 structuredproperties.py。源码会自动把大写转小写并校验README 示例中的STRING/NUMBER/DATE与 YAML 示例中的小写写法等价cardinality否SINGLE单值或MULTIPLE多值赋值时用列表display_name否在 UI 中展示的友好名称description否属性语义说明entity_types否允许挂载的实体类型如dataset、dataFlow、dataJob、schemaField、container可写短名或完整实体类型 URN。源码会将其统一转换为urn:li:entityType:datahub.xxx并校验合法性见 structuredproperties.pyversion否版本号如1.0.0源码会强制转为字符串见 structuredproperties.pyallowed_values否枚举取值列表每项为value字符串或数字 可选description用于构建下拉式单/多选type_qualifier否类型限定。当type: urn时可用allowed_types限定值只能是指定实体类型的 URN如corpuser、corpGroupimmutable否是否不可变默认falsestructured_property_settings否UI 展示设置见下structured_property_settings支持五个布尔子项源码见 structuredproperties.pyis_hidden是否在 UI 隐藏、show_as_asset_badge作为徽标展示、show_in_asset_summary显示在资产摘要、show_in_columns_table显示在字段列表中、show_in_search_filters作为搜索过滤条件。这些设置会随属性定义一同以StructuredPropertySettingsClassAspect 写入见 structuredproperties.py。设计要点命名空间约定示例采用io.acryl.privacy.*、io.acryl.dataManagement.*的分级前缀便于按团队/业务域组织属性并避免冲突。类型即约束number型属性赋值必须是数值date型属性赋值必须是日期字符串urn型属性赋值必须是合法 URN配合allowed_values可在注册层面就杜绝脏数据。枚举值前后端一致示例中retentionTime的三个枚举值30/90/365在 create_structured_property.py 的 Python SDK 示例里以完全相同的描述出现说明同一属性定义可以用 YAML 或 SDK 两种方式幂等注册。三、CLI 实战注册与查询结构化属性1. 从 YAML 批量注册upsertREADME 给出的核心命令是datahub properties upsert -f structured_properties.yaml其中-f/--file指向 structured_properties.yaml。该命令的底层实现位于 structuredproperties_cli.py以 CLI 模式建立默认 DataHub 连接get_default_graph(ClientMode.CLI)连接参数来自环境变量或~/.datahubenv随后调用StructuredProperties.create()——注意该方法语义上就是存在即更新的 upsert对文件中每个属性由generate_mcps()生成StructuredPropertyDefinition的 MCP 并通过graph.emit_mcp()提交见 structuredproperties.py。因此该命令可以重复执行属性已存在时会按新定义覆盖更新不存在则创建适合纳入 CI 或初始化脚本。2. 逐条创建create如果只想临时建一个属性README 给出了参数化命令datahub properties create --name io.acryl.privacy.retentionTime \ --type STRING \ --cardinality MULTIPLE \ --entity_type DATASET \ --entity_type DATAFLOW--name指定属性 id--type指定值类型--cardinality指定单值/多值--entity_type可重复传参以声明多个允许挂载的实体类型。此命令适合交互式快速验证批量场景仍建议走 YAML 文件。3. 查询与导出get / list除了 README 中的创建命令仓库还提供了配套的查询能力源码见 structuredproperties_cli.py# 按 URN 查询单个属性的完整定义支持 --to-file 导出为 YAML datahub properties get --urn urn:li:structuredProperty:io.acryl.dataManagement.replicationSLA # 列出全部属性默认带详细信息--no-details 只输出 URN 列表 datahub properties list datahub properties list --no-details # 将列表结果写入 YAML 文件已存在文件时按 URN 做增量合并 datahub properties list --to-file properties_backup.yamllist的底层实现是StructuredProperties.list_urns()按实体类型structuredProperty过滤 URNfrom_datahub()读取每个 URN 的StructuredPropertyDefinitionAspect 并反序列化为 YAML 模型见 structuredproperties.py。这套导出→修改→再 upsert的循环可以很方便地实现属性字典的版本管理与迁移。四、给资产打标dataset 命令与 schema 字段级属性定义属性只是第一步真正的业务价值在于把属性值挂到数据资产上。README 指出使用datahub dataset命令完成这一操作datahub dataset upsert -f dataset.yaml示例文件 dataset.yaml 展示了三种赋值场景值得逐段拆解。场景一Hive 表 数据集级与字段级属性- id: user.clicks platform: hive # - urn: urn:li:dataset:(urn:li:dataPlatform:hive,user.clicks,PROD) # 可用 urn 替代 idplatform subtype: Table schema: file: examples/structured_properties/click_event.avsc fields: - id: ip structured_properties: io.acryl.dataManagement.deprecationDate: 2023-01-01 io.acryl.dataManagement.certifier: urn:li:corpuser:john.doeexample.com io.acryl.dataManagement.replicationSLA: 90 - id: url structured_properties: io.acryl.dataManagement.deprecationDate: 2023-01-01 - id: locator.latitude structured_properties: io.acryl.dataManagement.deprecationDate: 2023-01-01 structured_properties: # 数据集级别的结构化属性 io.acryl.privacy.retentionTime: 365 projectNames: - Tracking - DataHub关键点定位实体用idplatform组合定位数据集等价于urn:li:dataset:(urn:li:dataPlatform:hive,user.clicks,PROD)也可直接写urn。Schema 来源schema.file指向 click_event.avscAvro Schema含ip、url、locator.latitude等字段字段 id 需与 Avro 字段名对应。双层赋值structured_properties顶层作用于整个数据集fields[].structured_properties作用于单个字段schemaField实体。示例中deprecationDate同时出现在数据集级和三个字段级正是 README 里把该属性entity_types声明为dataset、dataFlow、dataJob之外还可用于schemaField的体现。多值属性projectNames声明为cardinality: MULTIPLE赋值时使用列表[Tracking, DataHub]单值属性如retentionTime直接赋标量。场景二Event Topic 描述与下游血缘- id: ClickEvent platform: events subtype: Topic description: | This is a sample event that is generated when a user clicks on a link. Do not use this event for any purpose other than testing. properties: project_name: Tracking namespace: org.acryl.tracking version: 1.0.0 retention: 30 structured_properties: io.acryl.dataManagement.certifier: urn:li:corpuser:john.doeexample.com schema: file: examples/structured_properties/click_event.avsc downstreams: - urn:li:dataset:(urn:li:dataPlatform:hive,user.clicks,PROD)该示例说明结构化属性不限于表Topic 实体同样可以挂载如certifier指向具体责任人 URNproperties提供无类型的普通键值元数据downstreams则声明了到 Hive 表的下游血缘。场景三跨平台同名表- id: user.clicks platform: snowflake structured_properties: io.acryl.dataManagement.replicationSLA: 90 schema: fields: - id: user_id structured_properties: io.acryl.dataManagement.deprecationDate: 2023-01-01 type: string同一个user.clicks名称在不同平台hive 与 snowflake是两个不同的数据集实体各自可以拥有不同的属性值——这印证了属性值挂在实体 URN 上的模型设计。从源码看 dataset 命令的落地方式datahub dataset upsert走的是 DataHub 通用数据集写入链路它会把dataset.yaml解析为数据集实体定义将顶层structured_properties写入数据集实体的StructuredPropertiesAspect将字段级属性写入对应schemaField实体的 Aspect并通过 MCP 逐条提交。你可以继续阅读 dataset.yaml 同级的dataproduct示例目录README 末尾提示See example in dataproduct了解更复杂的数据产品场景。五、Python SDK用代码驱动属性生命周期仓库为编程方式使用提供了三个可直接运行的示例脚本。1. 创建属性create_structured_property.py该脚本演示了通过 REST Emitter 创建三种典型属性from datahub.emitter.mcp import MetadataChangeProposalWrapper from datahub.emitter.rest_emitter import DatahubRestEmitter from datahub.metadata.schema_classes import ( PropertyValueClass, StructuredPropertyDefinitionClass, ) from datahub.metadata.urns import StructuredPropertyUrn rest_emitter DatahubRestEmitter(gms_serverhttp://localhost:8080) # 1) 开放文本属性单值、可挂 dataset 与 container text_property_urn StructuredPropertyUrn(io.acryl.openTextProperty) text_property_definition StructuredPropertyDefinitionClass( qualifiedNameio.acryl.openTextProperty, displayNameOpen Text Property, valueTypeurn:li:dataType:datahub.string, cardinalitySINGLE, entityTypes[ urn:li:entityType:datahub.dataset, urn:li:entityType:datahub.container, ], descriptionThis structured property allows a signle open ended response as a value, immutableFalse, ) rest_emitter.emit( MetadataChangeProposalWrapper( entityUrnstr(text_property_urn), aspecttext_property_definition ) )脚本共创建三个属性覆盖三类典型用法属性valueTypecardinality要点io.acryl.openTextPropertyurn:li:dataType:datahub.stringSINGLE开放自由文本io.acryl.dataManagement.dataStewardurn:li:dataType:datahub.urnMULTIPLEtypeQualifier{allowedTypes: [...]}限定只能填corpuser/corpGroupURN且immutableTrueio.acryl.dataManagement.replicationSLAurn:li:dataType:datahub.numberSINGLE通过allowedValues[PropertyValueClass(value30, ...), ...]声明 30/90/365 三个枚举值这里可以看到 YAML 字段与 SDK 参数的对应关系type↔valueType数据类型 URN如urn:li:dataType:datahub.number、entity_types↔entityTypes实体类型 URN、allowed_values↔allowedValuesPropertyValueClass列表、type_qualifier.allowed_types↔typeQualifier[allowedTypes]。启动前需确保本地 GMS 运行于http://localhost:8080。2. 更新属性update_structured_property.pyfrom datahub.emitter.rest_emitter import DataHubRestEmitter from datahub.metadata.urns import StructuredPropertyUrn from datahub.specific.structured_property import StructuredPropertyPatchBuilder property_urn StructuredPropertyUrn(io.acryl.dataManagement.dataSteward) with DataHubRestEmitter(gms_serverhttp://localhost:8080) as emitter: for patch_mcp in ( StructuredPropertyPatchBuilder(str(property_urn)) .set_display_name(test display name) .set_cardinality(MULTIPLE) .add_entity_type(urn:li:entityType:datahub.dataJob) .build() ): emitter.emit(patch_mcp)该示例演示了基于 Patch 的增量更新StructuredPropertyPatchBuilder以链式调用的方式修改展示名、基数并追加允许的实体类型build()产出若干 patch MCP通过 REST Emitter 逐个发送。相比 YAML 全量 upsertPatch 方式只改动指定字段适合精细化变更。脚本中还预留了 Kafka Emitter 的切换分支USE_REST_EMITTER开关 DatahubKafkaEmitter说明同一套 Patch 也可以走 Kafka 通道。3. 枚举属性list_structured_properties.pyfrom datahub.api.entities.structuredproperties.structuredproperties import ( StructuredProperties, ) from datahub.ingestion.graph.client import get_default_graph with get_default_graph() as graph: structuredproperties StructuredProperties.list(graph) for structuredproperty in structuredproperties: print(structuredproperty.dict())该脚本利用get_default_graph()建立默认连接复用 CLI 的认证配置调用StructuredProperties.list()枚举全部属性并逐条打印字典。其执行效果与 CLI 的datahub properties list --details等价适合在自动化脚本中获取属性清单做审计或差异对比。六、底层原理小结YAML → MCP → GMS 的完整链路把前面各部分串起来结构化属性的完整生命周期可以归纳为声明在 YAML 中声明属性id/urn、type、cardinality、entity_types、allowed_values、type_qualifier 等由StructuredPropertiespydantic 模型加载并做字段校验——类型必须是string/rich_text/number/date/urn之一大写自动转小写实体类型必须能转换为合法urn:li:entityType:datahub.*URNid 与 URN 中的 id 必须一致见 structuredproperties.py。写入generate_mcps()把每个属性转换为StructuredPropertyDefinitionClassAspect可选附StructuredPropertySettingsClass打包成 MCP 交给graph.emit_mcp()/ REST / Kafka Emitter 发送至 GMS见 structuredproperties.py。赋值datahub dataset upsert把structured_properties块中的键值对挂到目标实体数据集或schemaField的对应 Aspect 上值必须符合属性声明枚举、类型、URN 限定。消费属性定义与属性值均以 Aspect 形式存储可被properties get/list、StructuredProperties.list()以及 UI 检索与展示。七、实践建议与注意事项属性字典先行先集中维护一份structured_properties.yaml用datahub properties upsert -f一次性注册全部属性再编写dataset.yaml做赋值避免属性未定义就赋值导致校验失败。版本管理利用properties list --to-file导出当前属性字典纳入 Git 版本控制配合version字段标记 Schema 演进。类型与枚举是治理的第一道闸门type: urntype_qualifier.allowed_types可以把责任人、审批人等属性限定为合法用户/用户组allowed_values适合维护如保留期档位这类有限取值。多值与字段级属性MULTIPLE属性赋值用列表字段级属性fields[].structured_properties依赖 schema 定义务必保证字段 id 与 schema如 click_event.avsc中的字段一致。运行前提以上 CLI 与 SDK 示例均需要可用的 DataHub GMS默认http://localhost:8080与配置好的 CLI 认证Kafka 方式还需 broker 与 Schema Registry。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DataHub Structured Properties 实战指南：从 YAML 定义到 CLI 与 Python SDK 的元数据治理
DataHub Structured Properties 实战指南从 YAML 定义到 CLI 与 Python SDK 的元数据治理【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub导读本文基于 DataHub 仓库中 structured_properties 示例目录 的完整配套示例系统讲解 DataHub 结构化属性Structured Properties的定义、注册与赋值全流程你将掌握如何用一份 YAML 文件声明带类型、基数、枚举取值与实体范围约束的属性字典如何通过datahub properties系列 CLI 命令完成创建与查询如何借助datahub dataset命令把属性值挂到数据集、字段乃至 Topic 上以及如何用 Python SDK 以编程方式创建、更新和枚举属性。读完本文你可以直接基于仓库内的示例文件为你的元数据治理场景如数据保留期、复制 SLA、废弃日期、数据责任人搭建一套可复用的属性体系。一、什么是 Structured Properties给元数据加上自定义字段DataHub 的元数据模型虽然内置了描述、标签、术语表等标准能力但真实业务往往需要带类型的自定义元数据字段例如该数据集的数据保留期是多少天副本延迟不得超过多少小时数据责任人是谁。Structured Properties结构化属性正是为此设计的一等公民它是一套先声明、后赋值的元数据扩展机制属性本身拥有明确的类型字符串、数字、日期、URN、富文本与基数单值/多值并能限定可挂载的实体类型和允许的取值枚举。从源码看结构化属性在底层以StructuredPropertyDefinition这一 Aspect 落盘见 structuredproperties.py 的generate_mcps()方法每个属性对应一个形如urn:li:structuredProperty:id的 URN属性定义通过MetadataChangeProposalWrapperMCP写入 GMS之后再以 MCP 形式把属性值附加到目标实体上。整个链路与 DataHub 其他元数据写入通道完全一致因此既可以用 CLI 操作也可以用 REST/Kafka Emitter 编程驱动。二、用 YAML 声明属性字典字段全解与完整示例仓库中的 structured_properties.yaml 是一份可直接运行的属性声明文件定义了 7 个覆盖不同数据类型的属性。其结构如下节选并标注注释- id: io.acryl.privacy.retentionTime # 可选显式指定 URN 时qualified_name 必须与 URN 中的 id 一致 # urn: urn:li:structuredProperty:io.acryl.privacy.retentionTime qualified_name: io.acryl.privacy.retentionTime # 提供 urn 时为必填 type: number version: 1.0.0 cardinality: MULTIPLE display_name: Retention Time entity_types: - dataset # 或 urn:li:entityType:datahub.dataset - dataFlow description: Retention Time is used to figure out how long to retain records in a dataset allowed_values: - value: 30 description: 30 days, usually reserved for datasets that are ephemeral and contain pii - value: 90 description: Use this for datasets that drive monthly reporting but contain pii - value: 365 description: Use this for non-sensitive data that can be retained for longer - id: io.acryl.dataManagement.replicationSLA type: number display_name: Replication SLA description: SLA for how long data can be delayed before replicating to the destination cluster entity_types: - dataset - id: io.acryl.dataManagement.deprecationDate type: date display_name: Deprecation Date entity_types: - dataset - dataFlow - dataJob - id: io.acryl.dataManagement.steward type: urn type_qualifier: allowed_types: # 仅允许用户和用户组 URN 作为值 - corpuser - corpGroup display_name: Steward entity_types: - dataset - dataFlow - dataJob - id: io.acryl.dataManagement.certifier type: urn display_name: Person Certifying the asset entity_types: - dataset - schemaField - id: projectNames type: string cardinality: MULTIPLE display_name: Project names entity_types: - dataset allowed_values: - value: Tracking description: test value 1 for project - value: DataHub description: test value 2 for project - id: namespace type: string display_name: Namespace entity_types: - dataset字段语义与取值范围对照 StructuredProperties 数据模型各字段含义如下字段是否必填说明id与urn二选一属性短名构成urn:li:structuredProperty:idurn与id二选一完整 URN提供时必须同时给出qualified_name且两者 id 必须一致源码fqn属性会强制断言见 structuredproperties.pyqualified_name提供urn时必填属性的全限定名type必填值类型合法值为string、rich_text、number、date、urn对应源码AllowedTypes枚举见 structuredproperties.py。源码会自动把大写转小写并校验README 示例中的STRING/NUMBER/DATE与 YAML 示例中的小写写法等价cardinality否SINGLE单值或MULTIPLE多值赋值时用列表display_name否在 UI 中展示的友好名称description否属性语义说明entity_types否允许挂载的实体类型如dataset、dataFlow、dataJob、schemaField、container可写短名或完整实体类型 URN。源码会将其统一转换为urn:li:entityType:datahub.xxx并校验合法性见 structuredproperties.pyversion否版本号如1.0.0源码会强制转为字符串见 structuredproperties.pyallowed_values否枚举取值列表每项为value字符串或数字 可选description用于构建下拉式单/多选type_qualifier否类型限定。当type: urn时可用allowed_types限定值只能是指定实体类型的 URN如corpuser、corpGroupimmutable否是否不可变默认falsestructured_property_settings否UI 展示设置见下structured_property_settings支持五个布尔子项源码见 structuredproperties.pyis_hidden是否在 UI 隐藏、show_as_asset_badge作为徽标展示、show_in_asset_summary显示在资产摘要、show_in_columns_table显示在字段列表中、show_in_search_filters作为搜索过滤条件。这些设置会随属性定义一同以StructuredPropertySettingsClassAspect 写入见 structuredproperties.py。设计要点命名空间约定示例采用io.acryl.privacy.*、io.acryl.dataManagement.*的分级前缀便于按团队/业务域组织属性并避免冲突。类型即约束number型属性赋值必须是数值date型属性赋值必须是日期字符串urn型属性赋值必须是合法 URN配合allowed_values可在注册层面就杜绝脏数据。枚举值前后端一致示例中retentionTime的三个枚举值30/90/365在 create_structured_property.py 的 Python SDK 示例里以完全相同的描述出现说明同一属性定义可以用 YAML 或 SDK 两种方式幂等注册。三、CLI 实战注册与查询结构化属性1. 从 YAML 批量注册upsertREADME 给出的核心命令是datahub properties upsert -f structured_properties.yaml其中-f/--file指向 structured_properties.yaml。该命令的底层实现位于 structuredproperties_cli.py以 CLI 模式建立默认 DataHub 连接get_default_graph(ClientMode.CLI)连接参数来自环境变量或~/.datahubenv随后调用StructuredProperties.create()——注意该方法语义上就是存在即更新的 upsert对文件中每个属性由generate_mcps()生成StructuredPropertyDefinition的 MCP 并通过graph.emit_mcp()提交见 structuredproperties.py。因此该命令可以重复执行属性已存在时会按新定义覆盖更新不存在则创建适合纳入 CI 或初始化脚本。2. 逐条创建create如果只想临时建一个属性README 给出了参数化命令datahub properties create --name io.acryl.privacy.retentionTime \ --type STRING \ --cardinality MULTIPLE \ --entity_type DATASET \ --entity_type DATAFLOW--name指定属性 id--type指定值类型--cardinality指定单值/多值--entity_type可重复传参以声明多个允许挂载的实体类型。此命令适合交互式快速验证批量场景仍建议走 YAML 文件。3. 查询与导出get / list除了 README 中的创建命令仓库还提供了配套的查询能力源码见 structuredproperties_cli.py# 按 URN 查询单个属性的完整定义支持 --to-file 导出为 YAML datahub properties get --urn urn:li:structuredProperty:io.acryl.dataManagement.replicationSLA # 列出全部属性默认带详细信息--no-details 只输出 URN 列表 datahub properties list datahub properties list --no-details # 将列表结果写入 YAML 文件已存在文件时按 URN 做增量合并 datahub properties list --to-file properties_backup.yamllist的底层实现是StructuredProperties.list_urns()按实体类型structuredProperty过滤 URNfrom_datahub()读取每个 URN 的StructuredPropertyDefinitionAspect 并反序列化为 YAML 模型见 structuredproperties.py。这套导出→修改→再 upsert的循环可以很方便地实现属性字典的版本管理与迁移。四、给资产打标dataset 命令与 schema 字段级属性定义属性只是第一步真正的业务价值在于把属性值挂到数据资产上。README 指出使用datahub dataset命令完成这一操作datahub dataset upsert -f dataset.yaml示例文件 dataset.yaml 展示了三种赋值场景值得逐段拆解。场景一Hive 表 数据集级与字段级属性- id: user.clicks platform: hive # - urn: urn:li:dataset:(urn:li:dataPlatform:hive,user.clicks,PROD) # 可用 urn 替代 idplatform subtype: Table schema: file: examples/structured_properties/click_event.avsc fields: - id: ip structured_properties: io.acryl.dataManagement.deprecationDate: 2023-01-01 io.acryl.dataManagement.certifier: urn:li:corpuser:john.doeexample.com io.acryl.dataManagement.replicationSLA: 90 - id: url structured_properties: io.acryl.dataManagement.deprecationDate: 2023-01-01 - id: locator.latitude structured_properties: io.acryl.dataManagement.deprecationDate: 2023-01-01 structured_properties: # 数据集级别的结构化属性 io.acryl.privacy.retentionTime: 365 projectNames: - Tracking - DataHub关键点定位实体用idplatform组合定位数据集等价于urn:li:dataset:(urn:li:dataPlatform:hive,user.clicks,PROD)也可直接写urn。Schema 来源schema.file指向 click_event.avscAvro Schema含ip、url、locator.latitude等字段字段 id 需与 Avro 字段名对应。双层赋值structured_properties顶层作用于整个数据集fields[].structured_properties作用于单个字段schemaField实体。示例中deprecationDate同时出现在数据集级和三个字段级正是 README 里把该属性entity_types声明为dataset、dataFlow、dataJob之外还可用于schemaField的体现。多值属性projectNames声明为cardinality: MULTIPLE赋值时使用列表[Tracking, DataHub]单值属性如retentionTime直接赋标量。场景二Event Topic 描述与下游血缘- id: ClickEvent platform: events subtype: Topic description: | This is a sample event that is generated when a user clicks on a link. Do not use this event for any purpose other than testing. properties: project_name: Tracking namespace: org.acryl.tracking version: 1.0.0 retention: 30 structured_properties: io.acryl.dataManagement.certifier: urn:li:corpuser:john.doeexample.com schema: file: examples/structured_properties/click_event.avsc downstreams: - urn:li:dataset:(urn:li:dataPlatform:hive,user.clicks,PROD)该示例说明结构化属性不限于表Topic 实体同样可以挂载如certifier指向具体责任人 URNproperties提供无类型的普通键值元数据downstreams则声明了到 Hive 表的下游血缘。场景三跨平台同名表- id: user.clicks platform: snowflake structured_properties: io.acryl.dataManagement.replicationSLA: 90 schema: fields: - id: user_id structured_properties: io.acryl.dataManagement.deprecationDate: 2023-01-01 type: string同一个user.clicks名称在不同平台hive 与 snowflake是两个不同的数据集实体各自可以拥有不同的属性值——这印证了属性值挂在实体 URN 上的模型设计。从源码看 dataset 命令的落地方式datahub dataset upsert走的是 DataHub 通用数据集写入链路它会把dataset.yaml解析为数据集实体定义将顶层structured_properties写入数据集实体的StructuredPropertiesAspect将字段级属性写入对应schemaField实体的 Aspect并通过 MCP 逐条提交。你可以继续阅读 dataset.yaml 同级的dataproduct示例目录README 末尾提示See example in dataproduct了解更复杂的数据产品场景。五、Python SDK用代码驱动属性生命周期仓库为编程方式使用提供了三个可直接运行的示例脚本。1. 创建属性create_structured_property.py该脚本演示了通过 REST Emitter 创建三种典型属性from datahub.emitter.mcp import MetadataChangeProposalWrapper from datahub.emitter.rest_emitter import DatahubRestEmitter from datahub.metadata.schema_classes import ( PropertyValueClass, StructuredPropertyDefinitionClass, ) from datahub.metadata.urns import StructuredPropertyUrn rest_emitter DatahubRestEmitter(gms_serverhttp://localhost:8080) # 1) 开放文本属性单值、可挂 dataset 与 container text_property_urn StructuredPropertyUrn(io.acryl.openTextProperty) text_property_definition StructuredPropertyDefinitionClass( qualifiedNameio.acryl.openTextProperty, displayNameOpen Text Property, valueTypeurn:li:dataType:datahub.string, cardinalitySINGLE, entityTypes[ urn:li:entityType:datahub.dataset, urn:li:entityType:datahub.container, ], descriptionThis structured property allows a signle open ended response as a value, immutableFalse, ) rest_emitter.emit( MetadataChangeProposalWrapper( entityUrnstr(text_property_urn), aspecttext_property_definition ) )脚本共创建三个属性覆盖三类典型用法属性valueTypecardinality要点io.acryl.openTextPropertyurn:li:dataType:datahub.stringSINGLE开放自由文本io.acryl.dataManagement.dataStewardurn:li:dataType:datahub.urnMULTIPLEtypeQualifier{allowedTypes: [...]}限定只能填corpuser/corpGroupURN且immutableTrueio.acryl.dataManagement.replicationSLAurn:li:dataType:datahub.numberSINGLE通过allowedValues[PropertyValueClass(value30, ...), ...]声明 30/90/365 三个枚举值这里可以看到 YAML 字段与 SDK 参数的对应关系type↔valueType数据类型 URN如urn:li:dataType:datahub.number、entity_types↔entityTypes实体类型 URN、allowed_values↔allowedValuesPropertyValueClass列表、type_qualifier.allowed_types↔typeQualifier[allowedTypes]。启动前需确保本地 GMS 运行于http://localhost:8080。2. 更新属性update_structured_property.pyfrom datahub.emitter.rest_emitter import DataHubRestEmitter from datahub.metadata.urns import StructuredPropertyUrn from datahub.specific.structured_property import StructuredPropertyPatchBuilder property_urn StructuredPropertyUrn(io.acryl.dataManagement.dataSteward) with DataHubRestEmitter(gms_serverhttp://localhost:8080) as emitter: for patch_mcp in ( StructuredPropertyPatchBuilder(str(property_urn)) .set_display_name(test display name) .set_cardinality(MULTIPLE) .add_entity_type(urn:li:entityType:datahub.dataJob) .build() ): emitter.emit(patch_mcp)该示例演示了基于 Patch 的增量更新StructuredPropertyPatchBuilder以链式调用的方式修改展示名、基数并追加允许的实体类型build()产出若干 patch MCP通过 REST Emitter 逐个发送。相比 YAML 全量 upsertPatch 方式只改动指定字段适合精细化变更。脚本中还预留了 Kafka Emitter 的切换分支USE_REST_EMITTER开关 DatahubKafkaEmitter说明同一套 Patch 也可以走 Kafka 通道。3. 枚举属性list_structured_properties.pyfrom datahub.api.entities.structuredproperties.structuredproperties import ( StructuredProperties, ) from datahub.ingestion.graph.client import get_default_graph with get_default_graph() as graph: structuredproperties StructuredProperties.list(graph) for structuredproperty in structuredproperties: print(structuredproperty.dict())该脚本利用get_default_graph()建立默认连接复用 CLI 的认证配置调用StructuredProperties.list()枚举全部属性并逐条打印字典。其执行效果与 CLI 的datahub properties list --details等价适合在自动化脚本中获取属性清单做审计或差异对比。六、底层原理小结YAML → MCP → GMS 的完整链路把前面各部分串起来结构化属性的完整生命周期可以归纳为声明在 YAML 中声明属性id/urn、type、cardinality、entity_types、allowed_values、type_qualifier 等由StructuredPropertiespydantic 模型加载并做字段校验——类型必须是string/rich_text/number/date/urn之一大写自动转小写实体类型必须能转换为合法urn:li:entityType:datahub.*URNid 与 URN 中的 id 必须一致见 structuredproperties.py。写入generate_mcps()把每个属性转换为StructuredPropertyDefinitionClassAspect可选附StructuredPropertySettingsClass打包成 MCP 交给graph.emit_mcp()/ REST / Kafka Emitter 发送至 GMS见 structuredproperties.py。赋值datahub dataset upsert把structured_properties块中的键值对挂到目标实体数据集或schemaField的对应 Aspect 上值必须符合属性声明枚举、类型、URN 限定。消费属性定义与属性值均以 Aspect 形式存储可被properties get/list、StructuredProperties.list()以及 UI 检索与展示。七、实践建议与注意事项属性字典先行先集中维护一份structured_properties.yaml用datahub properties upsert -f一次性注册全部属性再编写dataset.yaml做赋值避免属性未定义就赋值导致校验失败。版本管理利用properties list --to-file导出当前属性字典纳入 Git 版本控制配合version字段标记 Schema 演进。类型与枚举是治理的第一道闸门type: urntype_qualifier.allowed_types可以把责任人、审批人等属性限定为合法用户/用户组allowed_values适合维护如保留期档位这类有限取值。多值与字段级属性MULTIPLE属性赋值用列表字段级属性fields[].structured_properties依赖 schema 定义务必保证字段 id 与 schema如 click_event.avsc中的字段一致。运行前提以上 CLI 与 SDK 示例均需要可用的 DataHub GMS默认http://localhost:8080与配置好的 CLI 认证Kafka 方式还需 broker 与 Schema Registry。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考