# SQL 与数据看板

使用 `moi-cli sql` 与 `moi-cli dashboard` 浏览库表元数据、执行 SQL 查询并管理工作簿、创建与运行数据看板图表，以及查看工作区任务执行概览。执行前请先完成 [配置与身份认证](../configuration-authentication.md)；工作区已写入本地配置时可省略命令中的 `--workspace-id`。

## 浏览元数据与执行 SQL 查询

运行查询前，可先列出当前工作区可见的数据库、表结构与建表语句：

```bash
moi-cli -auth pat -o sql meta-databases --workspace-id "$WORKSPACE_ID"
moi-cli -auth pat -o sql meta-db-tables --workspace-id "$WORKSPACE_ID" --db-name analytics
moi-cli -auth pat -o sql meta-table-columns --workspace-id "$WORKSPACE_ID" \
  --db-name analytics --table-name daily_sales
```

`moi-cli sql` 提供异步查询链路（`execute-query` → `describe-query` → `query-result`）以及单命令内联返回行数据的 `sql run`（视安装包版本提供，可通过 `moi-cli sql --help` 确认）：

```bash
# 方式一：单命令执行并内联返回列、行、rows_affected 与 truncated
moi-cli -auth pat -o sql run \
  --workspace-id "$WORKSPACE_ID" \
  --db analytics \
  --query 'SELECT * FROM daily_sales LIMIT 20'

# 方式二：异步提交查询 -> 轮询状态取得 statement_id -> 读取结果或导出文件
SUBMIT_JSON="$(moi-cli -auth pat -o sql execute-query \
  --workspace-id "$WORKSPACE_ID" \
  --db-name analytics \
  --query 'SELECT product_id, SUM(amount) AS total FROM daily_sales GROUP BY product_id')"

export QUERY_ID="$(printf '%s' "$SUBMIT_JSON" | jq -r '.query_id')"

DESC_JSON="$(moi-cli -auth pat -o sql describe-query \
  --workspace-id "$WORKSPACE_ID" \
  --query-id "$QUERY_ID")"

export STATEMENT_ID="$(printf '%s' "$DESC_JSON" | jq -r '.statement_id // empty')"

moi-cli -auth pat -o sql query-result \
  --workspace-id "$WORKSPACE_ID" \
  --statement-id "$STATEMENT_ID" \
  --limit 100 --offset 0
```

`sql` 命令组常用子命令与关键标识对应关系如下：

| 场景 | 子命令 | 关键参数与说明 |
| --- | --- | --- |
| 异步提交、轮询与取消 | `execute-query`（别名 `execute`）、`describe-query`（别名 `describe`）、`kill-query`（别名 `kill`） | `execute-query` 返回 `query_id`；`describe-query` 与 `kill-query` 接收 `--query-id`，查询成功后从 `describe-query` 响应提取 `statement_id`。 |
| 读取结果、详情与执行画像 | `query-result`（别名 `result`）、`download-query-result`、`query-detail`、`query-profile` | 统一接收 `--statement-id "$STATEMENT_ID"`（不可传入 `query_id`）；`download-query-result` 通过 `--output result.csv` 保存结果文件。 |
| 查看查询历史 | `query-history-overview`、`query-history`（别名 `history`） | 支持按时间范围、`--status`、`--databases`、`--users`、`--min-duration` 等条件检索历史语句。 |
| 浏览与删除元数据 | `meta-databases`、`meta-db-tree`、`meta-db-tables`（别名 `meta-tables`）、`meta-table-info`、`meta-table-columns`、`meta-table-column-stats`、`meta-table-ddl`、`drop-meta-database`、`drop-meta-table`、`drop-meta-view` | 查看库表列统计与 DDL；`drop-meta-*` 会直接删除目标库、表或视图，执行前请核对 `--db-name`、`--table-name` 与下游依赖。 |
| WebSocket 地址与连接探测 | `query-web-socket-url`、`connect-query-web-socket` | `query-web-socket-url` 仅返回连接地址而不建立连接；`connect-query-web-socket` 验证连接握手而不提供交互式 SQL 终端。 |

:::{warning}
`sql execute-query` 进程退出码为 `0` 仅代表查询请求已成功提交。SQL 语法错误、权限拒绝或执行期异常记录在查询状态中，必须检查 `describe-query` 返回的 `status` 与错误信息后再读取 `query-result`。此外，每次 CLI 命令调用均使用独立数据库连接，不支持跨多次 CLI 命令维护 `BEGIN` / `COMMIT` 事务。
:::

## 管理 SQL 工作簿与版本

使用 `sql` 的工作簿子命令维护保存的 SQL 脚本草稿与历史版本：

```bash
# 分页检索工作簿并查看详情与版本列表
moi-cli -auth pat -o sql workbooks --workspace-id "$WORKSPACE_ID" --search "销售" --page-size 20
moi-cli -auth pat -o sql workbook-detail --workspace-id "$WORKSPACE_ID" --workbook-id "$WORKBOOK_ID"
moi-cli -auth pat -o sql workbook-versions --workspace-id "$WORKSPACE_ID" --workbook-id "$WORKBOOK_ID"
```

| 操作 | 子命令 | 说明 |
| --- | --- | --- |
| 创建、重命名与删除工作簿 | `create-workbook --name <name>`、`update-workbook --workbook-id <id> --name <name>`、`delete-workbook --workbook-id <id>` | 创建新工作簿、更新工作簿名称或删除不再使用的工作簿。 |
| 创建、更新与保存工作簿版本 | `create-workbook-version`、`update-workbook-version`、`save-workbook-version` | 按子命令 `--help` 传入 `--workbook-id`、`--version-id` 及脚本内容，避免将多行复杂 SQL 直接裸拼在未转义的 shell 参数中。 |

(cli-data-dashboards)=

## 创建数据看板与查询图表

创建数据看板前，先从 Catalog 检索可用数据表的正整数 `table_id`（更多目录与表查询见 [数据目录、卷与共享](catalog-files.md)），并通过 `moi-cli schema` 查看请求体结构：

```bash
moi-cli -auth pat -o catalog search-data-dashboard-tables \
  --workspace-id "$WORKSPACE_ID" \
  --search "daily_sales"

moi-cli schema dashboard create
moi-cli -auth pat -o dashboard list --workspace-id "$WORKSPACE_ID" --json '{}'
```

将看板名称与来源表 ID 保存为 `dashboard.json`（跨库看板需确保当前身份对每个来源表均具备访问权限）：

```json
{
  "name": "销售分析",
  "sources": [
    {
      "table_id": 123
    },
    {
      "table_id": 456
    }
  ]
}
```

创建看板并保存返回的 `DASHBOARD_ID`：

```bash
DASHBOARD_JSON="$(moi-cli -auth pat -o dashboard create \
  --workspace-id "$WORKSPACE_ID" \
  --json-file dashboard.json)"

export DASHBOARD_ID="$(printf '%s' "$DASHBOARD_JSON" | jq -r '.id')"
```

### 生成和预览图表 SQL

使用 `generate-sql` 根据自然语言问题生成 SQL 草稿，核对限定表名与过滤口径后再通过 `preview-sql` 试运行验证：

```bash
# 生成 SQL 草稿（仅返回草稿文本，不会自动执行查询）
DRAFT_JSON="$(moi-cli -auth pat -o dashboard generate-sql \
  --workspace-id "$WORKSPACE_ID" \
  --dashboard-id "$DASHBOARD_ID" \
  --question '按产品统计本月销售额')"

export SQL_TEXT="$(printf '%s' "$DRAFT_JSON" | jq -r '.sql_text')"

# 预览 SQL 执行结果
moi-cli -auth pat -o dashboard preview-sql \
  --workspace-id "$WORKSPACE_ID" \
  --dashboard-id "$DASHBOARD_ID" \
  --sql-text "$SQL_TEXT"
```

### 创建图表、刷新运行与读取结果

图表配置中的 `chart_config` 与 `layout_config` 为编码后的 JSON 字符串，可通过 `moi-cli schema` 查看各图表类型的序列化字段：

```bash
moi-cli schema dashboard create-chart
moi-cli schema dashboard create-chart --argument json.chart_config
moi-cli schema dashboard create-chart --argument json.layout_config
```

准备 `chart.json`：

```json
{
  "name": "销售明细",
  "chart_type": "table",
  "sql_text": "SELECT * FROM analytics.daily_sales LIMIT 10",
  "chart_config": "{}",
  "layout_config": "{}",
  "refresh_interval": "manual",
  "alert_enabled": false
}
```

创建图表、触发查询并读取或下载结果：

```bash
CHART_JSON="$(moi-cli -auth pat -o dashboard create-chart \
  --workspace-id "$WORKSPACE_ID" \
  --dashboard-id "$DASHBOARD_ID" \
  --json-file chart.json)"

export CHART_ID="$(printf '%s' "$CHART_JSON" | jq -r '.id')"

# 运行单个图表（刷新整张看板全部图表可使用 dashboard refresh）
moi-cli -auth pat -o dashboard run-chart \
  --workspace-id "$WORKSPACE_ID" \
  --dashboard-id "$DASHBOARD_ID" \
  --chart-id "$CHART_ID"

# 读取最新图表结果或导出文件
moi-cli -auth pat -o dashboard chart-result \
  --workspace-id "$WORKSPACE_ID" \
  --dashboard-id "$DASHBOARD_ID" \
  --chart-id "$CHART_ID"

moi-cli -auth pat -o dashboard download-chart-result \
  --workspace-id "$WORKSPACE_ID" \
  --dashboard-id "$DASHBOARD_ID" \
  --chart-id "$CHART_ID" \
  --output chart-result.csv
```

看板与图表维护还支持 `get`、`update`、`delete`、`update-chart`、`update-chart-order`、`delete-chart`、`drill-through` 和 `download-drill-through`（通过 `moi-cli dashboard <subcommand> --help` 查看选项）。

:::{warning}
`dashboard update` 会整体替换看板元数据：请求体中省略 `description` 会清空原有看板描述；移除仍被图表引用的来源表会报错 `DATA_DASHBOARD_SOURCE_IN_USE`。调用 `update-chart-order` 时须传入看板下全部图表的完整 `chart_ids` 排列。
:::

(cli-task-execution-overview)=

## 查看工作区任务执行概览

使用 `dashboard task-execution-overview` 读取当前工作区近期后台任务的汇总计数：

```bash
moi-cli -auth pat -o dashboard task-execution-overview --workspace-id "$WORKSPACE_ID"
```

输出包含统计时间窗口及运行中、成功、失败、待执行和总计任务数量（JSON 输出中零值计数字段可能省略）。该命令仅返回工作区级汇总指标；需排查具体失败任务时，请分别通过 `workflow`、`connector` 或 `agent` 命令组列出对应任务并读取执行详情。

## 限制和注意事项

- 写入、更新、删除语句及 `drop-meta-*` 命令会直接作用于目标工作区的数据表与元数据，执行前请确认目标数据库与角色权限。
- `dashboard run-chart` 与 `dashboard refresh` 返回受理结果后，图表查询仍在后台执行；若 `chart-result` 尚未就绪，使用原 `DASHBOARD_ID` 和 `CHART_ID` 有限次重查，无需重复创建图表。
- 读取历史时间点的图表快照时，可在 `dashboard chart-result` 中附加 `--query-param 'at=<RFC3339Nano时间戳>'`。
