企业官网建设流程全解析

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 Catalog（Dataplex）集成中的核心工具之一，其作用是创建一个新的 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 Operation（LRO）名称。你必须严格按下面描述的编排顺序轮询，才能最终拿到质量分数。

异步编排：完整的数据质量巡检工作流

由于整个流程跨越“模板创建”和“后台执行”两个异步阶段，MCP Toolbox 用多个工具组合出完整工作流。仓库中的预置配置 dataplex.yaml 对 Agent 给出了明确的 5 步编排要求，这也是本文推荐的标准流程：

1. 捕获 LRO 名称：调用dataplex-check-data-quality后，从响应中获取operation_id（即 LRO 的name字段，格式为projects/{project}/locations/{location}/operations/{operation_id}）。
2. 轮询模板创建状态：用dataplex-get-operation工具携带该operation_id持续轮询，直到响应中done字段为true且操作成功。注意：此步骤只跟踪扫描模板的创建是否完成，不跟踪后台执行。
3. 提取 scanId：操作完成后，从返回的 DataScan 资源中提取scanId（例如nq-dq-1234）。
4. 轮询执行任务：用dataplex-get-run-status工具携带scanId轮询后台执行任务（DataScanJob）的状态，直到返回的state为SUCCEEDED。若为FAILED，需检查错误详情。
5. 获取质量结果：执行成功后，调用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工具接受以下参数：

从源码看参数的校验与去向

在 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 行），工具依次执行：

1. 必填校验：resourcePath、location、specJSON任一为空都会返回AgentError（"xxx parameter is required"），publish为可选布尔值；
2. 路径归一化：调用dataplexcommon.NormalizeResourcePath(resourcePath, source.ProjectID())，把各种简写形式转换为 Dataplex 认可的全限定资源 URI；
3. 发起扫描：调用 source 的GenerateDataQuality(ctx, location, resourcePath, specJSON, publish)，成功则返回{"operation_id": opName}，失败则通过util.ProcessGcpError包装 GCP 错误。

resourcePath 的归一化规则

路径归一化逻辑实现在 util.go，其规则可以总结为：

这意味着调用方既可以传最规范的projects/...全路径，也可以传dataset.table甚至裸表名，工具会根据 source 配置的project自动补齐。

配置示例：在 MCP Toolbox 中声明工具

dataplex-check-data-quality是典型的"类型化工具"，需要在 MCP Toolbox 的服务配置中与一个 Knowledge Catalog（dataplex 类型）source 绑定后使用。一个最小可用的 YAML 声明如下：

kind: tool name: check_data_quality type: dataplex-check-data-quality source: my-dataplex-source description: Trigger a new data quality scan.

各字段的参考说明：

配套的 source 声明

上面的source: my-dataplex-source需要指向一个dataplex类型的 source。完整说明见 source.md，其最小配置为：

kind: source name: my-dataplex-source type: "dataplex" project: "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 Management（IAM）] 控制用户和群组对 Knowledge Catalog 资源的访问。MCP Toolbox 会使用你的Application Default Credentials（ADC）与 Knowledge Catalog 交互时完成授权与认证。

因此，除了为你的 MCP server 正确配置 ADC 之外，还需要确保该 IAM 身份具备执行目标操作所需的 IAM 权限，具体包括：

• 创建/触发 DataScan（数据质量扫描）所需的 Dataplex 相关权限；
• 若设置publish: true，还需要向 Dataplex Universal Catalog 发布结果的权限；
• 读取 BigQuery 表数据的权限，以便扫描引擎对目标表执行规则评估。

建议为 IAM 身份绑定 Knowledge Catalog（Dataplex）预定义角色或最小权限自定义角色，具体角色与权限清单可查阅 Knowledge Catalog IAM 权限与角色官方文档（详见 source.md 中指向的 Dataplex 文档）。

源码级原理：一次扫描请求是如何组装的

当 Agent 或客户端调用该工具时，底层调用链为：Tool.Invoke→source.GenerateDataQuality→ Dataplex API 的CreateDataScan。关键实现位于 dataplex.go，值得关注的细节有：

1. 父级路径：parent = projects/{project}/locations/{location}，project取自 source 配置，location来自工具参数；
2. 自动生成 DataScan ID：nq-dq-{uuid}，保证每次调用创建全新的扫描模板，互不冲突；
3. 规则解析：specJSON通过protojson.Unmarshal直接反序列化为dataplexpb.DataQualitySpec，解析失败会明确报错failed to parse data quality spec JSON；
4. 一次性触发：ExecutionSpec使用Trigger_OneTime，即本次调用立即执行一次质量评估，而不是周期调度；
5. 扫描类型与标签：Type = DATA_QUALITY，并打上onemcp-server: "true"标签，便于在 Dataplex 控制台中识别来自 MCP Toolbox 的扫描；
6. 返回值：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，并从中提取scanId；
• dataplex-get-run-status：以scanId轮询后台执行状态，直到SUCCEEDED；
• dataplex-get-data-quality-results：获取最终质量结果，包括总体通过状态、总体得分、维度级得分（如 COMPLETENESS）、列级得分与规则评估明细，以及用于定位失败行的failingRowsQuery；
• dataplex-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