DataHub Structured Property 创建与配置实战指南从 UI 定义到资产与字段级元数据落地【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub本指南以 DataHub 官方特性指南 create-a-property.md 为核心主体系统讲解如何通过 DataHub UI 创建Create、配置Configure并应用Apply结构化属性Structured Property覆盖属性定义、显示偏好设置、资产级与列级赋值、搜索过滤以及常见故障排查。读完本文你将能够结合仓库中的配置源码与 CLI/GraphQL/OpenAPI 教程独立完成一套可落地的自定义元数据体系搭建。什么是 Structured Property为什么要用它DataHub 的Structured Properties结构化属性允许你向任意实体类型Entity附加自定义的、经过校验的元数据字段从而让数据发现与治理能够基于你组织特有的属性展开。它在模型上的核心能力详见 overview.md包括强类型字段Typed Fields属性显式声明类型例如 Date、Number、URN 或 Text。允许值约束Allowed Values将取值限制为特定格式或预定义的可接受列表保证跨资产的输入一致性。定向应用Targeted Application属性可以只针对特定资产类型如 Dataset、Column、Dashboard生效与应用场景对齐。Structured Property 可以挂载到以下两类对象上数据资产Data AssetsDataset、Column字段、Task、Pipeline、Chart、Dashboard 等DataHub 实体EntitiesDomain、Glossary Term 与 Glossary Group、Data Product 等。本指南聚焦UI 操作路径如需通过代码/API 方式完成同样的工作可参考 Structured Properties API 教程本文末尾也会给出核心命令速览。前提条件需要哪些权限要在 UI 中创建、编辑或删除 Structured Property你必须拥有两个平台级权限Platform PrivilegesView Structured Properties查看结构化属性Manage Structured Properties管理增删改结构化属性。而要将一个已存在的 Structured Property 添加到某个资产、修改其值或将其从资产上移除你还需要拥有元数据权限Metadata Privilege中的 Edit Properties。从权限设计的角度可以理解为前者管元数据模型定义后者管实例数据写入两者缺一不可。第一步在 UI 中定义一个新的 Structured Property从导航栏进入Govern Structured Properties点击 Create开始定义属性。进入创建页面后需要依次填写四类信息1. 名称与描述Name and Description清晰描述该属性的用途与含义让使用者理解它的角色和上下文。一个语义明确的描述会让后续的数据消费者包括检索系统更容易理解该属性的业务含义。2. 属性类型Property Type根据你要采集的元数据类型选择合适的类型可选类型包括类型说明Text任意字符串Number数值Date日期DataHub Entity关联另一个 DataHub 实体URNsRich Text富文本此外选择任意类型的List 选项如 List of Text可以让该属性接受多个值对应元数据模型中的cardinality: MULTIPLE。注意值大小限制每个Text、Rich Text、Date 或 DataHub Entity类型的值默认最多32,766 UTF-8 字节对应 Elasticsearch / OpenSearch 的 keyword 上限可通过STRUCTURED_PROPERTIES_KEYWORD_MAX_LENGTH配置调整。超长值在写入时会被拒绝除非设置STRUCTURED_PROPERTIES_DROP_OVERSIZED_KEYWORD_VALUES_FROM_INDEXtrue——此时该值仍会存入主存储primary storage但不会进入搜索索引。详见 Limitations。3. 允许值Allowed Values可选对于Text、Number 和 DataHub Entity类型可以定义一个允许值集合确保不同资产上的输入保持一致。⚠️ 重要限制一旦保存了 Structured Property你不能再编辑或删除已定义的允许值但可以继续追加新的允许值。因此创建时请谨慎规划取值集合。4. 应用于Applies To指定该 Structured Property 可以关联哪些 DataHub 资产类型例如 Dataset、Dashboard、Pipeline 等确保属性只出现在真正相关的资产上保持元数据的精准性。实战示例Lifecycle Stage假设你的组织希望在开发周期中标准化数据资产Dataset、Task、Pipeline 等的分类方式。可以创建一个名为Lifecycle Stage的 Structured Property并预设允许值Draft、Review、Prod从而保证一致性与可追溯性。后续所有操作示例都将围绕该属性展开。第二步设置 Structured Property 的显示偏好创建属性时可以自定义它在 DataHub 界面中的呈现方式。默认情况下Structured Property 会显示在资产的Properties选项卡中但你可以通过以下选项进行条件化配置Hide Property隐藏属性当属性包含敏感元数据、不希望普通用户在 UI 中看到时启用。启用后只有具备相应权限的用户才能查看或操作该属性值。Customize Visibility自定义可见性决定属性在 DataHub UI 中出现的位置Asset Badge资产徽章将属性值以徽章形式展示在资产上突出关键元数据Asset Sidebar资产侧边栏在浏览资产时于侧边栏快速展示。Show in Search Filters显示在搜索过滤器中启用后用户可按该属性的值过滤资产提升可发现性方便按特定属性或分类检索资产。Show in Columns Table显示在列字段表格中启用后属性值会出现在 Dataset Schema 视图的 Columns Table 中特别适合采集字段级自定义元数据与 Schema 详情并列展示。对于Lifecycle Stage示例如果希望在数据发现过程中快速查看生命周期状态可以同时开启Show in Search Filters、Asset Badge和Asset Sidebar。提示显示偏好的底层配置在仓库中对应StructuredPropertySettings相关 aspectUI 层实现可参考 datahub-web-react 下的输入组件如MultiSelectInput.tsx、SingleSelectInput.tsx、StringInput.tsx、NumberInput.tsx以及资产头部徽章组件 StructuredPropertyBadge.tsx。第三步将 Structured Property 添加到资产Asset属性定义完成后即可添加到所指定的资产类型上。添加属性到资产进入某个资产的Properties选项卡点击按钮在下拉列表中选择可用的 Structured Property。例如pet_profilesDataset 现在可以看到Lifecycle Stage选项。继续以Lifecycle Stage为例将pet_profiles标记为Prod点击Save保存后该属性值会出现在资产页面的以下三个区域Properties Tab属性选项卡Asset Badge资产徽章Asset Sidebar资产侧边栏提示DataHub Compliance Forms合规表单 可以方便地批量更新多个资产上的属性值适合大规模治理场景。编辑或移除资产上的属性属性被添加到资产后用户可以通过More菜单修改其值或将该属性整体从资产上移除。对应后端能力为upsertStructuredProperties/removeStructuredProperties两个 GraphQL mutation详见 structured-properties.md其中移除操作需要传入资产 URN 与待移除的属性 URN 列表。按属性值搜索资产对于开启了Show in Search Filters的 Structured Property用户可以在搜索界面的More下拉菜单中找到该属性并基于允许值过滤搜索结果。例如在Lifecycle Stage下选择Prod即可快速缩小结果范围同时Prod值会醒目地展示在pet_profiles的资产徽章上。第四步将 Structured Property 添加到列Column / 字段Structured Property 同样可以应用到列字段级别为单个数据集字段提供更深层的业务上下文。下面以Business Label为例帮助业务用户理解数据集列与常用术语、缩写或关键业务概念的对应关系。定义 Business Label 属性按以下步骤定义与配置该属性属性详情Property DetailsNameBusiness LabelDescription描述其用途例如A user-friendly name for a dataset column, helping business users understand its meaning.Property Type选择Text允许输入任意合法字符串Applies To设置为仅应用于Columns字段显示偏好Display Preferences默认情况下列级 Structured Property 会自动启用于 DataHub 内所有 Dataset 的所有列并通过Column Sidebar列侧边栏访问可选地启用Show in Table Columns让Business Label在 Dataset Schema 的 Columns Table 中可见。⚠️ 注意事项列侧边栏虽然提供了便捷的属性访问入口但过多的 Structured Property 会挤占侧边栏空间、造成视觉混乱。请限制侧边栏中展示的属性数量保持界面清晰易用。配置完成后Business Label会自动添加到 DataHub 中数据集资产的所有列上。例如赋值后它会出现在pet_profiles资产页面的两个关键区域Columns Table列表格在 Dataset Schema 的 Columns Table 中直接显示该属性及填充值方便查看字段级元数据Column Sidebar列侧边栏列级属性也会出现在所选列的侧边栏中。通过应用Business Label这样的列级 Structured Property可以在保持界面友好的同时增强数据可发现性为业务用户提供有价值的洞察。从列侧边栏更新 Business Label在 UI 中选中某一列时Business Label会显示在该列的侧边栏中。具备相应权限的用户可以直接在此界面查看或更新属性值。从元数据模型看列级属性实际上是通过schemaField实体类型urn:li:entityType:datahub.schemaField挂载到 Dataset 的 schema field 上——这一点在 structured-properties.md 的 CLI 示例datasets.yaml中fields[].structured_properties字段中可以直接印证列级赋值使用io.acryl.dataManagement.deprecationDate: 2023-01-01这样的键值对写在 schema field 之下。补充用 CLI / GraphQL / OpenAPI 以编程方式创建属性UI 之外仓库还提供了完整的编程路径完整教程见 Structured Properties API 教程可复用的示例文件位于 metadata-ingestion/examples/structured_properties。CLI 方式datahub properties命令族先准备一个 YAML 文件描述属性定义例如创建一个io.acryl.privacy.retentionTime属性- id: io.acryl.privacy.retentionTime qualified_name: io.acryl.privacy.retentionTime type: number cardinality: MULTIPLE display_name: Retention Time entity_types: - 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然后执行 upsert 创建对应仓库示例 README.md 中的用法datahub properties upsert -f {properties_yaml}成功后会输出Created structured property urn:li:structuredProperty:...。其他常用命令# 列出全部属性完整详情 datahub properties list # 只列出 URN datahub properties list --no-details # 将全部属性定义导出为可复用的 YAML可与 upsert 配合做备份/迁移 datahub properties list --to-file structured_properties.yaml # 读取单个属性 datahub properties get --urn {urn}给 Dataset 赋值时使用 dataset YAML字段级与实体级皆可- id: user_clicks_snowflake platform: snowflake schema: fields: - id: user_id structured_properties: io.acryl.dataManagement.deprecationDate: 2023-01-01 structured_properties: io.acryl.dataManagement.replicationSLA: 90datahub dataset upsert -f {dataset_yaml}GraphQL 方式使用createStructuredPropertymutationmutation createStructuredProperty { createStructuredProperty( input: { id: retentionTime qualifiedName: retentionTime displayName: Retention Time description: Retention Time is used to figure out how long to retain records in a dataset valueType: urn:li:dataType:datahub.number allowedValues: [ { numberValue: 30, description: 30 days, usually reserved for datasets that are ephemeral and contain pii } { numberValue: 90, description: Use this for datasets that drive monthly reporting but contain pii } { numberValue: 365, description: Use this for non-sensitive data that can be retained for longer } ] cardinality: SINGLE entityTypes: [ urn:li:entityType:datahub.dataset urn:li:entityType:datahub.dataFlow ] } ) { urn } }OpenAPI v3 方式curl -X POST -v \ http://localhost:8080/openapi/v3/entity/structuredProperty/urn%3Ali%3AstructuredProperty%3Aio.acryl.privacy.retentionTime/propertyDefinition \ -H accept: application/json \ -H Content-Type: application/json \ -d { value: { qualifiedName: io.acryl.privacy.retentionTime, valueType: urn:li:dataType:datahub.number, description: Retention Time is used to figure out how long to retain records in a dataset, displayName: Retention Time, cardinality: MULTIPLE, entityTypes: [ urn:li:entityType:datahub.dataset, urn:li:entityType:datahub.dataFlow ], allowedValues: [ { value: { double: 30 }, description: 30 days, usually reserved for datasets that are ephemeral and contain pii }, { value: { double: 60 }, description: Use this for datasets that drive monthly reporting but contain pii }, { value: { double: 365 }, description: Use this for non-sensitive data that can be retained for longer } ] } } | jq注意 OpenAPI v2 的实体 API 已标记为 deprecated新项目应优先使用/openapi/v3/entity路径。深入原理值大小限制的配置与实现前文多次提到的 32,766 字节限制其默认值与开关在仓库源码中有明确的实现依据配置类StructuredPropertiesConfiguration.java 定义了enabled、writeEnabled、systemUpdateEnabled、typeMismatchReindexEnabled、dropMissingPropertyValuesWithWarning、dropOversizedKeywordValuesFromIndex、keywordMaxLength等字段配置文件application.yaml 给出了对应的环境变量与默认值环境变量默认值作用ENABLE_STRUCTURED_PROPERTIES_HOOKtrue是否应用 structured property 映射ENABLE_STRUCTURED_PROPERTIES_WRITEtrue是否允许写入属性值ENABLE_STRUCTURED_PROPERTIES_SYSTEM_UPDATEfalse是否在 system update job 中应用映射ENABLE_STRUCTURED_PROPERTIES_TYPE_MISMATCH_REINDEXtrue索引字段类型与定义目标不一致时是否重索引需同时开启systemUpdateEnabledSTRUCTURED_PROPERTIES_DROP_MISSING_PROPERTY_VALUES_WITH_WARNINGtrue对已删除/缺失定义的赋值以 WARN 丢弃若无有效赋值则写入失败STRUCTURED_PROPERTIES_DROP_OVERSIZED_KEYWORD_VALUES_FROM_INDEXfalse为 true 时超长字符串值仍写入主存储但不出现在搜索文档为 false 时由StructuredPropertiesValidator拒绝写入HTTP 422STRUCTURED_PROPERTIES_KEYWORD_MAX_LENGTH32766字符串类属性值的 UTF-8 字节阈值同时用于 keyword 映射的ignore_above推导出的字符上限约为keywordMaxLength / 4由此可以得出几条实操结论默认情况下超长值会被校验器直接拒绝根本不会进入搜索索引开启STRUCTURED_PROPERTIES_DROP_OVERSIZED_KEYWORD_VALUES_FROM_INDEXtrue后超长值仍可通过 GraphQL / OpenAPI 读到主存储保留但无法被搜索与过滤低于字节阈值但超过ignore_above字符上限的值可能仍写入文档_source但同样不可搜索Number 类型的值不受此 keyword 限制。因此需要可搜索/可过滤的属性请使用较短的值大段的自由格式内容长 Markdown、HTML 或文档应改存为资产文档Asset documentation而不是放进属性值。FAQ 与故障排查为什么我无法修改 Structured Property 的定义属性定义一经保存只有部分内容可修改可以修改标题Title与描述Description追加新的允许值增加新的受支持资产类型更新显示偏好不能修改属性的类型Type已有的允许值及其定义为什么无法把属性配置为 Asset Badge只有Text和Number类型且带有允许值的属性才能配置为 Asset Badge同一资产只能有一个Structured Property 显示为 Badge。为什么无法按某个属性过滤搜索结果确认该属性已开启显示在搜索过滤器中Show in Search Filters确认搜索结果的资产确实关联了该属性的值——属性若没有关联任何资产过滤条件自然不产生结果。可以尝试更换搜索词或放宽其他过滤条件。为什么无法向资产添加属性确认你拥有Edit Properties元数据权限确认该属性已创建并且其应用于Applies To包含了你要修改的资产类型。为什么我的 Text / Rich Text 属性值被拒绝每个字符串类属性值Text、Rich Text、Date、DataHub Entity默认最多32,766 UTF-8 字节STRUCTURED_PROPERTIES_KEYWORD_MAX_LENGTH因为其需要作为 Elasticsearch / OpenSearch keyword 被索引超过该限制的写入会被拒绝除非启用STRUCTURED_PROPERTIES_DROP_OVERSIZED_KEYWORD_VALUES_FROM_INDEX此时值会被存储但不可搜索解决方案缩短值长度或将大段内容作为资产文档Asset documentation存储。相关文档导航Structured Properties 特性总览概念、能力与 Limitations 完整说明Structured Properties API 教程CLI / GraphQL / OpenAPI 全量操作示例创建、列出、读取、删除、赋值、PATCH、搜索聚合DataHub Compliance Forms批量更新多个资产属性值的治理表单方案可复用示例metadata-ingestion/examples/structured_properties含structured_properties.yaml、dataset.yaml、create_structured_property.py、list_structured_properties.py、update_structured_property.py配置源码StructuredPropertiesConfiguration.java 与 application.yaml【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考