API docs by Redocly

数据层直查 (0.1.3)

Download OpenAPI specification:

脱离本体、直接查底层数据资源的三个接口：列资源、看资源结构、跑只读 SQL。

与本体路径（schema-search.yaml → object-instance.yaml）互补：本体路径回答「这张网里 业务概念长什么样」，数据层直查回答「底下的表里到底有什么」。两条路都通向 run_sql——要么从 search_schema 拿对象类的物理列名（include_columns=true）， 要么从 list_resources + describe_resource 拿资源的物理 schema。

典型链路：

list_resources    → 找到 resource_id
describe_resource → 看有哪些列、什么类型、什么连接器
run_sql           → SELECT ... FROM {{.<resource_id>}} ...

授权：资源可见性与读取权限由下游 vega 按账户强制（空账户直接拒绝），本服务 不做二次放行。

认证：Authorization: Bearer <token>（OAuth access token 或 bak_ AppKey）。

DataAccess

列出可查询的数据资源

列出当前账户有权查看的数据资源，输出精简字段（够用来挑一个 resource_id）。 请求体可选，不传则按 vega 默认分页返回。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

Request Body schema: application/json
optional
required
object (BKNContext)

BKN Trace 业务溯源上下文，声明这次调用属于哪一轮业务对话。REST 面必填。

两个必填子字段均为服务端签发的句柄、不可自拟：

  • conversation_id：首轮调用 Context Loader MCP 工具 bkn_start_interaction 取得
  • interaction_id：调用 Context Loader 的 MCP 工具 bkn_start_interaction 取得

这两个句柄只能经上述 MCP 溯源工具取得。BKN Trace Core 的 /api/agent-observability/v1 会话接口只接受集群内可信服务的网关凭据， 不接受 OAuth token 或 bak_ AppKey，外部调用方直接调用会得到 401 permission_denied。 Context Loader 按请求关联信息、工具名和规范化输入服务端派生 Operation 幂等标识；调用方不得提交 operation_key。网络重试应复用 bkn-request-id，或提供同一次逻辑调用稳定不变的 X-OpenBKN-Client-Invocation-Id 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

catalog_id
string

限定某个 catalog。

type
string

资源类别，映射 vega 的 category：table / file / fileset / api / metric / topic / index / logicview / dataset。

offset
integer

分页偏移；不传由 vega 取默认值 0。

limit
integer

分页大小；不传由 vega 取默认值 20。

Responses

Request samples

Content type
application/json
{
  • "catalog_id": "cat_prod_mysql",
  • "type": "table",
  • "limit": 50
}

Response samples

Content type
{
  • "entries": [
    ],
  • "total_count": 0
}

查看资源的物理结构

取单个资源的物理列与连接器类型——写 run_sql 之前该看的东西。 connector_type 决定实际目标方言；run_sql 仅支持 mysql / mariadb / postgresql / sqlserver 资源，统一接收 MySQL 方言。目标方言不是 MySQL 时由 Vega 转译，MySQL / MariaDB 资源则直接下发；其他连接器（如 opensearch）会被拒绝。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

Request Body schema: application/json
required
required
object (BKNContext)

BKN Trace 业务溯源上下文，声明这次调用属于哪一轮业务对话。REST 面必填。

两个必填子字段均为服务端签发的句柄、不可自拟：

  • conversation_id：首轮调用 Context Loader MCP 工具 bkn_start_interaction 取得
  • interaction_id：调用 Context Loader 的 MCP 工具 bkn_start_interaction 取得

这两个句柄只能经上述 MCP 溯源工具取得。BKN Trace Core 的 /api/agent-observability/v1 会话接口只接受集群内可信服务的网关凭据， 不接受 OAuth token 或 bak_ AppKey，外部调用方直接调用会得到 401 permission_denied。 Context Loader 按请求关联信息、工具名和规范化输入服务端派生 Operation 幂等标识；调用方不得提交 operation_key。网络重试应复用 bkn-request-id，或提供同一次逻辑调用稳定不变的 X-OpenBKN-Client-Invocation-Id 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

resource_id
required
string

资源 ID。

Responses

Request samples

Content type
application/json
{
  • "resource_id": "res_orders"
}

Response samples

Content type
{
  • "resource_id": "string",
  • "connector_type": "string",
  • "columns": [
    ]
}

对数据资源执行只读 SQL

以 MySQL 方言执行只读 SQL。表名不写物理表名，写占位符 {{.<resource_id>}}，由服务端解析到真实数据源。

标识符需要引用时使用反引号（如 `order_id`）；双引号在 MySQL 方言下是 字符串字面量，不能用于标识符。

两条硬约束，违反直接 400，SQL 不会下发：

  1. 必须引用占位符。SQL 里没有 {{.resource_id}} 时报 sql must reference at least one data resource via the {{.resource_id}} placeholder ——这既是定位数据源的唯一途径，也挡住了绕开权限直接写物理表名。

  2. 必须是单条只读 SELECT 语句。端到端兼容性以 vega 的只读策略为准； 虽然本服务的本地守卫可接受以 WITH 开头的语句，但 vega 当前会拒绝 CTE， 因此调用方**不得使用 WITH / CTE 或 UNION / INTERSECT / EXCEPT**。 守卫会先剥掉注释、字符串字面量、反引号标识符与占位符， 再判定：不允许多语句（剥离后仍含 ;）、必须以 SELECT 或 WITH 开头、不得含 写入 / DDL / 权限 / 过程类关键字（INSERT、UPDATE、DELETE、DROP、ALTER、 CREATE、TRUNCATE、GRANT、REVOKE、REPLACE、MERGE、UPSERT、CALL、EXEC、 EXECUTE、RENAME、LOAD、COPY、INTO、ATTACH、DETACH、USE、VACUUM、ANALYZE、 REFRESH、COMMENT、PREPARE、DEALLOCATE）。

    当前保证可用的只读语法为：单表或同一 catalog 内的 JOIN、WHERE、 GROUP BY / HAVING、ORDER BY、LIMIT 及常用聚合函数（如 COUNT、SUM、 AVG、MIN、MAX）。子查询和窗口函数不属于当前兼容性承诺，调用方不得依赖。 SQL Server 资源还要求 SELECT 输出列名唯一；使用 JOIN 时，* 必须带表别名 限定（如 o.*），不能使用裸 *。

    守卫不是完整 SQL 解析器，是纵深防御的一层：vega 侧另有基于 SQLGlot AST 的 只读策略做最终裁决（拒绝非顶层 SELECT、WITH/CTE、集合运算等），两层都不可省。

不分页：固定单次返回，上限 10000 行。要更多数据请在 SQL 里自己收敛 （聚合、加条件、加 LIMIT）。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

Request Body schema: application/json
required
required
object (BKNContext)

BKN Trace 业务溯源上下文，声明这次调用属于哪一轮业务对话。REST 面必填。

两个必填子字段均为服务端签发的句柄、不可自拟：

  • conversation_id：首轮调用 Context Loader MCP 工具 bkn_start_interaction 取得
  • interaction_id：调用 Context Loader 的 MCP 工具 bkn_start_interaction 取得

这两个句柄只能经上述 MCP 溯源工具取得。BKN Trace Core 的 /api/agent-observability/v1 会话接口只接受集群内可信服务的网关凭据， 不接受 OAuth token 或 bak_ AppKey，外部调用方直接调用会得到 401 permission_denied。 Context Loader 按请求关联信息、工具名和规范化输入服务端派生 Operation 幂等标识；调用方不得提交 operation_key。网络重试应复用 bkn-request-id，或提供同一次逻辑调用稳定不变的 X-OpenBKN-Client-Invocation-Id 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

sql
required
string

MySQL 方言 SQL。表名必须写成 {{.<resource_id>}} 占位符， 也接受 {{<resource_id>}} 形式；resource_id 必须匹配 [a-z0-9][a-z0-9_-]{0,39}（小写，最长 40 个字符），否则占位符不会被识别。 标识符需要引用时使用反引号；双引号在 MySQL 方言下是字符串字面量，不能用于 标识符。只允许单条 SELECT（不支持 WITH / CTE）。

query_timeout
integer

查询超时（秒）。不传走下游默认。

Responses

Request samples

Content type
application/json
Example
{
  • "sql": "SELECT status, count(*) AS cnt FROM {{.res_orders}} WHERE created_at >= DATE_SUB(CURRENT_DATE, INTERVAL 7 DAY) GROUP BY status"
}

Response samples

Content type
{
  • "columns": [
    ],
  • "entries": [
    ],
  • "total_count": 0,
  • "warnings": [
    ],
  • "paging": {
    }
}