# 管理 SQL 工作簿和数据看板

保存 SQL、维护草稿和定稿版本，并创建、运行、更新、刷新和删除数据看板及图表。本页不直接执行任意 SQL；需要执行和检查 SQL 结果时，请参阅[执行 SQL 和管理 SQL 元数据](sql-execution-metadata.md)。

## 前提条件

准备可访问目标工作区的凭据，以及用于保存、图表或看板操作的已有对象标识。有关服务地址、认证和通用请求格式，请参阅[调用前准备](../../api-call-basics.md)。

修改、定稿、删除、运行或更新前，先从 SQL 保存记录、版本或数据看板列表、详情中取得目标标识。

## 调用顺序

1. 查询已保存 SQL 和版本，确定是创建保存记录、创建草稿还是修改已有版本。
2. 需要固定版本时定稿，并通过版本内容确认目标版本。
3. 创建数据看板后创建或更新图表；需要根据自然语言生成图表 SQL 时，先生成 SQL 草稿；运行或刷新图表前，可先预览图表 SQL。
4. 查询图表结果或下载结果，确认图表输出；不再需要的图表、看板或 SQL 保存记录再删除。

## API 操作

### 保存 SQL 和管理版本

| 要完成的事 | API 操作 | 何时使用 |
| --- | --- | --- |
| 查看已保存的 SQL | [查看 SQL 工作簿列表](../../../../reference/api/ai-studio/data-processing/sql-workbooks/list-workbooks.md) | 查找 SQL 保存记录或取得目标标识时使用。 |
| 创建 SQL 保存记录 | [创建 SQL 工作簿](../../../../reference/api/ai-studio/data-processing/sql-workbooks/create-workbook.md) | 需要新增 SQL 保存记录时使用。 |
| 修改 SQL 保存记录名称 | [更新 SQL 工作簿名称](../../../../reference/api/ai-studio/data-processing/sql-workbooks/update-workbook.md) | 需要调整保存记录名称时使用。 |
| 删除 SQL 保存记录 | [删除 SQL 工作簿](../../../../reference/api/ai-studio/data-processing/sql-workbooks/delete-workbook.md) | 确认不再需要保存记录后使用。 |
| 查看已保存 SQL 的版本 | [查看 SQL 工作簿版本列表](../../../../reference/api/ai-studio/data-processing/sql-workbooks/list-workbook-versions.md) | 查找已有版本或取得版本标识时使用。 |
| 查看已保存 SQL 的版本内容 | [查看 SQL 工作簿版本内容](../../../../reference/api/ai-studio/data-processing/sql-workbooks/get-workbook.md) | 检查指定版本内容时使用。 |
| 创建 SQL 草稿版本 | [创建 SQL 草稿版本](../../../../reference/api/ai-studio/data-processing/sql-workbooks/create-workbook-draft.md) | 需要新增草稿版本时使用。 |
| 修改 SQL 草稿版本 | [更新 SQL 草稿版本](../../../../reference/api/ai-studio/data-processing/sql-workbooks/update-workbook-draft.md) | 需要调整草稿内容时使用。 |
| 定稿 SQL 版本 | [定稿 SQL 版本](../../../../reference/api/ai-studio/data-processing/sql-workbooks/finalize-workbook-version.md) | 需要将目标版本定稿时使用。 |

### 管理数据看板和图表

| 要完成的事 | API 操作 | 何时使用 |
| --- | --- | --- |
| 查询数据看板列表 | [查看数据看板列表](../../../../reference/api/ai-studio/data-processing/data-dashboards/list-data-dashboards.md) | 查找看板或取得目标标识时使用。 |
| 创建数据看板 | [创建数据看板](../../../../reference/api/ai-studio/data-processing/data-dashboards/create-data-dashboard.md) | 需要新增数据看板时使用。 |
| 查询数据看板详情 | [查看数据看板详情](../../../../reference/api/ai-studio/data-processing/data-dashboards/get-data-dashboard.md) | 检查单个看板当前信息时使用。 |
| 更新数据看板 | [更新数据看板](../../../../reference/api/ai-studio/data-processing/data-dashboards/update-data-dashboard.md) | 需要调整已有看板时使用。 |
| 删除数据看板 | [删除数据看板](../../../../reference/api/ai-studio/data-processing/data-dashboards/delete-data-dashboard.md) | 确认不再需要看板后使用。 |
| 创建图表 | [创建看板图表](../../../../reference/api/ai-studio/data-processing/data-dashboards/create-data-dashboard-chart.md) | 已确定目标看板后新增图表时使用。 |
| 更新图表 | [更新看板图表](../../../../reference/api/ai-studio/data-processing/data-dashboards/update-data-dashboard-chart.md) | 需要调整已有图表时使用。 |
| 删除图表 | [删除看板图表](../../../../reference/api/ai-studio/data-processing/data-dashboards/delete-data-dashboard-chart.md) | 确认不再需要图表后使用。 |
| 生成图表 SQL 草稿 | [生成看板图表 SQL 草稿](../../../../reference/api/ai-studio/data-processing/data-dashboards/generate-data-dashboard-chart-sql.md) | 需要根据自然语言问题生成并校验只读 SQL 草稿时使用。 |
| 预览图表 SQL | [预览看板图表 SQL](../../../../reference/api/ai-studio/data-processing/data-dashboards/preview-data-dashboard-chart-sql.md) | 运行前检查图表 SQL 时使用。 |
| 运行图表 | [运行看板图表](../../../../reference/api/ai-studio/data-processing/data-dashboards/run-data-dashboard-chart.md) | 需要运行单个图表时使用。 |
| 刷新全部图表 | [刷新全部看板图表](../../../../reference/api/ai-studio/data-processing/data-dashboards/refresh-all-data-dashboard-charts.md) | 需要刷新看板中全部图表时使用。 |
| 查询图表结果 | [查看看板图表结果](../../../../reference/api/ai-studio/data-processing/data-dashboards/get-data-dashboard-chart-result.md) | 检查图表输出时使用。 |
| 下载图表结果 | [下载看板图表结果](../../../../reference/api/ai-studio/data-processing/data-dashboards/download-data-dashboard-chart-result.md) | 需要取得图表结果时使用。 |

## 结果确认

创建、修改或定稿 SQL 后，查询保存记录、版本列表和版本内容确认目标版本。创建、更新、运行或刷新看板后，使用[查看数据看板详情](../../../../reference/api/ai-studio/data-processing/data-dashboards/get-data-dashboard.md)确认看板信息，并通过[查看看板图表结果](../../../../reference/api/ai-studio/data-processing/data-dashboards/get-data-dashboard-chart-result.md)检查图表输出。

## 限制和注意事项

- SQL 保存记录、草稿版本、定稿版本、数据看板和图表是不同对象；调用前先确认所持有的对象标识。
- 运行或刷新图表不等同于结果已可读取；以图表结果查询为准。
- 删除保存记录、看板或图表前，先确认影响范围。

## 下一步

- [执行 SQL 和管理 SQL 元数据](sql-execution-metadata.md)