DataHub 数据集 Deprecation（废弃）状态管理实战指南：GraphQL、Curl 与 Python SDK 读写废弃元数据

DataHub 数据集 Deprecation废弃状态管理实战指南GraphQL、Curl 与 Python SDK 读写废弃元数据【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahubDeprecation废弃是 DataHub 中标识实体生命周期状态的核心元数据特性。本文基于官方 API 教程 deprecation.md结合仓库源码与可运行示例完整讲解如何通过 GraphQL、Curl 与 Python SDK 读取和更新数据集的废弃状态覆盖单实体更新、批量更新、权限校验与底层写入原理帮助数据平台团队主动向数据消费者传递该数据集即将下线或已不可用的信号。为什么要废弃Deprecate数据集在 DataHub 中Deprecation 特性用于表示一个实体的状态。对于数据集而言保持废弃状态的及时更新至关重要原因在于主动告知变更当数据集可用性、可靠性发生变化时及时打上废弃标记可以向用户与下游系统传递明确信号预防问题避免下游继续依赖即将下线或已被替换的数据资产防止消费到不可信数据建立信任确保用户始终使用高可信度的数据资产降低误用陈旧数据的风险。本指南的目标Goal Of This Guide是演示如何**读取Read与更新Update**一个数据集的废弃状态。前提准备Prerequisites执行本教程前需要先完成两件事部署 DataHub Quickstart具体步骤参考 DataHub Quickstart Guide摄入示例数据ingest sample data本指南将使用示例摄入产生的fct_users_created数据集。注意在更新废弃状态之前必须确保目标数据集已经存在于 DataHub 中。如果对不存在的实体执行变更操作操作会失败。本指南使用的实体来自一次示例摄入流程。认识 Deprecation 元数据模型在深入 API 调用前先理解 Deprecation 的数据结构。它在元数据模型中是一个标准的 Aspect定义于 Deprecation.pdlAspect { name: deprecation } record Deprecation { deprecated: boolean // 实体是否已废弃 decommissionTime: optional Time // 计划停用下线该实体的时间 note: string // 废弃计划的补充信息如 wiki、文档链接、工单等 actor: Urn // 修改该废弃内容的用户 URN replacement: optional Urn // 用于替换该实体的目标 URN }从 PDL 定义中可以确认几个关键实现细节deprecated字段被标记为SearchablefieldType: BOOLEAN并设置了filterNameOverride: Deprecated这意味着废弃状态可以直接作为搜索过滤器使用在 UI 中通过 Deprecated 过滤条件即可筛选出或排除已废弃的资产note是必填字段string因此在调用 API 时如果不提供 note服务端会写入空字符串decommissionTime与replacement都是可选字段分别表示计划停用时间和替代实体 URNactor由服务端根据当前登录用户自动填充无需调用方手动指定。读取 Deprecation 状态读取废弃状态无需任何权限要求查询类操作推荐从 UI 的 Data Quality 或实体详情页的 Deprecation 模块查看也可以通过 API 精确读取。方式一GraphQL 查询query { dataset(urn: urn:li:dataset:(urn:li:dataPlatform:hive,fct_users_created,PROD)) { deprecation { deprecated decommissionTime } } }如果操作成功将看到如下响应{ data: { dataset: { deprecation: { deprecated: false, decommissionTime: null } } }, extensions: {} }方式二Curl 调用使用 GraphQL 端点http://localhost:8080/api/graphql通过 POST 请求发送查询curl --location --request POST http://localhost:8080/api/graphql \ --header Authorization: Bearer my-access-token \ --header Content-Type: application/json \ --data-raw { query: { dataset(urn: \urn:li:dataset:(urn:li:dataPlatform:hive,fct_users_created,PROD)\) { deprecation { deprecated decommissionTime } } }, variables:{} }期望响应{ data: { dataset: { deprecation: { deprecated: false, decommissionTime: null } } }, extensions: {} }方式三Python SDK仓库提供了可直接运行的官方示例脚本 dataset_query_deprecation.py完整代码如下from typing import Optional, Tuple from datahub.metadata.schema_classes import DeprecationClass from datahub.sdk import DataHubClient, DatasetUrn def query_dataset_deprecation( client: DataHubClient, dataset_urn: DatasetUrn ) - Tuple[bool, Optional[str], Optional[int]]: Query the deprecation status of a dataset. Args: client: DataHub client to use for the query dataset_urn: URN of the dataset to check Returns: Tuple of (is_deprecated, deprecation_note, decommission_time_millis) dataset client.entities.get(dataset_urn) deprecation dataset._get_aspect(DeprecationClass) if deprecation and deprecation.deprecated: return (True, deprecation.note, deprecation.decommissionTime) return (False, None, None) def main() - None: client DataHubClient.from_env() dataset_urn DatasetUrn(platformhive, namefct_users_created, envPROD) is_deprecated, note, decommission_time query_dataset_deprecation( client, dataset_urn ) if is_deprecated: print(fDataset is deprecated: {note}) if decommission_time: print(fDecommission time: {decommission_time}) else: print(Dataset is not deprecated) if __name__ __main__: main()脚本要点DataHubClient.from_env()从环境变量DATAHUB_GMS_URL、DATAHUB_TOKEN等读取连接配置无需硬编码地址DatasetUrn(platformhive, namefct_users_created, envPROD)以结构化方式构造数据集 URN等价于urn:li:dataset:(urn:li:dataPlatform:hive,fct_users_created,PROD)通过client.entities.get()获取实体再用_get_aspect(DeprecationClass)取出 Deprecation aspect返回三元组(is_deprecated, deprecation_note, decommission_time_millis)其中decommissionTime是毫秒时间戳。更新 Deprecation 状态更新废弃状态属于写操作需要相应的权限见下文底层实现原理章节的权限校验说明。方式一GraphQL 单实体更新mutation updateDeprecation { updateDeprecation(input: { urn: urn:li:dataset:(urn:li:dataPlatform:hive,fct_users_created,PROD), deprecated: true }) }操作成功的响应如下{ data: { updateDeprecation: true }, extensions: {} }方式二GraphQL 批量更新除了单个实体还可以通过batchUpdateDeprecation一次性更新多个实体或子资源的废弃状态mutation batchUpdateDeprecation { batchUpdateDeprecation( input: { deprecated: true, resources: [ { resourceUrn:urn:li:dataset:(urn:li:dataPlatform:hdfs,SampleHdfsDataset,PROD)} , { resourceUrn:urn:li:dataset:(urn:li:dataPlatform:hive,fct_users_created,PROD)} ,] } ) }UpdateDeprecationInput 完整字段说明根据 GraphQL Schema 定义 entity.graphqlupdateDeprecation的输入结构如下字段类型必填说明urnString是要设置废弃状态的实体 URNdeprecatedBoolean是是否标记为废弃subResourceTypeSubResourceType否要设置废弃状态的子资源类型如 SchemaFieldsubResourceString否要设置废弃状态的子资源标识如字段路径decommissionTimeLong否计划停用该实体的时间毫秒时间戳noteString否关于实体废弃计划的补充信息replacementString否用于替换该实体的目标 URN其中subResourceType/subResource支持将废弃状态精确打到**字段级schemaField**子资源上replacement可以指向一个替代数据集在 UI 中会展示该资产已被 XX 替换的指引。方式三Curl 调用curl --location --request POST http://localhost:8080/api/graphql \ --header Authorization: Bearer my-access-token \ --header Content-Type: application/json \ --data-raw { query: mutation updateDeprecation { updateDeprecation(input: { deprecated: true, urn: \urn:li:dataset:(urn:li:dataPlatform:hive,fct_users_created,PROD)\ }) }, variables:{}}期望响应{ data: { updateDeprecation: true }, extensions: {} }方式四Python SDK 更新仓库中的 mlmodel_group_deprecate.py 演示了使用 Python SDK 写入 Deprecation aspect 的通用模式示例针对 ML 模型组模式可无缝迁移到数据集from datetime import datetime import datahub.metadata.schema_classes as models from datahub.sdk import DataHubClient, MlModelGroupUrn client DataHubClient.from_env() group_urn MlModelGroupUrn( platformmlflow, namelegacy-recommendation-models, envPROD, ) mlmodel_group client.entities.get(group_urn) deprecation_aspect models.DeprecationClass( deprecatedTrue, noteThis model group has been replaced by the new transformer-based recommendation models, decommissionTimeint(datetime.now().timestamp() * 1000), actorurn:li:corpuser:datahub, ) mlmodel_group._set_aspect(deprecation_aspect) client.entities.update(mlmodel_group) print(fDeprecated ML model group: {group_urn})迁移到数据集时的对应写法为from datetime import datetime import datahub.metadata.schema_classes as models from datahub.sdk import DataHubClient, DatasetUrn client DataHubClient.from_env() dataset_urn DatasetUrn(platformhive, namefct_users_created, envPROD) dataset client.entities.get(dataset_urn) deprecation_aspect models.DeprecationClass( deprecatedTrue, noteThis dataset is decommissioned, please use the replacement, decommissionTimeint(datetime.now().timestamp() * 1000), actorurn:li:corpuser:datahub, ) dataset._set_aspect(deprecation_aspect) client.entities.update(dataset) print(fDeprecated dataset: {dataset_urn})注意decommissionTime必须是毫秒时间戳datetime.now().timestamp() * 1000与 GraphQL 输入的Long类型一致。更新后的预期结果Expected Outcomes执行上述任意一种更新操作后回到 DataHub UI 查看数据集fct_users_created可以看到它已被标记为Deprecated实体卡片与详情页会展示废弃标识、废弃说明note以及计划停用时间等元数据信息。同时由于deprecated字段可搜索见 Deprecation.pdl 中的Searchable注解你还可以在搜索界面通过 Deprecated 过滤条件快速筛选出全部已废弃资产便于统一治理。底层实现原理更新一次废弃状态发生了什么1. GraphQL Schema 与 Resolver 注册updateDeprecation与batchUpdateDeprecation两个 Mutation 定义在 entity.graphql Sets the Deprecation status for a Metadata Entity. Requires the Edit Deprecation status privilege for an entity. updateDeprecation( Input required to set deprecation for an Entity. input: UpdateDeprecationInput! ): Boolean Updates the deprecation status for a batch of assets. batchUpdateDeprecation(input: BatchUpdateDeprecationInput!): Boolean对应实现类为 UpdateDeprecationResolver.java 与 BatchUpdateDeprecationResolver.java两者在 GmsGraphQLEngine.java 中完成绑定。2. 权限校验Edit Deprecation 特权从 UpdateDeprecationResolver.java 可以看到更新废弃状态要求用户具备以下任一条件拥有全部权限组ALL_PRIVILEGES_GROUP或拥有EDIT_ENTITY_DEPRECATION_PRIVILEGE即 Edit Deprecation status 特权定义于PoliciesConfig否则将抛出AuthorizationException提示请联系 DataHub 管理员。批量更新场景的权限校验逻辑一致见 DeprecationUtils.java。3. 实体存在性校验在写入前服务端会调用validateUpdateDeprecationInput校验目标实体必须存在if (!entityService.exists(opContext, entityUrn, true)) { throw new IllegalArgumentException( String.format( Failed to update deprecation for Entity %s. Entity does not exist., entityUrn)); }这正是文档前提中如果实体不存在操作将失败的底层来源。4. 组装 Deprecation Aspect 并写入更新逻辑UpdateDeprecationResolver.java的核心行为setDeprecated(input.getDeprecated())写入废弃标记setDecommissionTime(input.getDecommissionTime(), SetMode.REMOVE_IF_NULL)decommissionTime为 null 时删除该字段note为 null 时默认写入空字符串因为 GMS 侧该字段必填replacement非 null 时解析为 Urn 写入否则移除actor由服务端从当前请求上下文中自动获取并写入。最后通过MutationUtils.buildMetadataChangeProposalWithUrn(entityUrn, DEPRECATION_ASPECT_NAME, deprecation)构造MetadataChangeProposalMCP经_entityClient.ingestProposal(...)提交给 GMS触发 MAE/MCE 异步消费最终同步到 Elasticsearch 索引使 UI 搜索与过滤立即生效。5. 批量更新与字段级子资源batchUpdateDeprecation的流程BatchUpdateDeprecationResolver.java先通过LabelUtils.existingResourceUrns预校验所有资源的 URN 存在性对每个资源执行权限校验调用 DeprecationUtils.java 中的updateDeprecationForResources为每个资源构造独立的 MCP 后一次性批量摄入。值得关注的是批量接口支持subResource当传入subResource如某个 schema 字段路径时会通过SchemaFieldUtils.generateSchemaFieldUrn(...)将目标转换为urn:li:schemaField:(...)形式的字段级 URN从而实现对数据集内单个字段的废弃标记。6. 测试验证该功能有完善的单元测试支撑见 UpdateDeprecationResolverTest.java 与 BatchUpdateDeprecationResolverTest.java。测试覆盖了无既有 Deprecation 时的成功更新testGetSuccessNoExistingDeprecation携带replacement含 schemaField 替换的更新场景通过 Mock 的EntityClient.batchGetV2验证读取旧 aspect、构造新 MCP 的完整调用链实体不存在 / 未授权等失败路径的异常断言。常见问题与最佳实践问题原因与解决更新时报 Entity does not exist目标 URN 尚未摄入 DataHub请先执行对应的 ingestion recipe 摄入该数据集更新时报 Unauthorized to perform this action当前访问令牌对应的用户缺少EDIT_ENTITY_DEPRECATION_PRIVILEGE特权需联系管理员在 Policies 中授权未传note是否会报错不会。服务端会默认写入空字符串GMS 要求该字段非 nulldecommissionTime传什么格式毫秒级时间戳Long如int(datetime.now().timestamp() * 1000)如何撤销废弃标记将deprecated设为false再次调用updateDeprecation即可同时可清空decommissionTime与replacement如何让下游尽早感知结合note填写 wiki / 工单链接并在replacement中指定替代数据集配合搜索过滤 Deprecated 定期治理存量废弃资产总结通过本文你已经掌握 DataHub 数据集 Deprecation 元数据的完整读写链路读取GraphQL Query / Curl / Python SDK 三种方式均可查询deprecated、decommissionTime等状态更新updateDeprecation单实体更新batchUpdateDeprecation批量更新含字段级子资源原理底层由UpdateDeprecationResolver完成权限校验、存在性校验、Aspect 组装与 MCP 摄入数据最终落库并同步到搜索索引实战结合 dataset_query_deprecation.py 与 mlmodel_group_deprecate.py 两个官方示例可将废弃管理无缝集成进自动化治理脚本。正确、及时地维护数据集的废弃状态是保障数据平台高可信度数据资产承诺的重要一环——它让废弃决策透明化让下游消费者永远只使用可信的数据。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考