# 创建和使用数据看板

数据看板使用所选 Catalog 表生成和执行 SQL，并以图表展示结果。数据来源可以位于不同目录、不同数据库；执行 SQL 仍受实际表访问权限约束。

## 创建看板并选择来源

1. 打开数据看板，创建看板并填写便于识别的名称。
2. 在数据源选择中进入相应目录和数据库，选择需要分析的表。
3. 需要跨库分析时，继续选择其他目录或数据库中的表，检查最终来源列表。
4. 保存后重新打开看板，确认所选来源正确。

例如，可从销售数据库选择订单表，从商品数据库选择产品表，用于按产品统计销售额。先核对两张表的关联字段、金额单位和统计时间，再生成图表。

## 添加图表并检查 SQL

1. 在看板中添加图表，用自然语言描述问题，例如“按产品统计本月销售额”。
2. 生成 SQL 后，检查引用的表是否属于所选来源，过滤条件、关联字段和聚合口径是否符合要求。
3. 预览 SQL，核对返回列和少量结果。生成 SQL 草稿与实际执行是两个步骤。
4. 检查图表所使用的数据列和展示方式，保存图表。
5. 提交运行，等待结果，再与源数据核对。

跨数据库引用时，应核对完整的库表名称，避免同名表造成混淆。看板的访问权限不代替底层 SQL 和表权限。

## 刷新与维护

源数据变化后，使用看板提供的刷新操作更新图表。提交刷新并不代表所有图表已经完成；检查各图表的加载、结果或错误状态。

修改数据源后，检查依赖该来源的 SQL 和图表。原表不可访问、字段变化或被删除时，应先修正来源和 SQL，再重新运行。删除图表或看板前，确认对象和影响范围。

## 查看结果、明细下探与导出

针对单个图表卡片，可执行以下分析与导出动作：

- **查看执行结果与导出 CSV**：在图表操作菜单选择**查看执行结果**，可查看底层 SQL 返回行并点击**导出 CSV** 下载结果表。
- **明细数据下探**：点击图表中对应维度或数据点，打开**明细数据**抽屉查看对应明细行与**明细 SQL**。明细查询严格遵循你当前的 Effective Role 行列权限；点击**导出当前明细**可下载可见明细，或点击**在 SQL 编辑器中打开**将明细 SQL 带入 [SQL 编辑器](sql-editor.md) 继续分析。

## 查看历史快照

在看板详情顶部找到**查看时间**控制器（默认处于**当前**实时视图）：

1. 在预设下拉中选择 `1天`、`7天`、`15天`、`30天`、`3个月`、`6个月` 或 `一年`，或选择**自定义**指定历史时间点。
2. 若该时间点存在可用快照，图表会切换到对应快照视图；若提示“该时间点没有可用快照”，请改选其他时间或切回**当前**。
3. **历史快照暂不支持明细下探**；需要下探明细时请先切换回**当前**视图。

## 配置数据告警与查看记录

**指标卡**、**折线图**、**柱状图**和**面积图**支持在看板内配置图表级数据告警（其余图表类型暂不支持）：

1. 在新建或**修改**图表时开启**启用数据告警**。
2. 选择**判断数据**字段、**运算符**与**阈值**。
3. 选择**告警级别**（**严重**、**警告**、**提醒**）及**告警间隔**（**实时**、**每 15 分钟**、**每 1 小时**、**每 6 小时**或**每 24 小时**）后保存。
4. 在看板顶部点击**告警记录**，可查看触发过的图表、触发条件、数据点、级别、状态（**告警中** / **已恢复**）与发生时间。

## 常见问题

| 现象 | 检查方式 |
| --- | --- |
| 首张图表一直加载 | 检查本次运行状态和错误，刷新页面后确认是否已有图表，避免重复创建。 |
| SQL 无法预览 | 检查库表限定名、所选来源、字段和访问权限；保留页面给出的错误。 |
| 图表没有数据 | 先用相同条件检查 SQL 结果，再检查图表列和时间过滤。 |
| 刷新失败 | 检查来源是否仍可用，以及 SQL 是否仍符合当前表结构。 |

## API、SDK 和 CLI

- [管理 SQL 工作簿和数据看板](../../../developer/api/ai-studio/data-processing/sql-workbooks-dashboards.md)：HTTP 接口的创建、运行和结果流程。
- SDK [管理数据看板与图表](../../../developer/sdk/ai-studio/数据处理/管理数据看板和图表.md)：通过 Go 或 Python 管理看板。
- CLI [SQL 与数据看板](../../../developer/cli/tasks/sql-dashboards.md#cli-data-dashboards)：创建看板、运行图表并查询结果。
