---
name: data-factory-sql
description: 通过小米数据工场 Kyuubi HTTP API 执行 SQL 查询，轮询状态并下载 CSV 结果。适合用户直接给 SQL、要求“跑个 SQL”“数据工场查一下”“查数据”，或基于表结构/字段说明生成 SQL 草稿后执行。
when_to_use: 用户希望在小米数据工场执行 SQL、查询 Hive/Presto/Spark/Doris/Hologres 数据、下载查询结果 CSV、或基于数据工场结果做进一步分析时使用。
aliases: data-factory, kyuubi-sql, sql-query, 数据工场, 跑SQL
allowed_tools: python_exec, python_package, read_file, write_file, ask_user_question
---

# Data Factory SQL Skill

使用这个 skill 作为“小米数据工场 SQL 查询”的统一入口。它通过 Kyuubi HTTP API 提交 SQL、轮询状态、拉取结果并保存 CSV，不依赖浏览器。

本 skill 已安装在项目目录：

```text
skills/data-factory-sql/
```

## 关键文件

| 文件 | 用途 |
|------|------|
| `run_sql.py` | CLI 入口，提交 SQL 并输出 JSON 摘要 |
| `kyuubi_client.py` | Kyuubi HTTP API client |
| `README.md` | 原始说明和安装/token 配置说明 |

## 在本数据 Agent 中使用

不要用 `bash` 执行 `python run_sql.py`，也不要用系统 `pip` 安装依赖。

执行 SQL 必须使用 `python_exec`：

```json
{
  "script_path": "skills/data-factory-sql/run_sql.py",
  "args": ["SELECT 1 AS id, 'hello' AS msg"],
  "timeout_seconds": 700,
  "max_output_chars": 20000
}
```

如果 `python_exec` 返回缺少 `requests`，先用 `python_package` 安装：

```json
{
  "action": "install",
  "packages": ["requests"],
  "timeout_seconds": 120
}
```

多行 SQL 或复杂 SQL 不要通过命令行字符串硬塞。优先把 SQL 写到当前 session/scratchpad；只有用户明确指定外部目标文件时，才写到用户指定目录，再用 `-f` 执行：

```json
{
  "script_path": "skills/data-factory-sql/run_sql.py",
  "args": ["-f", "<sql_file>", "--engine", "auto"],
  "timeout_seconds": 700,
  "max_output_chars": 20000
}
```

## Token 配置

脚本按以下顺序读取 token：

1. `--token <value>`
2. 环境变量 `KYUUBI_TOKEN`
3. `C:\workspace\data-factory-token.txt`
4. `~/.config/data-factory/token`

不要把 token 写入项目仓库。推荐让用户在运行环境里配置 `KYUUBI_TOKEN`，或写到用户 home 下的默认 token 文件。

Token 申请入口：

```text
https://data.mioffice.cn/workspace/?wid=<YOUR_WORKSPACE_ID>#/workspace/<YOUR_WORKSPACE_ID>/config?tab=tokenList
```

注意：token 与服务地址必须同集群。本 skill 默认 `cnbj1`，如果用户使用其他集群，需要显式传 `--cluster cnbj2`、`--cluster alsgp0` 等。

## 默认配置

| 项 | 默认值 |
|----|------|
| 集群 | `cnbj1` |
| Base URL | `http://proxy-service-http-cnbj1-dp.api.xiaomi.net` |
| 引擎 | `auto` |
| 输出 | 当前 session/output/data_factory_<时间戳>.csv；如果没有 session 环境，则退回 `~/Downloads/data_factory_<时间戳>.csv` |
| 轮询间隔 | 2.0s |
| 查询超时 | 600s |

## 两种工作模式

### 模式 A：用户直接给 SQL

用户提供完整 SQL 时，可以在做基础风险检查后直接执行。

执行前必须检查：

- 是否明显是查询语句，而不是危险写操作。
- 大表查询是否带 `dt`、日期、分区或合理 limit。
- 用户是否显式指定了 `catalog.schema.table`、引擎、集群或输出路径。

如果 SQL 看起来会全表扫、跨天扫很多数据，或存在写入/删除/建表等副作用，不要直接执行，先向用户确认。

### 模式 B：自然语言需求 + 表结构/知识文档

用户没有给完整 SQL，而是给自然语言需求、表结构、字段说明或业务文档时：

1. 先读取用户提供的文档或表结构。
2. 生成 SQL 草稿。
3. 向用户展示 SQL 草稿并等待确认。
4. 用户确认后再执行。
5. 读取 CSV 结果并分析，必要时迭代 SQL。

不要跳过第 3 步。自然语言生成的 SQL 必须先给用户 review。

## 标准执行流程

1. 判断是“直接 SQL”还是“自然语言生成 SQL”。
2. 如果需要读取表结构或知识文档，先用 `read_file`。
3. 检查 SQL 风险：分区、时间范围、limit、副作用、catalog/schema/table 是否被擅自改动。
4. 需要确认时，展示 SQL 并停止等待用户确认。
5. 确认后调用 `python_exec` 执行 `skills/data-factory-sql/run_sql.py`。
6. 解析 stdout 最后一行 JSON 摘要。
7. 如果 JSON 有 `error`，把错误直接告诉用户，不要盲目重试。
8. 如果 `rows == 0`，提示空结果，不要编造数据。
9. 如果有 `output`，用 `read_file` 读取 CSV 或根据行数选择采样分析。
10. 用具体数值回答用户问题，并说明结果文件路径。

## 常用参数

### 直接执行 SQL

```json
{
  "script_path": "skills/data-factory-sql/run_sql.py",
  "args": ["SELECT 1"],
  "timeout_seconds": 700,
  "max_output_chars": 20000
}
```

### 从文件读取 SQL

```json
{
  "script_path": "skills/data-factory-sql/run_sql.py",
  "args": ["-f", "/path/to/query.sql"],
  "timeout_seconds": 700,
  "max_output_chars": 20000
}
```

### 指定引擎

```json
{
  "script_path": "skills/data-factory-sql/run_sql.py",
  "args": ["-f", "/path/to/query.sql", "--engine", "spark"],
  "timeout_seconds": 700,
  "max_output_chars": 20000
}
```

### 指定输出路径

输出路径优先写到当前 session/output，或用户明确指定的任务目录。不要写项目根目录、源码目录或其他非 session 临时位置。

```json
{
  "script_path": "skills/data-factory-sql/run_sql.py",
  "args": ["-f", "/path/to/query.sql", "--output", "/path/to/output/result.csv"],
  "timeout_seconds": 700,
  "max_output_chars": 20000
}
```

### 调试配置

```json
{
  "script_path": "skills/data-factory-sql/run_sql.py",
  "args": ["--print-config"],
  "timeout_seconds": 60,
  "max_output_chars": 12000
}
```

## 输出 JSON

成功时 stdout 最后一行是 JSON：

```json
{
  "queryId": "...",
  "engine": "TRINO",
  "rows": 1,
  "cols": 2,
  "elapsed_ms": 5210,
  "columns": [{"name": "id", "type": "BIGINT"}],
  "output": "/path/to/data_factory_20260427_150120.csv"
}
```

失败时会输出：

```json
{"error": "..."}
```

退出码：

- `2`：输入问题，例如空 SQL。
- `3`：认证问题，例如 token 失效。
- `4`：SQL 执行错误，例如语法、权限、超时。
- `5`：其他 Kyuubi 错误。

## 红线

禁止：

- 在自然语言生成 SQL 后跳过用户确认直接执行。
- 在 SQL 失败后不读 `error` 信息盲目重试。
- 大表查询没有 `dt`、日期范围、分区过滤或合理 limit 就直接执行。
- 擅自修改用户 SQL 里的 `catalog/schema/table` 名。
- 把 token、CSV 输出或临时 SQL 文件写进项目源码目录。
- 使用 `bash` 执行 Python 或安装依赖。

必须：

- 使用 `python_exec` 执行脚本。
- 缺依赖时使用 `python_package` 安装到当前用户独立 venv。
- 多行 SQL 优先走 `-f` 文件。
- 解析 stdout 最后一行 JSON 决定下一步。
- 大结果集先汇报行数和文件路径，再决定全量分析或采样。

## 已知约束

- 状态机是 `PENDING / RUNNING / FINISHED / ERROR / TIMEOUT / CLOSED`。
- `progress 100%` 不代表完成，必须等 `state == FINISHED`。
- `nextQueryId` 每次轮询都会更新，client 已自动处理。
- 查询 ID 中的 `/`、`;`、`:` 等特殊字符，client 已自动 URL 编码。
- token 与服务地址必须同集群，否则可能报“找不到元信息”。