DataHub GraphQL API 快速上手：查询、搜索、变更与错误处理实战指南

DataHub GraphQL API 快速上手查询、搜索、变更与错误处理实战指南【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub本文基于 DataHub 开源仓库中的 getting-started.md 编写围绕 DataHub 提供的 GraphQL API 展开你将掌握如何通过/api/graphql端点读取实体Query、执行全文搜索Search、修改实体元数据Mutation以及如何正确解析 GraphQL 错误响应。文章结合仓库内datahub-graphql-core模块的源码实现如SearchResolver、DataHubGraphQLErrorCode等进行纵深讲解让你不仅会用更理解其底层机制。DataHub 将组织的元数据统一建模为一张Metadata Graph元数据图其中的实体Dataset、Dashboard、DataFlow 等与关系Ownership、Lineage、Tagging 等均可通过其 GraphQL API 以强类型、文档化、层级化的方式编程访问。GraphQL API 的完整能力概览可先参阅 DataHub GraphQL API 总览而端点的部署与连接方式GraphiQL、CURL、Postman、认证见 How To Set Up GraphQL。本文聚焦于如何使用该 API 完成三类核心操作读、搜、写以及错误处理。读取实体QueriesDataHub 为元数据图中的实体提供了一系列graphql查询字段Query。最典型的是按 URN 直接读取某个实体。按 URN 查询实体以下查询根据数据集Dataset的 URN 获取其urn与properties.name{ dataset(urn: urn:li:dataset:(urn:li:dataPlatform:kafka,SampleKafkaDataset,PROD)) { urn properties { name } } }这是 DataHub GraphQL API 最基础的用法以 URN 为键、以 GraphQL 选择集Selection Set为投影只取你关心的字段。从源码角度看dataset字段的解析由 DatasetType.java 承载其中定义了读取一个 Dataset 时需要解析的 aspect 集合ASPECTS_TO_RESOLVE包括datasetProperties、ownership、globalTags、institutionalMemory、upstreamLineage等核心元数据片段。这意味着一次dataset查询底层会聚合多个 aspect 后再映射为 GraphQL 的Dataset对象返回避免了客户端多次往返。除 URN 与 properties 之外你还可以在同一查询中获取实体的**所有者Owners、标签Tags、域Domain、术语Glossary Terms**等元数据。相关的专题教程如下查询 Dataset 的所有者查询 Dataset 的标签查询 Dataset 的域查询 Dataset 的术语查询 Dataset 的弃用状态查询某个 DataFlow 下的所有 DataJob按类型全文搜索Search当你不清楚目标实体的 URN或需要按关键词检索时应使用search(input: SearchInput!)查询字段对特定实体类型执行全文搜索{ search(input: { type: DATASET, query: my sql dataset, start: 0, count: 10 }) { start count total searchResults { entity { urn type ...on Dataset { name } } } } }对上述查询的各字段含义说明如下search表示执行一次搜索的查询字段input搜索条件包括被搜索的实体类型type、搜索词query、结果起始下标start与返回条数countquery搜索词可以是简单字符串也可以是带通配符的复杂模式见下表searchResults.entity命中的实体可使用内联片段...on Dataset按类型取字段total命中的总条数用于分页展示。query支持的搜索模式基于 Elasticsearch 索引的匹配语义模式含义*匹配所有实体*[string]匹配所有以指定 string 开头的 aspect 命名的实体[string]*匹配所有以指定 string 结尾的 aspect 命名的实体*[string]*匹配所有包含指定 string 的 aspect 命名的实体[string]匹配所有包含指定 string 的实体注意分页上限默认情况下Elasticsearch 通过 search API 最多只能分页遍历10,000条实体。如果需要翻页更多数据可以调整 Elasticsearch 的index.max_result_window配置项直接使用 scroll API 从索引中读取。从源码实现看search字段由 SearchResolver.java 解析它定义了若干默认行为与文档示例中的start: 0, count: 10一一对应默认start 0、count 10源码常量DEFAULT_START、DEFAULT_COUNT默认开启fulltext true、skipCache false、skipAggregates false、skipHighlighting false会对查询词中的正斜杠/做转义ResolverUtils.escapeForwardSlash因为它是 Elasticsearch 中的保留字符底层通过EntityClient.search(...)调用元数据服务将结果经UrnSearchResultsMapper映射为 GraphQL 的SearchResults。修改实体Mutations变更前的两个重要提醒:::note权限校验凡是修改实体元数据的 Mutation都受 DataHub Access Policies 约束。DataHub 服务端会检查发起请求的 actor 是否被授权执行该操作未授权将返回 403 类错误。 ::::::note适用场景DataHub 的 GraphQL Mutation主要为 UI 交互设计在程序化使用场景中应尽量避免。Mutation 虽然已实现且可通过 API 调用但不适用于高吞吐或批量操作例如数据集成工作流。对于程序化元数据管理、数据摄取与批量操作请改用Python SDK随acryl-datahub包发布其中包含了常见用例的完整示例。详细用法见 Python SDK 文档。 :::更新已有实体更新一个已存在的元数据实体使用updateentityName(urn: String!, input: EntityUpdateInput!)形式的 Mutation。例如更新一个 Dashboard 实体的描述mutation updateDashboard { updateDashboard( urn: urn:li:dashboard:(looker,baz), input: { editableProperties: { description: My new description } } ) { urn } }该 Mutation 携带两个核心参数urn目标实体的唯一标识String!必填inputEntityUpdateInput类型的变更载荷本例中通过editableProperties.description更新用户可编辑属性editable aspect中的描述文本。更多的写操作示例请参考以下专题添加标签 / 移除标签添加术语 / 移除术语添加域 / 移除域添加所有者 / 移除所有者更新弃用状态编辑 Dataset 的描述文档编辑列的描述文档软删除如果你不确定某个操作该走 GraphQL 还是其他接口可参考 DataHub API 对比与选型指南它按使用场景给出了导航。处理错误GraphQL 与 REST 的一个显著差异在于请求出错时HTTP 状态码并不一定是非 200。错误会出现在响应体的顶层errors字段中。这种设计允许服务端在返回部分数据的同时携带错误信息因此客户端在每次请求后都应同时检查data与errors两个字段而不只是依赖 HTTP 状态码。错误响应的结构捕获 GraphQL 错误只需检查响应中的errors字段。每个错误条目包含message、locations、path以及携带标准错误码的extensions{ errors: [ { message: Failed to change ownership for resource urn:li:dataFlow:(airflow,dag_abc,PROD). Expected a corp user urn., locations: [ { line: 1, column: 22 } ], path: [addOwners], extensions: { code: 400, type: BAD_REQUEST, classification: DataFetchingException } } ] }各字段的作用message人类可读的错误描述可能附带根因root cause信息locations出错位置在请求中的行列号便于定位问题查询path出错字段在查询中的路径如[addOwners]表示错误发生在addOwners这一级extensions扩展信息其中code为标准错误码type为错误类型名classification为 GraphQL 层的异常分类。官方支持的错误码CodeTypeDescription400BAD_REQUEST查询或变更query/mutation格式错误malformed。403UNAUTHORIZED当前 actor 未被授权执行所请求的操作。404NOT_FOUND资源不存在。500SERVER_ERROR服务端内部错误。请检查服务端日志或联系 DataHub 管理员。错误码的源码级实现错误码并非散落在各业务代码中而是集中定义在 DataHubGraphQLErrorCode.java。从该枚举可以看到仓库实现比文档表格还多了两个错误码CONFLICT(409)操作冲突SERVICE_UNAVAILABLE(503)瞬时故障transient failure客户端可以重试与 HTTP 503 对齐注释中明确说明。典型触发场景是数据库事务冲突。也就是说文档中列出的 400/403/404/500 是官方保证的稳定契约而 409/503 在源码中同样存在遇到时可按其语义处理503 可重试。错误码的映射规则实现在 DataHubDataFetcherExceptionHandler.java 中。它按异常类型优先级DataHubGraphQLException→ValidationException→IllegalArgumentException→DatabaseTransactionConflictException→IllegalStateException→RuntimeException→ 兜底沿异常链cause walk匹配然后映射到对应的DataHubGraphQLErrorCodeDataHubGraphQLException携带自身定义的错误码ValidationException/IllegalArgumentException→BAD_REQUEST400DatabaseTransactionConflictException→SERVICE_UNAVAILABLE503提示可重试IllegalStateException/RuntimeException/ 其他未知异常→SERVER_ERROR500兜底消息为An unknown error occurred.。此外该处理器在提取错误信息时会沿异常链收集所有 cause 的消息并拼接为Root cause: ...形式方便定位真正的根因。这也是为什么实际返回的message往往比业务异常原文更详尽。实战要点小结连接端点GraphQL 端点固定为/api/graphql仅支持 POST浏览器调试器 GraphiQL 位于/api/graphiql。首次使用前请先完成 DataHub Quickstart 部署 并摄入一些元数据详见 GraphQL 环境搭建指南。认证方式携带Authorization: Bearer access-token请求头Personal Access Token 会携带用户权限。令牌的创建与管理见 Access Token 管理 与 Personal Access Token 文档。读操作用 Query写操作用 Mutation且写操作必须通过 Access Policies 授权。批量与高吞吐场景请优先使用 Python SDKacryl-datahubGraphQL Mutation 面向 UI 场景设计不承担数据集成工作负载。错误判断务必同时检查data与errors并依据extensions.code处理400 修正请求、403 检查权限、404 核对 URN、500 查服务端日志、503源码级可安全重试。至此你已经掌握了 DataHub GraphQL API 的读、搜、写与错误处理全流程。更细粒度的 Schema 参考Queries / Mutations / Objects / Input Objects / Enums 等可继续翻阅 GraphQL Schema Reference 及 GraphQL 最佳实践。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考