概述

/api/v1/search/glob
按路径模式查找文件和目录，不检索文件正文。适合按扩展名、目录结构或已知文件名定位内容。

前置条件

完成 "数据库访问使用说明" 页面的 API Key 获取后，可调用本接口执行文件模式匹配。

请求接口

URI	/api/v1/search/glob	统一资源标识符
请求方法	POST	客户端对服务器请求的操作类型
请求头	Content-Type: application/json	请求消息类型
请求头	Authorization: Bearer {api_key}	API Key 鉴权

请求参数

参数	类型	必填／默认值	说明
pattern	string	是	路径模式，通常相对于 uri。`.md` 匹配一层的 Markdown 文件，`/.md` 用于递归匹配，`?` 匹配单个字符。不是正则表达式。
uri	string	否，viking://	搜索起点。建议显式指定业务目录，便于控制范围和查询成本。
node_limit	integer	否，256	返回条目数量上限，包含匹配到的文件和目录。建议使用正整数。
extra_fields	string[]	否	不传时通常返回 URI 字符串；显式传 [] 或字段列表时返回条目对象。用于请求附加元信息，不应理解为严格的响应字段投影。
tags	string[]	否	按全部有效标签精确过滤；传入有效标签后 matches 返回对象，包含 tags。
include_tags	boolean	否，false	true 时返回包含 tags 的条目对象。要读取标签请使用本参数，不要只依赖 extra_fields=["tags"]。

extra_fields 可按需请求 size、mtime、mode 等元信息；文件系统与索引路径能提供的字段可能不同。uri、name、isDir 等基础信息可随条目对象返回。部分元信息需要额外查询，批量查找时仅请求需要的字段。

响应消息

字段	类型	说明
result.matches	string[] 或 object[]	未请求附加字段和标签时为 URI 数组；请求条目信息或标签时为对象数组。
result.count	integer	当前实际返回的条目数，不是目录中所有匹配对象的总数。
对象.uri	string	文件或目录 URI。
对象.isDir	boolean	若提供，true 表示目录。
对象.name	string	若提供，文件或目录名。
对象.tags	string[]	请求标签输出时提供。
其他元信息	按字段而定	按请求及后端能力返回，调用方应允许缺省。

常见错误码

error.code	说明
UNAUTHENTICATED	缺少 API Key 或 API Key 无效
PERMISSION_DENIED	API Key 权限不足
INVALID_ARGUMENT	`pattern` 非法
NOT_FOUND	指定 `uri` 不存在

完整示例

示例1：返回 URI 列表

递归查找项目目录中的 Markdown 文件，不请求附加字段。
请求：

curl --request POST \
  'https://api.vikingdb.cn-beijing.volces.com/openviking/api/v1/search/glob' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {api_key}' \
  --data '{
  "pattern": "**/*.md",
  "uri": "viking://resources/projects/atlas",
  "node_limit": 100
}'

返回（HTTP 200，结构示例）：

{
  "status": "ok",
  "result": {
    "matches": [
      "viking://resources/projects/atlas/release.md",
      "viking://resources/projects/atlas/login.md"
    ],
    "count": 2
  }
}

示例2：返回文件信息和标签

请求大小、修改时间及标签。matches 因此返回条目对象；修改时间在此示例中使用后端原始字段 modTime。
请求：

curl --request POST \
  'https://api.vikingdb.cn-beijing.volces.com/openviking/api/v1/search/glob' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {api_key}' \
  --data '{
  "pattern": "**/*.md",
  "uri": "viking://resources/projects/atlas",
  "extra_fields": [
    "size",
    "mtime"
  ],
  "include_tags": true,
  "node_limit": 100
}'

返回（HTTP 200，结构示例）：

{
  "status": "ok",
  "result": {
    "matches": [
      {
        "uri": "viking://resources/projects/atlas/release.md",
        "name": "release.md",
        "isDir": false,
        "size": 428,
        "mode": 420,
        "modTime": "2026-09-20T08:30:00.000Z",
        "tags": [
          "project=atlas"
        ]
      }
    ],
    "count": 1
  }
}

参数、示例与排错补充

可选参数缺少默认行为：node_limit 不传时使用服务默认上限 1000，避免无界遍历。
数值边界限制缺失：node_limit 取值范围为 [1, 1000]。
返回参数描述不完整：返回结构采用统一包装：status 为 string，result 为 object/array/null，telemetry 为 object/null，error 为 object/null；业务子字段的类型和层级与成功示例保持一致。
错误码原因或处理建议缺失：错误处理建议：UNAUTHENTICATED：检查并重新生成 API Key；PERMISSION_DENIED：确认 Agent/账号对目标 URI 有权限；INVALID_ARGUMENT：按参数表检查类型、范围和必填项；NOT_FOUND：确认 URI 或资源 ID 存在；INTERNAL：记录 request ID 后重试，持续失败时提交工单。

最近更新时间：2026.09.22 22:12:21

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

概述 #

前置条件 #

请求接口 #

请求参数 #

响应消息 #

常见错误码 #

完整示例 #

示例1：返回 URI 列表 #

示例2：返回文件信息和标签 #

参数、示例与排错补充 #

概述