# 管理工作簿与版本

工作簿用于保存 SQL 编辑器中的内容和版本。创建或保存工作簿不会运行 SQL；需要运行时，请把版本中的 SQL 发送到 SQL 运行接口。

## 创建工作簿

```bash
curl -X POST "$PRODUCT_API_BASE_URL/workbook/create" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"name": "<WORKBOOK_NAME>"}'
```

```json
{
  "code": 200,
  "data": {
    "workbook_id": "<WORKBOOK_ID>",
    "name": "<WORKBOOK_NAME>"
  }
}
```

保存 `workbook_id`。工作簿名称用于显示和查找，但后续详情、更新和删除都使用 ID。

## 创建并保存版本

创建版本时提交工作簿 ID 和 SQL 内容：

```bash
curl -X POST "$PRODUCT_API_BASE_URL/workbook/version/create" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "workbook_id": "<WORKBOOK_ID>",
    "sql_content": "SELECT 1 AS n"
  }'
```

成功响应返回版本 ID、版本标识和状态：

```json
{
  "code": 200,
  "data": {
    "id": "<VERSION_ID>",
    "version": "<VERSION>",
    "status": "<STATUS>"
  }
}
```

在草稿阶段使用 `POST /workbook/version/update` 更新内容；需要保存当前版本时，调用 `POST /workbook/version/save`。两者都需要 `workbook_id` 和 `version_id`，更新还需要 `sql_content`。

## 读取工作簿

| 方法与路径 | 关键输入 | 返回内容 |
| --- | --- | --- |
| `POST /workbook/list` | 搜索、页大小和 `page_token` | `total`、`result[]` 和下一页 Token |
| `POST /workbook/version/list` | `workbook_id`、分页字段 | 版本列表和下一页 Token |
| `POST /workbook/detail` | `workbook_id`、`version_id` | SQL 内容和创建、更新时间 |
| `POST /workbook/update` | `workbook_id`、`name` | 更新工作簿名称 |
| `POST /workbook/delete` | `workbook_id` | 删除工作簿 |

覆盖版本前先读取最新内容。Product API 没有把工作簿保存成功定义为 SQL 语义正确；需要验证时，在明确的数据库上下文中运行 SQL。

## 常见问题

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| 找不到工作簿 | 工作区 ID、分页 Token 和搜索条件 | 清除搜索条件并重新列出工作簿。 |
| 详情为空或版本不匹配 | `workbook_id` 和 `version_id` | 先列出版本，再使用同一工作簿下的版本 ID。 |
| 保存后查询结果没有变化 | 是否实际调用了 SQL 运行接口 | 将版本 SQL 发送到 `/query/execute`；保存本身不会运行 SQL。 |
| 协作内容被覆盖 | 更新前读取的版本是否为最新 | 重新读取详情并合并内容后再保存。 |

## 下一步

- [运行工作簿中的 SQL](execute-results.md)
- [浏览数据库元数据](metadata-history.md)