概述

/api/v1/search/grep 接口用于基于模式在指定 URI 范围内搜索内容。按正则表达式匹配指定文件或目录中的文本，返回命中行及其位置。适合查找错误码、函数名、配置项等明确文本。前置条件
完成 "数据库访问使用说明" 页面的 API Key 获取后，可调用本接口执行模式搜索。

请求接口

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

请求参数

参数	类型	必填／默认值	说明
uri	string	是	搜索起点，可为文件 URI 或目录 URI。API 不提供默认值。
pattern	string	是	正则表达式。JSON 中反斜杠须转义，例如匹配字面量点写为 \.。复杂正则的兼容性取决于服务端检索引擎。
case_insensitive	boolean	否，false	true 忽略大小写。
exclude_uri	string	否	排除一个文件或目录范围，不接受数组。
node_limit	integer	否，256	最多返回的命中行数，不是最多扫描的文件数。建议使用正整数。
level_limit	integer	否，10	目录递归深度上限，不是记忆 L0/L1/L2 层级。
tags	string[]	否	只搜索满足全部有效标签条件的文件。格式 key=value；标签过滤依赖索引。
include_tags	boolean	否，false	为命中项附带 tags；提供有效 tags 过滤时也会附带标签。

当前 grep/glob 会忽略不合法的标签项；如果所有标签均不合法，可能不再按标签过滤。调用前须校验标签格式，不能依赖服务端必然报错。多个有效标签按 AND 合并，标签大小写和重复 key 规则同 find。

响应消息

字段	类型	说明
result.matches	object[]	命中行数组。
matches[].uri	string	命中文件的 URI。
matches[].line	integer	行号。
matches[].content	string	命中行的文本。
matches[].tags	string[]	请求标签输出时提供。
result.count	integer	实际返回的命中行数。
result.match_count	integer	当前结果的匹配计数，不表示未截断的全范围总数。
result.files_scanned	integer	引擎返回的文件统计，不同检索路径的统计口径可能不同，不应用于推断扫描覆盖率。

常见错误码

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

完整示例

示例1：搜索错误关键词

curl --request POST \
  'https://api.vikingdb.cn-beijing.volces.com/openviking/api/v1/search/grep' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {api_key}' \
  --data '{
  "uri": "viking://resources/projects/atlas",
  "pattern": "timeout|deadline",
  "case_insensitive": true,
  "node_limit": 50,
  "level_limit": 10,
  "include_tags": true
}'

执行成功返回：

{
  "status": "ok",
  "result": {
    "matches": [
      {
        "uri": "viking://resources/projects/atlas/config.md",
        "line": 12,
        "content": "request_timeout = 30",
        "tags": [
          "project=atlas",
          "stage=production"
        ]
      }
    ],
    "count": 1,
    "match_count": 1,
    "files_scanned": 1
  }
}

示例2：按标签过滤并排除归档目录

只查找带 stage=production 标签的文件，并排除 archive 目录。node_limit 控制返回的命中行数。
请求：

curl --request POST \
  'https://api.vikingdb.cn-beijing.volces.com/openviking/api/v1/search/grep' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {api_key}' \
  --data '{
  "uri": "viking://resources/projects/atlas",
  "pattern": "ERROR",
  "exclude_uri": "viking://resources/projects/atlas/archive",
  "tags": [
    "stage=production"
  ],
  "include_tags": true,
  "node_limit": 50,
  "level_limit": 10
}'

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

{
  "status": "ok",
  "result": {
    "matches": [
      {
        "uri": "viking://resources/projects/atlas/troubleshooting.md",
        "line": 18,
        "content": "ERROR AUTH_TIMEOUT：先检查身份服务响应时间。",
        "tags": [
          "project=atlas",
          "stage=production"
        ]
      }
    ],
    "count": 1,
    "match_count": 1,
    "files_scanned": 1
  }
}

参数、示例与排错补充

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

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

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

概述 #

请求接口 #

请求参数 #

响应消息 #

常见错误码 #

完整示例 #

示例1：搜索错误关键词 #

示例2：按标签过滤并排除归档目录 #

参数、示例与排错补充 #

概述