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>}} ...
只有 REST：这三个接口返回的是物理列，走的是调用者自己的数据资源授权，
绕开知识网络的属性级规则，因此已从 MCP 面下线——tools/list、tools/call、
按需网关与沙箱能力面都不提供 run_sql / list_resources / describe_resource。
模型侧要聚合请走 run_cypher，要指标请走 query_metric。
授权：资源可见性与读取权限由下游 vega 按账户强制（空账户直接拒绝），本服务 不做二次放行。
认证：Authorization: Bearer <token>（OAuth access token 或 bak_ AppKey）。
列出当前账户有权查看的数据资源，输出精简字段（够用来挑一个 resource_id）。
请求体可选，不传则按 vega 默认分页返回。
| response_format | string Default: "json" Enum: "json" "toon" 响应格式。 |
object (BKNContext) BKN Trace business-provenance context identifying the business
conversation and interaction to which this call belongs. Required on
MCP business tools and REST execution APIs while capture is enabled
and Trace Core is available;
optional on REST reads and Naming it makes the call managed: the service records an Operation under that interaction and attempts to return a receipt and capture evidence. Omitting it entirely, or sending an empty object, makes an eligible REST read or proxy call ad hoc. Only those two shapes are ad hoc — one id without the other, or a misspelt field, is refused rather than quietly downgraded. Both required child fields are server-issued handles and must not be invented by the caller:
These handles are available only through the provenance MCP tool above.
The BKN Trace Core session APIs under | |
| catalog_id | string 限定某个 catalog。 |
| type | string 资源类别，映射 vega 的 category： |
| offset | integer 分页偏移；不传由 vega 取默认值 0。 |
| limit | integer 分页大小；不传由 vega 取默认值 20。 |
{- "catalog_id": "cat_prod_mysql",
- "type": "table",
- "limit": 50
}{- "entries": [
- {
- "resource_id": "string",
- "name": "string",
- "type": "string",
- "status": "string",
- "catalog_id": "string"
}
], - "total_count": 0
}取单个资源的物理列与连接器类型——写 run_sql 之前该看的东西。
connector_type 决定实际目标方言；run_sql 仅支持 mysql / mariadb /
postgresql / sqlserver 资源，统一接收 MySQL 方言。目标方言不是 MySQL 时由
Vega 转译，MySQL / MariaDB 资源则直接下发；其他连接器（如 opensearch）会被拒绝。
| response_format | string Default: "json" Enum: "json" "toon" 响应格式。 |
object (BKNContext) BKN Trace business-provenance context identifying the business
conversation and interaction to which this call belongs. Required on
MCP business tools and REST execution APIs while capture is enabled
and Trace Core is available;
optional on REST reads and Naming it makes the call managed: the service records an Operation under that interaction and attempts to return a receipt and capture evidence. Omitting it entirely, or sending an empty object, makes an eligible REST read or proxy call ad hoc. Only those two shapes are ad hoc — one id without the other, or a misspelt field, is refused rather than quietly downgraded. Both required child fields are server-issued handles and must not be invented by the caller:
These handles are available only through the provenance MCP tool above.
The BKN Trace Core session APIs under | |
| resource_id required | string 资源 ID。 |
{- "resource_id": "res_orders"
}{- "resource_id": "string",
- "connector_type": "string",
- "columns": [
- {
- "name": "string",
- "type": "string",
- "description": "string"
}
]
}以 MySQL 方言执行只读 SQL。表名不写物理表名，写占位符
{{<resource_id>}}，由服务端解析到真实数据源。
权限：调用者必须对 SQL 引用的每个数据资源都持有 Vega 资源的 view_detail
权限——与其他遵循知识网络授权的查询接口不同，通过对象类获得的授权不覆盖本接口，
仅通过对象类获得授权的调用方应改用 /kn/query_object_instance 或 /kn/run_cypher。
标识符需要引用时使用反引号（如 `order_id`）；双引号在 MySQL 方言下是
字符串字面量，不能用于标识符。
两条硬约束，违反直接 400，SQL 不会下发：
必须引用占位符。SQL 里没有 {{resource_id}} 时报
sql must reference at least one data resource via the {{resource_id}} placeholder
——这既是定位数据源的唯一途径，也挡住了绕开权限直接写物理表名。
必须是单条只读 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 侧统一使用公共 Go Parser 做最终只读策略校验（拒绝非顶层 SELECT、WITH/CTE、集合运算等），两层都不可省。
不分页：固定单次返回，上限 10000 行。要更多数据请在 SQL 里自己收敛 （聚合、加条件、加 LIMIT）。
| response_format | string Default: "json" Enum: "json" "toon" 响应格式。 |
object (BKNContext) BKN Trace business-provenance context identifying the business
conversation and interaction to which this call belongs. Required on
MCP business tools and REST execution APIs while capture is enabled
and Trace Core is available;
optional on REST reads and Naming it makes the call managed: the service records an Operation under that interaction and attempts to return a receipt and capture evidence. Omitting it entirely, or sending an empty object, makes an eligible REST read or proxy call ad hoc. Only those two shapes are ad hoc — one id without the other, or a misspelt field, is refused rather than quietly downgraded. Both required child fields are server-issued handles and must not be invented by the caller:
These handles are available only through the provenance MCP tool above.
The BKN Trace Core session APIs under | |
| sql required | string MySQL 方言 SQL。表名必须写成 |
| query_timeout | integer 查询超时（秒）。不传走下游默认。 |
{- "sql": "SELECT status, count(*) AS cnt FROM {{res_orders}} WHERE created_at >= DATE_SUB(CURRENT_DATE, INTERVAL 7 DAY) GROUP BY status"
}{- "columns": [
- {
- "name": "string",
- "type": "string"
}
], - "entries": [
- { }
], - "total_count": 0,
- "warnings": [
- "string"
], - "paging": {
- "next_cursor": "string",
- "expires_at_sec": 0
}
}