武阳
246 lines
7.2 KiB
Markdown
246 lines
7.2 KiB
Markdown
---
|
||
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 写到当前会话 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` |
|
||
| 输出 | `~/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
|
||
}
|
||
```
|
||
|
||
### 指定输出路径
|
||
|
||
输出路径优先写到当前用户当前会话 output 目录，或用户明确指定的任务目录。不要写项目根目录。
|
||
|
||
```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 与服务地址必须同集群，否则可能报“找不到元信息”。
|