MCP Toolbox 数据质量守护dataplex-check-data-quality 工具实战指南【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本文围绕 MCP Toolbox面向数据库的开源 MCP Server中的 Knowledge Catalog原 Dataplex集成深入讲解dataplex-check-data-quality工具它如何针对指定 BigQuery 表创建 Dataplex Data Quality 扫描模板并触发异步执行如何用specJSON定义非空校验、取值范围、自定义 SQL 断言等质量规则以及如何配合dataplex-get-operation、dataplex-get-run-status、dataplex-get-data-quality-results完成一次完整的数据质量巡检闭环。读完本文你将掌握该工具的完整配置方法、参数语义、异步编排时序并能结合仓库源码理解其底层实现原理。工具概览一次调用触发一轮数据质量扫描dataplex-check-data-quality是 Knowledge CatalogDataplex集成中的核心工具之一其作用是创建一个新的 Dataplex Data Quality 扫描模板并立即触发首次异步执行用于针对表数据评估自定义的质量规则例如非空non-null检查指定列是否存在 NULL 值完整性 / COMPLETENESS取值范围value range限制数值列的最小值、最大值自定义 SQL 断言custom SQL assertions用 SQL 表达式定义更复杂的业务约束。从源码看该工具在仓库中的实现位于 dataplexcheckdataquality.go其注册类型名为dataplex-check-data-quality见第 30 行const resourceType string dataplex-check-data-quality并在init()中通过tools.Register完成注册第 32-36 行。需要特别强调的是扫描模板的创建是异步的。工具不会立即返回质量评估结果而是返回一个 Long-Running OperationLRO名称。你必须严格按下面描述的编排顺序轮询才能最终拿到质量分数。异步编排完整的数据质量巡检工作流由于整个流程跨越“模板创建”和“后台执行”两个异步阶段MCP Toolbox 用多个工具组合出完整工作流。仓库中的预置配置 dataplex.yaml 对 Agent 给出了明确的 5 步编排要求这也是本文推荐的标准流程捕获 LRO 名称调用dataplex-check-data-quality后从响应中获取operation_id即 LRO 的name字段格式为projects/{project}/locations/{location}/operations/{operation_id}。轮询模板创建状态用dataplex-get-operation工具携带该operation_id持续轮询直到响应中done字段为true且操作成功。注意此步骤只跟踪扫描模板的创建是否完成不跟踪后台执行。提取 scanId操作完成后从返回的 DataScan 资源中提取scanId例如nq-dq-1234。轮询执行任务用dataplex-get-run-status工具携带scanId轮询后台执行任务DataScanJob的状态直到返回的state为SUCCEEDED。若为FAILED需检查错误详情。获取质量结果执行成功后调用dataplex-get-data-quality-results携带scanId获取最终的规则通过状态、总体得分、维度得分如 COMPLETENESS、列级得分及规则评估明细其中failingRowsQuery字段可直接返回可执行的 SQL 查询用于定位未通过检查的具体数据行。这一整套工具在预置配置中归属于enrich工具集见 dataplex.yaml 中kind: toolset的定义与generate_data_insights、generate_data_profile、discover_metadata等扫描类工具并列共同构成“元数据增强 / 治理”能力面。参数详解dataplex-check-data-quality工具接受以下参数字段类型必填说明resourcePathstringtrue目标 BigQuery 表的资源路径格式projects/{project}/datasets/{dataset}/tables/{table}。locationstringtrue执行扫描的 Google Cloud 区域例如us-central1。publishbooleanfalse若为 true将质量结果直接发布到 Dataplex Universal Catalog。默认值为 false。specJSONstringtrue定义质量检查规则的原始 JSON 字符串例如{rules: [{column: age, nonNullExpectation: {}}]}直接映射到dataplexpb.DataQualitySpec。从源码看参数的校验与去向在 dataplexcheckdataquality.go 的Initialize中四个参数被定义为标准参数对象parameters.NewStringParameter/parameters.NewBooleanParameter其中resourcePath的描述明确支持三种输入形态裸表名my_table、dataset.table形式my_dataset.my_table、或全限定路径//bigquery.googleapis.com/projects/{project}/datasets/{dataset}/tables/{table}。在Invoke阶段第 104-134 行工具依次执行必填校验resourcePath、location、specJSON任一为空都会返回AgentErrorxxx parameter is requiredpublish为可选布尔值路径归一化调用dataplexcommon.NormalizeResourcePath(resourcePath, source.ProjectID())把各种简写形式转换为 Dataplex 认可的全限定资源 URI发起扫描调用 source 的GenerateDataQuality(ctx, location, resourcePath, specJSON, publish)成功则返回{operation_id: opName}失败则通过util.ProcessGcpError包装 GCP 错误。resourcePath 的归一化规则路径归一化逻辑实现在 util.go其规则可以总结为输入形式归一化结果gs://my-bucket/...//storage.googleapis.com/projects/{project}/buckets/{bucket}//storage.googleapis.com/buckets/...同上提取桶名//storage.googleapis.com/projects/...原样返回//bigquery.googleapis.com/...原样返回projects/{p}/datasets/{d}/tables/{t}前缀补//bigquery.googleapis.com/project.dataset.table三段//bigquery.googleapis.com/projects/{project}/datasets/{dataset}/tables/{table}dataset.table两段使用 source 的 ProjectID 补齐 project 段其他原样返回这意味着调用方既可以传最规范的projects/...全路径也可以传dataset.table甚至裸表名工具会根据 source 配置的project自动补齐。配置示例在 MCP Toolbox 中声明工具dataplex-check-data-quality是典型的类型化工具需要在 MCP Toolbox 的服务配置中与一个 Knowledge Catalogdataplex 类型source 绑定后使用。一个最小可用的 YAML 声明如下kind: tool name: check_data_quality type: dataplex-check-data-quality source: my-dataplex-source description: Trigger a new data quality scan.各字段的参考说明字段类型必填说明typestringtrue必须为dataplex-check-data-quality。sourcestringtrue该工具要执行于其上的 source 名称。descriptionstringtrue传给 LLM 的工具描述。配套的 source 声明上面的source: my-dataplex-source需要指向一个dataplex类型的 source。完整说明见 source.md其最小配置为kind: source name: my-dataplex-source type: dataplex project: my-project-id字段类型必填说明typestringtrue必须为dataplex。projectstringtrue用于配额与计费的 GCP 项目 ID例如my-project-id。仓库还内置了完整的开箱即用预置配置 dataplex.yaml其中就包含名为check_data_quality的工具声明并配套get_data_quality_results、get_operation、get_run_status等工具以及discovery、data-products、enrich三个工具集可直接作为自定义配置的蓝本。specJSON 的推荐写法specJSON直接映射到 Dataplex 的DataQualitySpecproto。结合源码中的示例dataplexcheckdataquality.go与文档示例推荐使用如下结构{ rules: [ {column: my_col, dimension: COMPLETENESS, nonNullExpectation: {}}, {column: age, rangeExpectation: {minValue: 0, maxValue: 150}} ], catalogPublishingEnabled: false }其中catalogPublishingEnabled与工具参数publish语义对应——实际上源码在 dataplex.go 中会无条件用publish参数覆盖dqSpec.CatalogPublishingEnabled第 1050 行因此两者取其一即可工具参数优先级更高。前置条件IAM 权限与身份认证Knowledge Catalog 使用 [Identity and Access ManagementIAM] 控制用户和群组对 Knowledge Catalog 资源的访问。MCP Toolbox 会使用你的Application Default CredentialsADC与 Knowledge Catalog 交互时完成授权与认证。因此除了为你的 MCP server 正确配置 ADC 之外还需要确保该 IAM 身份具备执行目标操作所需的 IAM 权限具体包括创建/触发 DataScan数据质量扫描所需的 Dataplex 相关权限若设置publish: true还需要向 Dataplex Universal Catalog 发布结果的权限读取 BigQuery 表数据的权限以便扫描引擎对目标表执行规则评估。建议为 IAM 身份绑定 Knowledge CatalogDataplex预定义角色或最小权限自定义角色具体角色与权限清单可查阅 Knowledge Catalog IAM 权限与角色官方文档详见 source.md 中指向的 Dataplex 文档。源码级原理一次扫描请求是如何组装的当 Agent 或客户端调用该工具时底层调用链为Tool.Invoke→source.GenerateDataQuality→ Dataplex API 的CreateDataScan。关键实现位于 dataplex.go值得关注的细节有父级路径parent projects/{project}/locations/{location}project取自 source 配置location来自工具参数自动生成 DataScan IDnq-dq-{uuid}保证每次调用创建全新的扫描模板互不冲突规则解析specJSON通过protojson.Unmarshal直接反序列化为dataplexpb.DataQualitySpec解析失败会明确报错failed to parse data quality spec JSON一次性触发ExecutionSpec使用Trigger_OneTime即本次调用立即执行一次质量评估而不是周期调度扫描类型与标签Type DATA_QUALITY并打上onemcp-server: true标签便于在 Dataplex 控制台中识别来自 MCP Toolbox 的扫描返回值CreateDataScan返回的 LRO 的Name()即文档所述operation_id供后续dataplex-get-operation轮询。这也解释了为什么文档反复强调“先轮询get-operation再轮询get-run-status”CreateDataScan只保证模板创建成功而真正的规则评估发生在后台的 DataScanJob 中必须通过scanId跟踪执行状态。关联工具链与验收闭环单个dataplex-check-data-quality调用并不构成完整的数据质量治理闭环建议与以下工具配合使用文档与预置配置均覆盖dataplex-get-operation轮询 LRO 直到done: true并从中提取scanIddataplex-get-run-status以scanId轮询后台执行状态直到SUCCEEDEDdataplex-get-data-quality-results获取最终质量结果包括总体通过状态、总体得分、维度级得分如 COMPLETENESS、列级得分与规则评估明细以及用于定位失败行的failingRowsQuerydataplex-search-dq-scans在发起新扫描前检索已有的数据质量扫描避免重复创建。上述工具的文档位于 knowledge-catalog/tools 目录预置配置见 dataplex.yaml。整体而言dataplex-check-data-quality为 Agent 提供了一条从“定义规则 → 触发扫描 → 跟踪执行 → 获取结果 → 定位问题行”的完整自动化路径可直接嵌入数据管道巡检、数据资产治理等场景。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考