# 生成看板图表 SQL 草稿

根据自然语言问题生成当前数据看板可用的只读 SQL 草稿和建议图表类型。接口只生成并校验草稿，不执行 SQL，也不创建看板图表。

```text
POST https://moi.matrixorigin.cn/newmoi/data-dashboards/{dashboard_id}/generate-sql
```

## 调用前准备

先在[查看数据看板列表](list-data-dashboards.md#成功响应)中选择已配置数据库和数据表的数据看板。

准备有目标工作区访问权限的[个人访问令牌](../../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)和[目标工作区 ID](../../../../../guides/ai-studio/resource-center/workspace.md#复制工作区-id)。

## 请求体

将示例中的调用者专属值替换为实际值。

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/data-dashboards/$DASHBOARD_ID/generate-sql" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "统计最近 30 天每天的销售额",
    "title": "近 30 天销售趋势"
  }'

```

:::::
:::::{tab-item} 参数说明

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `question` | string | 是 | 希望通过数据回答的问题，不能为空。 |
| `title` | string | 否 | 图表标题，用于辅助生成草稿。 |

:::::
::::::
:::::::

## 成功响应

生成成功时返回已经过只读检查和 SQL 可执行性检查的草稿。要查看查询结果，可将 sql_text 传给[预览看板图表 SQL](preview-data-dashboard-chart-sql.md#请求示例)。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": 200,
  "data": {
    "dashboard_id": "dashboard-001",
    "sql_text": "SELECT sale_date, SUM(amount) AS total_amount FROM sales WHERE sale_date >= DATE_SUB(CURRENT_DATE, INTERVAL 30 DAY) GROUP BY sale_date ORDER BY sale_date",
    "chart_type": "line"
  }
}
```

:::::
:::::{tab-item} 字段说明

::::{tab-set}
:::{tab-item} 通用字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| code | integer | 成功时为 200。 |
| data | object | SQL 草稿。 |

:::
:::{tab-item} SQL 草稿

下面表格展开响应示例中的 `data` 对象；每一行是该对象的一个字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| dashboard_id | string | 数据看板 ID。 |
| sql_text | string | 生成并校验通过的只读 SQL 草稿。 |
| chart_type | string | 建议使用的图表类型。 |

:::
::::
:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "ErrDataDashboardSQLDraftValidationFailed",
  "message": "生成的 SQL 未通过校验"
}

```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer 或 string | 错误代码或状态码。 |
| `message` | string | 错误信息。 |

:::::
::::::
:::::::

## 后续操作

使用[预览看板图表 SQL](preview-data-dashboard-chart-sql.md#请求示例)检查结果，确认后再[创建看板图表](create-data-dashboard-chart.md#请求示例)。