使用 MCP Toolbox 的 dataplex-search-dq-scans 工具检索 Dataplex 数据质量扫描-育师

使用 MCP Toolbox 的 dataplex-search-dq-scans 工具检索 Dataplex 数据质量扫描

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox

dataplex-search-dq-scans是 MCP Toolbox（Dataplex/Knowledge Catalog 集成）提供的一个只读工具，用于根据过滤条件、数据扫描资源名、目标表等参数，在 Google Cloud Dataplex 中检索满足条件的数据质量扫描（Data Quality Scan）。本文以该工具的官方文档为主体，结合仓库内工具实现、数据源实现与测试用例，完整讲解其参数语义、YAML 配置方式、底层调用链与典型使用场景，帮助开发者与 AI Agent 快速掌握在 MCP 会话中检索数据质量扫描的完整方法。

工具概述与适用场景

dataplex-search-dq-scans的作用是：返回符合给定条件的数据质量扫描。它归属于 Knowledge Catalog（原 Dataplex）集成，在 Dataplex 预置配置中作为search_dq_scans工具随--prebuilt dataplex一起提供，并被纳入discovery工具集（toolset），与search_entries、lookup_entry、search_aspect_types、lookup_context共同构成元数据发现与搜索能力。

典型使用场景包括：

在元数据治理会话中回答"当前项目里有哪些针对某张 BigQuery 表的数据质量扫描"；
在 Agent 编排数据质量工作流（如先创建质量扫描、再获取扫描结果）之前，先确认是否已存在同名或同表的扫描，避免重复创建；
按display_name、资源名或数据实体（表/存储桶）定位扫描，为后续get_data_quality_results等操作提供dataScanId。

前置条件：兼容数据源与 IAM 权限

兼容数据源

该工具必须运行在类型为dataplex的数据源之上。数据源的最小配置如下（详见 Knowledge Catalog 数据源文档）：

kind: source name: my-dataplex-source type: "dataplex" project: "my-project-id"

其中project为必填项，用于确定配额与计费所属的 GCP 项目。

从源码结构看，工具通过接口约束来校验数据源兼容性：dataplexsearchdqscans包定义了compatibleSource接口，要求数据源实现SearchDataQualityScans(context.Context, string, int, string)方法（见 dataplexsearchdqscans.go）。若在配置中为工具指定的source指向其他不兼容的数据源，ValidateSource会直接报错"source is not a compatible type"。

IAM 权限与身份认证

Dataplex 使用 Identity and Access Management（IAM）控制用户和组对 Dataplex 资源的访问。Toolbox 在与 Dataplex 交互时，会使用你的应用默认凭据（Application Default Credentials，ADC）完成授权与认证。

需要在启动服务器前为运行环境配置好 ADC；
需要确保该 IAM 身份被授予执行相应任务所需的 Dataplex 权限。

按预置配置文档的说明，搜索数据质量扫描属于只读操作，授予Dataplex Reader（roles/dataplex.viewer）即可满足search_dq_scans的检索需求（该角色也用于search_entries、lookup_entry等只读搜索工具）。若后续还要创建或修改条目，则需要 Dataplex Editor（roles/dataplex.editor）等更高级别的角色。

参数详解

dataplex-search-dq-scans的所有参数均为可选参数，官方文档定义的参数如下：

字段	类型	必填	说明
filter	string	否	用于搜索/过滤数据质量扫描的过滤字符串（例如`display_name = "my-scan"`）。
data_scan_id	string	否	用于过滤的数据扫描资源名（`projects/{project}/locations/{locationId}/dataScans/{dataScanId}`）。
table_name	string	否	用于过滤的表名，映射到`data.entity`（例如`//bigquery.googleapis.com/projects/P/datasets/D/tables/T`）。
pageSize	integer	否	单页返回的数据质量扫描数量，默认值为 10。
orderBy	string	否	指定结果的排序方式。

参数的实际语义与过滤字符串组装逻辑

对照工具实现源码，可以更精确地理解上述参数在运行时如何被转换为 Dataplex 过滤条件：

filter：用户传入的过滤字符串会原样保留；
dataScanId：若提供，会组装成name = "projects/{project}/locations/{locationId}/dataScans/{dataScanId}"形式；
resourcePath（对应文档中的table_name场景）：若提供，会组装成data.resource = "//bigquery.googleapis.com/projects/P/datasets/D/tables/T"形式；
最终将所有非空条件用AND拼接为完整的finalFilter传给 Dataplex 后端。

需要注意两点：

文档中以用户视角命名参数为data_scan_id与table_name，而在 MCP 工具的运行时参数清单（Manifest）中，源码注册的参数名是dataScanId与resourcePath（见 Initialize 中的参数定义），resourcePath的官方注释即为"要过滤的表或存储桶的资源路径，映射到过滤字符串中的data.entity"。在 MCP 客户端实际调用时，请以运行时参数名dataScanId、resourcePath为准，同时参考文档中的data_scan_id、table_name语义。
pageSize与orderBy直接透传：pageSize控制单页返回条数（默认 10），orderBy控制排序字段与方向。

底层实现：跨区域列出数据扫描

dataplex-search-dq-scans最终调用的是 Dataplex 数据源上的SearchDataQualityScans方法（见 dataplex.go 源码）。该方法内部构造一个ListDataScansRequest：

Parent为projects/{project}/locations/-，其中-表示跨所有区域进行检索；
Filter、PageSize、OrderBy直接取自工具传入的参数；
通过DataScanClient.ListDataScans返回一个迭代器（iterator），源码在len(results) < pageSize的循环内逐条取出结果，遇到iterator.Done时提前结束，遇到其他错误时会携带 gRPC 错误码与消息返回。

此外，从源码可以推断出两个边界行为：pageSize <= 0会被视为非法输入并直接返回错误（"pageSize must be positive"）；返回结果的条数不会超过pageSize，即使后端存在更多匹配项，也只会返回当前页的数据。

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

在 Toolbox 的配置文件中，以kind: tool声明该工具即可将其注册到 MCP 服务器：

kind: tool name: search_dq_scans type: dataplex-search-dq-scans source: my-dataplex-source description: Use this tool to search for data quality scans.

字段说明如下：

字段	类型	必填	说明
type	string	是	固定为`"dataplex-search-dq-scans"`。
source	string	是	工具要执行的数据源名称（即上文声明的`dataplex`类型数据源名）。
description	string	是	传给 LLM 的工具描述，用于让模型理解何时调用该工具。

name是该工具在 MCP 会话中的标识名，可按需命名；description建议写得具体一些，例如"搜索 Dataplex 中的数据质量扫描"，便于 LLM 在合适的时机自动选择调用。

使用预置配置快速启用

如果不希望手写数据源与工具配置，可以直接使用仓库提供的 Dataplex 预置配置文件：它以kind: source声明了dataplex-source（project: ${DATAPLEX_PROJECT}环境变量注入），并预置了search_dq_scans工具，同时将其纳入discovery工具集。启用方式为在启动 Toolbox 服务器时传入--prebuilt dataplex，并提前设置环境变量DATAPLEX_PROJECT为你的 GCP 项目 ID。

调用示例与典型工作流

按显示名称检索

向 LLM/Agent 提出类似"帮我查一下名为 my-scan 的数据质量扫描"时，模型会以display_name = "my-scan"作为filter参数调用本工具，返回匹配的扫描及其资源信息。

按目标表检索

当需要确认某张 BigQuery 表是否已配置质量扫描时，可传入resourcePath（文档语义为table_name）参数，例如：

resourcePath: "//bigquery.googleapis.com/projects/P/datasets/D/tables/T"

该参数会被组装为data.resource = "//bigquery.googleapis.com/projects/P/datasets/D/tables/T"过滤条件，只返回针对该数据实体的扫描。

与数据质量工具链协同

search_dq_scans在 Dataplex 数据质量工作流中扮演"检索/定位"角色，可与同集成的其他工具形成完整闭环：

check_data_quality 工具：创建数据质量扫描模板并触发执行，返回长时运行操作（LRO）；
get_data_quality_results 工具：按dataScanId获取扫描完成后的质量得分与规则评估结果。

推荐的 Agent 编排顺序是：先用search_dq_scans判断是否存在目标扫描，若不存在再创建，创建完成后轮询get_operation、get_run_status，最后用get_data_quality_results获取结果——这样既能避免重复创建扫描，也能在检索时直接拿到已有的dataScanId。

实现与测试佐证

仓库为工具提供了完整的解析测试：dataplexsearchdqscans_test.go 中的TestParseFromYamlDataplexSearchDQScans验证了以下 YAML 能被正确解析为Config结构：

kind: tool name: example_tool type: dataplex-search-dq-scans source: my-instance description: some description

测试断言了解析结果中的Name、Description、Type（固定为dataplex-search-dq-scans）与Source字段，确认了配置格式与字段映射与本文描述一致。工具通过init()中的tools.Register(resourceType, newConfig)完成注册（见 dataplexsearchdqscans.go），并在Invoke中对不兼容数据源返回客户端错误，保证调用链的类型安全。

小结

dataplex-search-dq-scans是 MCP Toolbox 中检索 Dataplex 数据质量扫描的标准入口：它以可选的filter、dataScanId、resourcePath、pageSize、orderBy参数覆盖了按名称、按资源名、按目标表等多种检索方式，底层通过跨区域ListDataScans调用实现，并与check_data_quality、get_data_quality_results等工具共同支撑完整的数据质量治理闭环。配置时只需确保数据源类型为dataplex、IAM 身份具备 Dataplex Reader 权限，即可在 MCP 会话中直接使用。