使用 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-toolboxdataplex-search-dq-scans是 MCP ToolboxDataplex/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 ManagementIAM控制用户和组对 Dataplex 资源的访问。Toolbox 在与 Dataplex 交互时会使用你的应用默认凭据Application Default CredentialsADC完成授权与认证。需要在启动服务器前为运行环境配置好 ADC需要确保该 IAM 身份被授予执行相应任务所需的 Dataplex 权限。按 预置配置文档 的说明搜索数据质量扫描属于只读操作授予Dataplex Readerroles/dataplex.viewer即可满足search_dq_scans的检索需求该角色也用于search_entries、lookup_entry等只读搜索工具。若后续还要创建或修改条目则需要 Dataplex Editorroles/dataplex.editor等更高级别的角色。参数详解dataplex-search-dq-scans的所有参数均为可选参数官方文档定义的参数如下字段类型必填说明filterstring否用于搜索/过滤数据质量扫描的过滤字符串例如display_name my-scan。data_scan_idstring否用于过滤的数据扫描资源名projects/{project}/locations/{locationId}/dataScans/{dataScanId}。table_namestring否用于过滤的表名映射到data.entity例如//bigquery.googleapis.com/projects/P/datasets/D/tables/T。pageSizeinteger否单页返回的数据质量扫描数量默认值为 10。orderBystring否指定结果的排序方式。参数的实际语义与过滤字符串组装逻辑对照 工具实现源码可以更精确地理解上述参数在运行时如何被转换为 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控制单页返回条数默认 10orderBy控制排序字段与方向。底层实现跨区域列出数据扫描dataplex-search-dq-scans最终调用的是 Dataplex 数据源上的SearchDataQualityScans方法见 dataplex.go 源码。该方法内部构造一个ListDataScansRequestParent为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.字段说明如下字段类型必填说明typestring是固定为dataplex-search-dq-scans。sourcestring是工具要执行的数据源名称即上文声明的dataplex类型数据源名。descriptionstring是传给 LLM 的工具描述用于让模型理解何时调用该工具。name是该工具在 MCP 会话中的标识名可按需命名description建议写得具体一些例如搜索 Dataplex 中的数据质量扫描便于 LLM 在合适的时机自动选择调用。使用预置配置快速启用如果不希望手写数据源与工具配置可以直接使用仓库提供的 Dataplex 预置配置文件它以kind: source声明了dataplex-sourceproject: ${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 工具创建数据质量扫描模板并触发执行返回长时运行操作LROget_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 会话中直接使用。参考文档knowledge-catalog-search-dq-scans 官方文档Knowledge CatalogDataplex数据源配置Dataplex 预置配置文档Dataplex 预置配置文件工具实现源码数据源实现源码SearchDataQualityScans工具解析测试【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考