# 下载执行结果

下载当前身份已成功执行的 SQL 查询结果 CSV 文件。

```text
POST https://moi.matrixorigin.cn/newmoi/query/result/download
```

## 调用前准备

先[查询执行状态](get-execution-status.md)，确认状态为 `success` 并取得结果 ID（`statement_id`）。响应体是 CSV 文件，不是 JSON。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：查询所在的工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$STATEMENT_ID`：状态响应中的结果 ID，即 `data.statement_id`。

## 请求体

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `statement_id` | string | 是 | 成功执行查询的结果 ID。 |

## 请求示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/query/result/download" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d "{\"statement_id\":\"$STATEMENT_ID\"}" \
  --output result.csv
```

## 成功响应

成功时返回 CSV 文件，示例命令会将它保存为 `result.csv`。例如，查询订单编号、客户名称和金额后的下载内容如下：

```csv
order_id,customer_name,amount
1001,王小明,128.50
1002,李华,89.00
1003,Chen Wei,256.00
```

响应 Header 中包含实际文件名和文件大小：

| 响应部分 | 值 | 说明 |
| --- | --- | --- |
| 响应体 | CSV 文件内容 | 完整查询结果。 |
| `Content-Type` | `text/csv; charset=utf-8` | 响应体的媒体类型和字符集。 |
| `Content-Disposition` | `attachment; filename*=UTF-8''query-result-<TIMESTAMP>.csv` | 建议使用的下载文件名。 |
| `Content-Length` | 文件字节数 | CSV 文件大小。 |

## 错误响应

失败时响应为 JSON。

```json
{
  "code": 404,
  "message": "SQL 查询结果不存在"
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 15 45 40

* - HTTP 状态码
  - 常见原因
  - 建议操作
* - `400`
  - 请求体不是有效 JSON，或缺少 `statement_id`。
  - 检查请求体和 Statement ID。
* - `401`
  - 凭据缺失或无效。
  - 检查访问令牌。
* - `404`
  - 结果不存在、查询未成功完成，或结果不属于当前身份。
  - 确认查询状态为 `success`，并检查 Statement ID。
* - `413`
  - 结果文件超过下载上限。
  - 缩小查询范围后重新执行。
* - `429`
  - 当前下载容量已满。
  - 稍后重试。
* - `500`
  - 服务端无法验证、准备或读取结果。
  - 记录错误信息后重试。
* - `503`
  - 下载服务或当前角色的执行连接不可用。
  - 稍后重试。
```

## 后续操作

需要按页读取时使用[查询执行结果](get-execution-result.md)。