企业官网建设流程全解析

MCP Toolbox 的 dataplex-search-entries 工具：在 Knowledge Catalog 中高效检索数据资产条目

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

导读

dataplex-search-entries是 MCP Toolbox（MCP Toolbox for Databases）为 Google Cloud Knowledge Catalog（前称 Dataplex）提供的关键检索工具，它允许 Agent 根据用户查询返回目录中匹配的数据资产条目（Entry，如表、视图、模型等）。本文将以官方文档 knowledge-catalog-search-entries.md 为骨架，结合仓库源码、预置配置与测试用例，完整讲解该工具的接入前置条件、四个核心参数、YAML 配置方式、底层调用链以及 Dataplex 查询语法实战，帮助你快速让 LLM/Agent 具备"在元数据目录中按语义找数据"的能力。

一、工具定位：在元数据目录中"按查询找条目"

Knowledge Catalog（前称 Dataplex）是 Google Cloud 面向数据与 AI 资产的统一智能治理方案，其核心是一个集中式目录，保存了组织内所有数据资产的业务、技术与运行时元数据，并借助 AI/ML 自动发现元数据之间的关联与语义（详见 Knowledge Catalog Source 文档）。

dataplex-search-entries工具的作用就是：返回 Knowledge Catalog 中与用户查询匹配的所有条目（例如 BigQuery 表、视图、模型、Cloud Storage 对象等数据资产）。它通过受控的查询字符串把"自然语言诉求"翻译成对目录索引的结构化检索，是 Agent 在元数据场景下做发现（Discovery）的入口级工具。

从源码看，该工具在仓库中以类型名dataplex-search-entries注册。见 dataplexsearchentries.go：

const resourceType string = "dataplex-search-entries" func init() { if !tools.Register(resourceType, newConfig) { panic(fmt.Sprintf("tool type %q already registered", resourceType)) } }

工具采用"注册表 + 工厂"模式：init()将类型名与配置构造函数绑定，Toolbox 在启动解析配置文件时据此实例化对应工具。这意味着只要在配置中声明type: dataplex-search-entries，框架就能自动识别并加载。

二、前置条件：ADC 认证与 IAM 权限

在调用该工具之前，必须完成两项基础设施配置（对应原文档 Requirements 一节）：

1. 设置 Application Default Credentials（ADC）：Toolbox 使用 ADC 对 Knowledge Catalog 发起授权与认证。你需要在运行 MCP Toolbox 服务器的环境中配置 ADC（例如通过gcloud auth application-default login或设置服务账号凭据），使服务器进程具备向 Google Cloud 发出请求的身份。
2. 为身份授予正确的 IAM 权限：除了 ADC 本身，还需要确保该 IAM 身份拥有你打算执行任务所需的 Knowledge Catalog IAM 权限与角色。例如搜索目录条目通常需要具备对 Catalog 资源的读取类权限（如dataplex.catalogEntries.search等，具体以 Knowledge Catalog 的 IAM 权限/角色文档为准）。权限不足时，工具调用会返回 Google Cloud 侧的错误（源码中通过util.ProcessGcpError(err)统一处理并透出）。

提示：关于 IAM 权限与角色的详细矩阵、ADC 的具体配置步骤，属于 Google Cloud 平台文档范畴；在仓库内可以进一步参考 knowledge-catalog 目录 下的 source 与 prebuilt-configs 文档了解接入方式。

三、参数详解：query / scope / pageSize / orderBy

原文档给出了该工具的核心参数表，这里逐项展开并结合源码补充默认值与取值细节（参数定义见 dataplexsearchentries.go）：

3.1 query：查询字符串

这是唯一必填参数，也是决定检索质量的关键。源码中对其描述给出了一条非常有价值的实战建议（见 dataplexsearchentries.go）：

• 支持逻辑运算符与分组，例如要查找可能被改过名的表，可构造type:table (name:books OR fiction)，这比多次单独调用更高效；
• 性能警告：在不加具体过滤条件（如type:table）的情况下做宽泛搜索可能很慢且消耗大量资源；进行探索性搜索时，务必使用pageSize限制返回结果数量。

3.2 scope：限定搜索空间

scope可选，仅在非空时才会被写入请求（见 dataplex.go）：

if scope != "" { req.Scope = scope }

合法的取值格式为organizations/<org_id>、projects/<project_id>或projects/<project_number>。用它把搜索限定到某个组织或项目，可以显著收窄结果集、提升精确度与性能。

3.3 pageSize：分页控制

控制单页结果条数，默认 5。在SearchEntries实现中，pageSize还承担了"迭代上限"的职责：实现会不断从迭代器中取结果，直到已收集数量达到 pageSize或迭代器耗尽（见 dataplex.go）：

func (s *Source) SearchEntries(ctx context.Context, query string, pageSize int, orderBy string, scope string) ([]*dataplexpb.SearchEntriesResult, error) { if pageSize <= 0 { return nil, fmt.Errorf("pageSize must be positive: %d", pageSize) } it, err := s.searchRequest(ctx, query, pageSize, orderBy, scope) ... var results []*dataplexpb.SearchEntriesResult for len(results) < pageSize { entry, err := it.Next() if err == iterator.Done { break } ... results = append(results, entry) } return results, nil }

也就是说，pageSize既是传给后端 API 的每页大小，也是本工具返回给 LLM 的结果数量上限。传入小于等于 0 的值会直接返回错误pageSize must be positive。

3.4 orderBy：结果排序

支持三种取值：

• relevance（默认）：按相关性排序，适合意图不明确的宽泛检索；
• last_modified_timestamp：按最近修改时间排序；
• last_modified_timestamp asc：按最近修改时间升序排序。

该值会原样透传给SearchEntriesRequest.OrderBy字段。

四、配置示例与字段参考

原文档给出了一个标准的工具声明 YAML：

kind: tool name: search_entries type: dataplex-search-entries source: my-dataplex-source description: Use this tool to get all the entries based on the provided query.

对应的Reference字段表如下：

4.1 源码中的 Config 结构

工具配置在源码中对应如下结构（见 dataplexsearchentries.go）：

type Config struct { tools.ConfigBase `yaml:",inline"` Type string `yaml:"type" validate:"required"` Source string `yaml:"source" validate:"required"` Annotations *tools.ToolAnnotations `yaml:"annotations,omitempty"` }

其中type与source均为必填且带validate:"required"校验；ConfigBase内嵌提供name、description、authRequired等通用字段（内联展开），annotations可选，用于声明工具注解（未指定时默认使用只读注解tools.NewReadOnlyAnnotations，见 dataplexsearchentries.go）。这与工具"只读检索"的定位一致。

4.2 测试用例验证

仓库测试 dataplexsearchentries_test.go 中的TestParseFromYamlDataplexSearchEntries直接验证了上述 YAML 的解析结果，例如：

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

解析后应得到Type: "dataplex-search-entries"、Source: "my-instance"、Name: "example_tool"、Description: "some description"、AuthRequired: []string{}。这说明该工具的配置声明方式与文档示例完全一致，可直接复制使用。

4.3 与 Source 的配合

source字段指向一个已声明的dataplex类型 Source。Source 的声明方式见 source.md：

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

其中project为必填，用于配额与计费。工具在运行时通过ValidateSource检查所关联 Source 是否实现了SearchEntries接口（见 dataplexsearchentries.go）：

type compatibleSource interface { SearchEntries(context.Context, string, int, string, string) ([]*dataplexpb.SearchEntriesResult, error) }

若 Source 类型不兼容，会返回错误invalid source for "dataplex-search-entries" tool。这正是"工具与 Source 解耦、按接口约束兼容性"的设计：任何实现了该签名的 Source 都能被此工具复用。

4.4 使用预置配置快速上手

仓库预置配置 dataplex.yaml 已把 Source 与工具打包好，可直接复制使用：

kind: source name: dataplex-source type: dataplex project: ${DATAPLEX_PROJECT} --- kind: tool name: search_entries type: dataplex-search-entries source: dataplex-source description: Searches for data assets (eg. table/dataset/view) in Catalog based on the provided search query.

该文件同时定义了discovery工具集（toolset），其中第一个成员就是search_entries（见 dataplex.yaml），说明它被官方定位为发现类工作流的首选入口。

五、底层实现原理：从参数到 CatalogClient 的调用链

理解底层实现有助于预估行为与排查问题。完整的调用链如下：

1. 工具层（Invoke）：Tool.Invoke从参数映射中依次取出query、pageSize、orderBy、scope（均带类型断言，失败会返回 Agent 错误），然后调用source.SearchEntries(ctx, query, pageSize, orderBy, scope)（见 dataplexsearchentries.go）。
2. Source 层（searchRequest）：构造SearchEntriesRequest，其关键点为（见 dataplex.go）：

req := &dataplexpb.SearchEntriesRequest{ Query: query, Name: fmt.Sprintf("projects/%s/locations/global", s.ProjectID()), PageSize: int32(pageSize), OrderBy: orderBy, SemanticSearch: true, }

• 请求的Name固定为projects/{project}/locations/global，即在整个项目的global位置目录中检索；
• SemanticSearch: true：启用语义搜索——这也是该工具区别于普通关键字匹配的关键特性，配合 Dataplex 目录的 AI 能力，可检索元数据中的语义关联；
• scope仅在非空时写入。

3. 迭代与返回：CatalogClient().SearchEntries返回一个SearchEntriesResultIterator；Source 层循环it.Next()直到收集满pageSize条或迭代器耗尽（iterator.Done），期间错误会被包装为带 gRPC 错误码/消息的明确提示。

六、查询语法实战：把 query 参数用到极致

query参数遵循 Dataplex（Knowledge Catalog）的搜索语法。虽然原文档正文未展开语法细节，但它直接决定了检索能力上限；source.md 的"Tool: search_entries"一节给出了官方推荐给 LLM 的完整语法说明，这里整理为可查手册。

6.1 简单搜索：单个谓词

最简形式的查询就是一个谓词（如foo），它可匹配多类元数据：

• 资源名称、显示名称或描述的子串；
• 资源类型的子串；
• 资源 schema 中列名（或嵌套列名）的子串；
• 项目 ID 的子串；
• 概览（overview）描述中的字符串。

例如foo可以命中名为foo.bar的资源、显示名为Foo Bar的资源、描述含This is the foo script的资源、类型恰为foo的资源、schema 中含foo_bar列的资源、项目prod-foo-bar等。

6.2 限定谓词（Qualified predicates）

通过key=value或key:value把匹配限定到特定元数据字段：

• =表示精确匹配；:表示子串或 token 匹配。
• 例：name:foo匹配名称含foo子串的资源；description:foo匹配描述含footoken 的资源；location=foo精确匹配指定位置。
• 注意：type、system、location、orgid这几个键只支持=精确匹配，不支持:子串匹配。

常用限定谓词速查：

6.3 Aspect 搜索：按元数据面板过滤

条目上挂载的丰富描述信息存放在 Aspect 中，可用以下语法按 Aspect 过滤：

• has:x：匹配 Aspect 类型完整路径含 x 子串的条目；
• has=x：匹配 Aspect 类型完整路径等于 x 的条目；
• xOPERATORvalue：按 Aspect 字段值过滤，路径格式为projectid.location.ASPECT_TYPE_ID.FIELD_NAME。运算符支持取决于字段类型：字符串/枚举/布尔仅=（枚举与布尔仅精确匹配）；数值与日期时间支持=、:、<、>、<=、>=、=>、=<。仅顶层 Aspect 字段可搜索。

系统 Aspect 类型可用省略路径，例如以下三种写法等价：

bigquery-dataset.type=default dataplex-types.bigquery-dataset.type=default dataplex-types.global.bigquery-dataset.type=default

自定义 Aspect 类型则为PROJECT_ID[.REGION].ASPECT_TYPE_ID.FIELD_NAME，例如example-project.us-central1.employee-info.is-enrolled=true。实用过滤示例：

• dataplex-types.global.bigquery-table.type={BIGLAKE_TABLE, BIGLAKE_OBJECT_TABLE, EXTERNAL_TABLE, TABLE}
• dataplex-types.global.storage.type={STRUCTURED, UNSTRUCTURED}

6.4 逻辑运算符与缩写语法

• 未显式写运算符时隐含AND：foo bar表示同时匹配foo与bar；
• 支持OR：foo OR bar；
• 可用-或NOT前缀取反：-name:foo；
• 运算符大小写敏感：OR、AND合法，or、and不合法；
• 缩写语法：|表示 OR、,表示 AND。例如projectid:(id1|id2|id3|id4)等价于projectid:id1 OR projectid:id2 OR projectid:id3 OR projectid:id4；column:(name1,name2,name3)表示 AND、column:(name1|name2|name3)表示 OR。缩写语法适用于除label关键字之外的限定谓词。

6.5 结果处理建议

Source 文档还给出了对 Agent 的响应纪律（可与工具 description 配合使用）：

• 检索到多条结果时，以嵌套有序列表呈现（显示名、projectId、location、description），并询问用户选择其一；
• 仅一条结果时直接呈现；
• 无结果时说明原因并建议更具体的查询；
• 不要自行在结果内再次搜索，也不要在未被明确要求时翻取多页结果。

七、与同族工具协同：检索只是发现的起点

dataplex-search-entries在 Knowledge Catalog 工具族中通常作为第一步——先用它缩小候选范围，再用其他工具深入。可参考 prebuilt-configs 与 dataplex.yaml 中同源工具的协作方式：

• dataplex-lookup-entry：拿到条目名称后，检索单个数据资产的详细元数据（可配合search_aspect_types确定 Aspect 类型以精简响应）；
• dataplex-search-aspect-types：按查询搜索 Aspect 类型，辅助构造精确的 Aspect 过滤条件；
• dataplex-lookup-context：基于资源名列表检索多个资产及其关系的丰富元数据；
• dataplex-search-dq-scans：按过滤条件搜索数据质量扫描。

在discovery工具集中，search_entries与lookup_entry、search_aspect_types、lookup_context被编为一组，正好对应"先搜索、再下钻"的典型 Agent 工作流。

八、小结

dataplex-search-entries用极简的四个参数（query必填，scope/pageSize/orderBy可选）把 Knowledge Catalog 的语义搜索能力开放给 LLM/Agent：

• 接入前：配置好 ADC，并为 IAM 身份授予 Knowledge Catalog 所需权限；
• 配置时：声明type: dataplex-search-entries的 tool 并指向dataplex类型的 source，可参考预置配置 dataplex.yaml；
• 调用时：用 Dataplex 搜索语法构造query（限定谓词、Aspect 过滤、逻辑运算符与缩写语法），并用scope、pageSize控制范围与开销；
• 底层：请求固定面向projects/{project}/locations/global目录并开启SemanticSearch，结果按pageSize封顶返回（实现见 dataplex.go）。

掌握该工具后，你的 Agent 即可在庞大而复杂的元数据目录中精准定位"用户想要的那张表/那个模型"，为后续的数据治理、血缘分析、数据质量检查等高级能力铺平道路。

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