浏览数据库元数据与 SQL 历史¶

使用元数据接口选择数据库和表，并通过 SQL 历史定位 SQL 执行详情与 Profile。本页中的数据库和表使用名称标识；需要数据目录（Catalog）资源 ID 时，请改用数据库与表页面中的接口。

浏览数据库对象¶

列出当前角色可见的数据库：

curl -X POST "$PRODUCT_API_BASE_URL/meta/db/info" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Accept: application/json"

成功响应的 data.result[] 包含 db_name、所有者、是否为系统库或订阅库等信息。保存要使用的 db_name，再列出其中的表和视图：

curl -X POST "$PRODUCT_API_BASE_URL/meta/db/table" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"name": "<DATABASE_NAME>"}'

方法与路径	用途	请求体
`POST /meta/db/tree`	读取数据库树	无
`POST /meta/db/table`	列出数据库中的表和视图	`name`
`POST /meta/table/info`	读取表信息和列	`db_name`、`table_name`
`POST /meta/table/column`	读取列定义	`db_name`、`table_name`
`POST /meta/table/column_stat`	读取列统计	`db_name`、`table_name`
`POST /meta/table/ddl`	读取建表 DDL	`db_name`、`table_name`

元数据结果反映当前角色在请求时可见的对象。列表中没有某个对象时，先检查角色和数据库权限，不要直接把对象不存在写入业务判断。

SQL 历史¶

POST /query/history/overview 返回时间范围内的总数、成功数、运行数和失败数。POST /query/history 分页返回 SQL 执行记录。

下面的请求读取一页历史；空请求体表示不主动增加筛选条件：

curl -X POST "$PRODUCT_API_BASE_URL/query/history" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "offset": 0,
    "limit": 20
  }'

响应中的 data.query_list[] 包含 statement_id、数据库、Statement、状态、错误、耗时和扫描量等当前可用信息。SQL 文本可能包含敏感数据，展示和日志记录前应脱敏。

可用筛选包括状态、用户、数据库、Statement 文本、查询类型、时间范围以及 Statement、事务和 Session ID。只使用当前调用场景需要的筛选，不要把示例时间格式当作固定契约。

读取详情和 Profile¶

从历史或 Describe 响应中取得 statement_id 后，可以调用：

方法与路径	用途
`POST /query/detail`	读取执行时间、状态、错误、扫描量和 SQL 来源等详情
`POST /query/profile`	读取执行计划图、步骤、统计和成本信息

这两个接口的请求体都包含 statement_id，并可按当前契约增加开始和结束时间。Profile 仅在服务端已经记录相应执行信息时返回完整内容。

删除数据库对象¶

POST /meta/db/drop、POST /meta/table/drop 和 POST /meta/view/drop 是破坏性接口。提交前显示完整数据库名和对象名，检查当前角色、依赖和备份。请求成功不提供 Product API 级别的恢复操作。

常见问题¶

现象	先检查	下一步
元数据中没有目标表	当前角色、数据库名和对象权限	切换到有权限的角色后重新读取元数据。
历史列表为空	时间、状态、用户和来源筛选	清除筛选并扩大时间范围后重试。
Profile 不完整	Statement 状态和 `statement_id`	先读取查询详情，确认 SQL 执行记录已经可用。
删除了错误对象	完整限定名和当前数据库上下文	Product API 无自动恢复；按数据库备份和恢复流程处理。

下一步¶

最后更新于 2026 年 8 月 14 日