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 ToolboxMCP 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.goconst 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 一节设置 Application Default CredentialsADCToolbox 使用 ADC 对 Knowledge Catalog 发起授权与认证。你需要在运行 MCP Toolbox 服务器的环境中配置 ADC例如通过gcloud auth application-default login或设置服务账号凭据使服务器进程具备向 Google Cloud 发出请求的身份。为身份授予正确的 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.gofieldtyperequireddescription默认值 / 说明querystringtrue用于过滤条目的搜索查询字符串无默认值必填遵循 Dataplex 搜索语法支持逻辑运算符AND、OR、NOT与分组scopestringfalse限定搜索空间organizations/org_id、projects/project_id或projects/project_number默认空字符串为空时不限定范围pageSizeintegerfalse单页返回的结果条数默认5orderBystringfalse结果排序方式relevance、last_modified_timestamp、last_modified_timestamp asc默认relevance3.1 query查询字符串这是唯一必填参数也是决定检索质量的关键。源码中对其描述给出了一条非常有价值的实战建议见 dataplexsearchentries.go支持逻辑运算符与分组例如要查找可能被改过名的表可构造type:table (name:books OR fiction)这比多次单独调用更高效性能警告在不加具体过滤条件如type:table的情况下做宽泛搜索可能很慢且消耗大量资源进行探索性搜索时务必使用pageSize限制返回结果数量。3.2 scope限定搜索空间scope可选仅在非空时才会被写入请求见 dataplex.goif scope ! { req.Scope scope }合法的取值格式为organizations/org_id、projects/project_id或projects/project_number。用它把搜索限定到某个组织或项目可以显著收窄结果集、提升精确度与性能。3.3 pageSize分页控制控制单页结果条数默认 5。在SearchEntries实现中pageSize还承担了迭代上限的职责实现会不断从迭代器中取结果直到已收集数量达到 pageSize或迭代器耗尽见 dataplex.gofunc (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字段。四、配置示例与字段参考原文档给出了一个标准的工具声明 YAMLkind: 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字段表如下fieldtyperequireddescriptiontypestringtrue必须为dataplex-search-entriessourcestringtrue工具执行所依赖的 source 名称descriptionstringtrue传给 LLM 的工具描述4.1 源码中的 Config 结构工具配置在源码中对应如下结构见 dataplexsearchentries.gotype 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.mdkind: source name: my-dataplex-source type: dataplex project: my-project-id其中project为必填用于配额与计费。工具在运行时通过ValidateSource检查所关联 Source 是否实现了SearchEntries接口见 dataplexsearchentries.gotype 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 的调用链理解底层实现有助于预估行为与排查问题。完整的调用链如下工具层InvokeTool.Invoke从参数映射中依次取出query、pageSize、orderBy、scope均带类型断言失败会返回 Agent 错误然后调用source.SearchEntries(ctx, query, pageSize, orderBy, scope)见 dataplexsearchentries.go。Source 层searchRequest构造SearchEntriesRequest其关键点为见 dataplex.goreq : 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仅在非空时写入。迭代与返回CatalogClient().SearchEntries返回一个SearchEntriesResultIteratorSource 层循环it.Next()直到收集满pageSize条或迭代器耗尽iterator.Done期间错误会被包装为带 gRPC 错误码/消息的明确提示。六、查询语法实战把 query 参数用到极致query参数遵循 DataplexKnowledge 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通过keyvalue或key:value把匹配限定到特定元数据字段表示精确匹配:表示子串或 token 匹配。例name:foo匹配名称含foo子串的资源description:foo匹配描述含footoken 的资源locationfoo精确匹配指定位置。注意type、system、location、orgid这几个键只支持精确匹配不支持:子串匹配。常用限定谓词速查谓词含义name:xx 作为资源 ID 的子串displayname:xx 作为资源显示名的子串column:xx 作为嵌套列名的子串description:xx 作为描述中的 tokenlabel:bar/labelbar按标签键的子串/精确匹配 BigQuery 资源label:bar:x/label.foobar按标签键标签值匹配typeTYPE按条目类型或类型别名精确匹配projectid:bar项目 ID 含 bar 子串parent:x资源层级路径同name语法orgidnumber组织 ID 精确匹配systemSYSTEM按系统匹配如systembigquerylocationLOCATION位置精确匹配如locationus-central1BigQuery Omni 资源用其区域名如locationaws-us-east-1createtime/updatetime按创建/更新时间匹配如createtime:2019-01-01、updatetime2019-01-016.3 Aspect 搜索按元数据面板过滤条目上挂载的丰富描述信息存放在 Aspect 中可用以下语法按 Aspect 过滤has:x匹配 Aspect 类型完整路径含 x 子串的条目hasx匹配 Aspect 类型完整路径等于 x 的条目xOPERATORvalue按 Aspect 字段值过滤路径格式为projectid.location.ASPECT_TYPE_ID.FIELD_NAME。运算符支持取决于字段类型字符串/枚举/布尔仅枚举与布尔仅精确匹配数值与日期时间支持、:、、、、、、。仅顶层 Aspect 字段可搜索。系统 Aspect 类型可用省略路径例如以下三种写法等价bigquery-dataset.typedefault dataplex-types.bigquery-dataset.typedefault dataplex-types.global.bigquery-dataset.typedefault自定义 Aspect 类型则为PROJECT_ID[.REGION].ASPECT_TYPE_ID.FIELD_NAME例如example-project.us-central1.employee-info.is-enrolledtrue。实用过滤示例dataplex-types.global.bigquery-table.type{BIGLAKE_TABLE, BIGLAKE_OBJECT_TABLE, EXTERNAL_TABLE, TABLE}dataplex-types.global.storage.type{STRUCTURED, UNSTRUCTURED}6.4 逻辑运算符与缩写语法未显式写运算符时隐含ANDfoo bar表示同时匹配foo与bar支持ORfoo 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:id4column:(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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
MCP Toolbox 的 dataplex-search-entries 工具：在 Knowledge Catalog 中高效检索数据资产条目
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 ToolboxMCP 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.goconst 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 一节设置 Application Default CredentialsADCToolbox 使用 ADC 对 Knowledge Catalog 发起授权与认证。你需要在运行 MCP Toolbox 服务器的环境中配置 ADC例如通过gcloud auth application-default login或设置服务账号凭据使服务器进程具备向 Google Cloud 发出请求的身份。为身份授予正确的 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.gofieldtyperequireddescription默认值 / 说明querystringtrue用于过滤条目的搜索查询字符串无默认值必填遵循 Dataplex 搜索语法支持逻辑运算符AND、OR、NOT与分组scopestringfalse限定搜索空间organizations/org_id、projects/project_id或projects/project_number默认空字符串为空时不限定范围pageSizeintegerfalse单页返回的结果条数默认5orderBystringfalse结果排序方式relevance、last_modified_timestamp、last_modified_timestamp asc默认relevance3.1 query查询字符串这是唯一必填参数也是决定检索质量的关键。源码中对其描述给出了一条非常有价值的实战建议见 dataplexsearchentries.go支持逻辑运算符与分组例如要查找可能被改过名的表可构造type:table (name:books OR fiction)这比多次单独调用更高效性能警告在不加具体过滤条件如type:table的情况下做宽泛搜索可能很慢且消耗大量资源进行探索性搜索时务必使用pageSize限制返回结果数量。3.2 scope限定搜索空间scope可选仅在非空时才会被写入请求见 dataplex.goif scope ! { req.Scope scope }合法的取值格式为organizations/org_id、projects/project_id或projects/project_number。用它把搜索限定到某个组织或项目可以显著收窄结果集、提升精确度与性能。3.3 pageSize分页控制控制单页结果条数默认 5。在SearchEntries实现中pageSize还承担了迭代上限的职责实现会不断从迭代器中取结果直到已收集数量达到 pageSize或迭代器耗尽见 dataplex.gofunc (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字段。四、配置示例与字段参考原文档给出了一个标准的工具声明 YAMLkind: 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字段表如下fieldtyperequireddescriptiontypestringtrue必须为dataplex-search-entriessourcestringtrue工具执行所依赖的 source 名称descriptionstringtrue传给 LLM 的工具描述4.1 源码中的 Config 结构工具配置在源码中对应如下结构见 dataplexsearchentries.gotype 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.mdkind: source name: my-dataplex-source type: dataplex project: my-project-id其中project为必填用于配额与计费。工具在运行时通过ValidateSource检查所关联 Source 是否实现了SearchEntries接口见 dataplexsearchentries.gotype 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 的调用链理解底层实现有助于预估行为与排查问题。完整的调用链如下工具层InvokeTool.Invoke从参数映射中依次取出query、pageSize、orderBy、scope均带类型断言失败会返回 Agent 错误然后调用source.SearchEntries(ctx, query, pageSize, orderBy, scope)见 dataplexsearchentries.go。Source 层searchRequest构造SearchEntriesRequest其关键点为见 dataplex.goreq : 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仅在非空时写入。迭代与返回CatalogClient().SearchEntries返回一个SearchEntriesResultIteratorSource 层循环it.Next()直到收集满pageSize条或迭代器耗尽iterator.Done期间错误会被包装为带 gRPC 错误码/消息的明确提示。六、查询语法实战把 query 参数用到极致query参数遵循 DataplexKnowledge 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通过keyvalue或key:value把匹配限定到特定元数据字段表示精确匹配:表示子串或 token 匹配。例name:foo匹配名称含foo子串的资源description:foo匹配描述含footoken 的资源locationfoo精确匹配指定位置。注意type、system、location、orgid这几个键只支持精确匹配不支持:子串匹配。常用限定谓词速查谓词含义name:xx 作为资源 ID 的子串displayname:xx 作为资源显示名的子串column:xx 作为嵌套列名的子串description:xx 作为描述中的 tokenlabel:bar/labelbar按标签键的子串/精确匹配 BigQuery 资源label:bar:x/label.foobar按标签键标签值匹配typeTYPE按条目类型或类型别名精确匹配projectid:bar项目 ID 含 bar 子串parent:x资源层级路径同name语法orgidnumber组织 ID 精确匹配systemSYSTEM按系统匹配如systembigquerylocationLOCATION位置精确匹配如locationus-central1BigQuery Omni 资源用其区域名如locationaws-us-east-1createtime/updatetime按创建/更新时间匹配如createtime:2019-01-01、updatetime2019-01-016.3 Aspect 搜索按元数据面板过滤条目上挂载的丰富描述信息存放在 Aspect 中可用以下语法按 Aspect 过滤has:x匹配 Aspect 类型完整路径含 x 子串的条目hasx匹配 Aspect 类型完整路径等于 x 的条目xOPERATORvalue按 Aspect 字段值过滤路径格式为projectid.location.ASPECT_TYPE_ID.FIELD_NAME。运算符支持取决于字段类型字符串/枚举/布尔仅枚举与布尔仅精确匹配数值与日期时间支持、:、、、、、、。仅顶层 Aspect 字段可搜索。系统 Aspect 类型可用省略路径例如以下三种写法等价bigquery-dataset.typedefault dataplex-types.bigquery-dataset.typedefault dataplex-types.global.bigquery-dataset.typedefault自定义 Aspect 类型则为PROJECT_ID[.REGION].ASPECT_TYPE_ID.FIELD_NAME例如example-project.us-central1.employee-info.is-enrolledtrue。实用过滤示例dataplex-types.global.bigquery-table.type{BIGLAKE_TABLE, BIGLAKE_OBJECT_TABLE, EXTERNAL_TABLE, TABLE}dataplex-types.global.storage.type{STRUCTURED, UNSTRUCTURED}6.4 逻辑运算符与缩写语法未显式写运算符时隐含ANDfoo bar表示同时匹配foo与bar支持ORfoo 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:id4column:(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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考