# 下载执行结果

将一条已成功完成的 SQL 查询结果下载为 CSV 文件。

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

## 调用前准备

1. 准备有目标工作区访问权限的[个人访问令牌](../../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)和[目标工作区 ID](../../../../../guides/ai-studio/resource-center/workspace.md#复制工作区-id)。
2. [查看执行状态](get-execution-status.md#成功响应)，确认查询已成功，并记录响应中的结果 ID（`statement_id`）。

## 请求体

将 `$AI_STUDIO_API_KEY`、`$WORKSPACE_ID` 和 `$STATEMENT_ID` 替换为实际值。

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

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/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

```

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

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `statement_id` | string | 是 | 成功执行查看的结果 ID。 |

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

## 成功响应

成功时返回 CSV 文件，而不是 JSON。请求示例会将文件保存为 `result.csv`。

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

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

CSV 使用标准 CSV 编码进行引号和分隔符转义。SQL NULL 与真实空字符串都会成为空单元格；以公式字符开头的文本按原值输出。使用表格软件打开下载文件时，应按业务需要选择文本导入方式。

下载受服务端配置的字节数和并发上限约束，超限分别可能返回 HTTP 413 和 429。请求先占用下载并发名额，再校验结果归属；结果先完整写入临时文件，随后发送响应，响应结束后清理临时文件。下载中断时收到的文件可能不完整。

## 错误响应

失败时响应为 JSON。

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

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

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer 或 string | SQL 处理错误可能为数值状态码；身份校验或通用服务错误可能为字符串错误码。 |
| `message` | string | 错误信息。 |

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

错误有两种封装：SQL 处理路径使用 {"code":400,"message":"..."}；身份校验或通用服务错误使用 {"code":"ErrServer","msg":"..."}。message 和 msg 均为可读错误信息，应根据实际字段读取，不能只按数值 code 判断。

## 后续操作

需要按页读取时，使用[查看执行结果](get-execution-result.md#调用前准备)。