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

使用元数据接口选择数据库和表，并通过 SQL 历史定位 SQL 执行详情与 Profile。本页中的数据库和表使用名称标识；需要数据目录（Catalog）资源 ID 时，请改用[数据库与表](../data-files-connectors/databases-tables.md)页面中的接口。

## 浏览数据库对象

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

```bash
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`，再列出其中的表和视图：

```bash
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 执行记录。

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

```bash
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 无自动恢复；按数据库备份和恢复流程处理。 |

## 下一步

- [运行 SQL 并读取结果](execute-results.md)
- [管理数据目录中的数据库与表](../data-files-connectors/databases-tables.md)