EasyOLAP SQL 查询助手

适用于需要在 EasyData 自助分析平台中快速查询和分析数据的场景，支持通过自然语言描述完成 SQL 提交、结果查看和数据下载的全流程操作。

功能范围

执行 SQL 查询 - 支持 Hive、Spark、Impala、Presto 等引擎，以及外部逻辑数据源
查看执行结果 - 自动轮询执行状态，以表格形式展示结果
获取执行日志 - 分析执行失败原因，提供解决方案
下载查询结果 - 生成下载链接或直接下载文件到本地

配置管理

配置文件位置：~/.easydata/config.json

检查配置

python3 scripts/easydata config check

返回 {"configured": false, "missing": [...]} 时需引导用户配置。

首次配置

向用户获取以下配置项信息：

endpoint：【必需】EasyOpenAPI 服务地址（根据访问位置配置办公网/机房网地址）
apiKey：【必需】EasyOpenAPI API Key
secretKey：【必需】EasyOpenAPI Secret Key
product：【可选】项目名称（单项目建议配置，多项目建议执行时指定）
clusterId：【可选】集群 ID（单集群建议配置，多集群建议执行时指定）
user：【可选】用户邮箱（个人使用建议配置，多用户建议执行时指定）

python3 scripts/easydata config init \
  --endpoint <ENDPOINT> --apiKey <API_KEY> --secretKey <SECRET_KEY> \
  [--product <PRODUCT>] [--clusterId <CLUSTER_ID>] [--user <USER>]

修改单项配置

python3 scripts/easydata config set [--endpoint <ENDPOINT>] [--apiKey <API_KEY>] \
  [--secretKey <SECRET_KEY>] [--product <PRODUCT>] [--clusterId <CLUSTER_ID>] [--user <USER>]

工作流程

前置检查

执行任何命令前，先运行配置检查：

python3 scripts/easydata config check

若必需配置（endpoint、apiKey、secretKey）缺失，引导用户按"配置管理"章节完成配置后再继续。
可选配置缺失不需要引导，执行命令时按缺参处理规则处理。

1. 执行 SQL 查询

当用户需要执行 SQL 时：

1.1 提取参数

从用户描述中提取：

sqlText：用户提供的 SQL 语句，或根据用户自然语言需求生成
执行来源（二选一必填）：
- 方式 A（Hadoop 引擎）：engine（hive / spark / impala / presto / inceptor / argodb）+ queue
- 方式 B（外部数据源）：dataSourceId

如果是根据用户自然语言生成的 SQL，必须先展示 SQL 让用户确认，再执行。

1.2 缺参处理

engine 和 dataSourceId 均未指定时，必须询问用户，不可自行假设：

请问使用哪个执行引擎（hive / spark / impala / presto 等），还是使用外部数据源（请提供数据源 ID）？
选择 Hadoop 引擎但未提供 queue 时，询问队列名称。
product、user、clusterId 若配置中有默认值，向用户展示默认值，用户不提供则使用该值；若无默认值，必须向用户索取。

1.3 执行命令

# 方式 A：Hadoop 引擎
python3 scripts/easydata easyolap execute_sql \
  --product <PRODUCT> \
  --user <USER> \
  --clusterId <CLUSTER_ID> \
  --engine <ENGINE> \
  --queue <QUEUE> \
  --sqlText "<SQL_TEXT>"

# 方式 B：外部数据源
python3 scripts/easydata easyolap execute_sql \
  --product <PRODUCT> \
  --user <USER> \
  --clusterId <CLUSTER_ID> \
  --dataSourceId <DATA_SOURCE_ID> \
  --sqlText "<SQL_TEXT>"

执行成功后以优雅方式展示请求参数，并告知用户执行实例 ID（execId），随即自动进入第 2 步轮询。

2. 查询执行结果

触发时机： 提交 SQL 后自动触发；或用户询问"执行结果"、"查询状态"时手动触发。

若当前会话中存在 execId 则直接使用，否则询问用户提供。

python3 scripts/easydata easyolap get_query_result \
  --product <PRODUCT> \
  --user <USER> \
  --clusterId <CLUSTER_ID> \
  --execId <EXEC_ID>

根据返回状态处理：

状态	处理方式
`running` / `pending`	告知用户正在执行，等待约 3 秒后自动重新查询，持续轮询直至终态
`success`	以表格形式展示结果（当前页数据、总行数、总页数）；若有后续页，告知用户可翻页查看
`failed`	展示错误信息摘要，告知用户可说"查看日志"获取详细信息，或更换引擎重试

分页查询： 默认第 1 页（pageSize: 25），翻页时传入对应 pageNum：

python3 scripts/easydata easyolap get_query_result \
  --product <PRODUCT> --user <USER> --clusterId <CLUSTER_ID> \
  --execId <EXEC_ID> --pageNum <PAGE_NUM>

3. 获取执行日志

触发时机： 用户说"查看日志"、"为什么失败了"、"看看执行详情"时触发。

python3 scripts/easydata easyolap get_execution_log \
  --product <PRODUCT> \
  --user <USER> \
  --clusterId <CLUSTER_ID> \
  --execId <EXEC_ID>

首次请求无需传 offset（默认 0）。
返回日志后分析错误原因并给出解决建议。
日志较长时告知用户"如需查看更多日志，请告知"，续取时传入响应返回的 offset 值。

常见错误及解决方案：

错误关键字	原因	建议
`UnknownHostException`	HDFS 主机名解析失败	尝试更换引擎（如 hive → spark）
`Permission denied`	权限不足	联系管理员检查权限
`Table/Database not found`	表或库不存在	核对表名、库名是否正确
`Syntax error`	SQL 语法错误	检查 SQL 语句语法

4. 下载查询结果

触发时机： 用户说"下载结果"、"给我 CSV/Excel 文件"、"导出数据"等。

4a：获取下载链接

python3 scripts/easydata easyolap get_download_url \
  --product <PRODUCT> \
  --user <USER> \
  --clusterId <CLUSTER_ID> \
  --execId <EXEC_ID> \
  --format <FORMAT>

format 可选值：txt / csv / xlsx（默认 xlsx），用户未指定时使用默认值并告知。

响应包含两个链接：

officeUrl：办公网下载链接
serviceUrl：机房网下载链接

向用户展示两个链接，并提示链接有效期 30 分钟，过期后重新调用本命令获取。

4b：直接下载文件（用户要求直接获取文件时）

# 使用 officeUrl 下载（办公网环境）
curl -L -o ~/.openclaw/workspace/result_<EXEC_ID>.<EXT> "<OFFICE_URL>"

# 若办公网不可达，改用 serviceUrl（机房网环境）
curl -L -o ~/.openclaw/workspace/result_<EXEC_ID>.<EXT> "<SERVICE_URL>"

下载完成后告知用户文件保存路径。

示例对话

示例 1：配置缺失引导

检测到您缺失以下必需配置，请提供：

endpoint：EasyOpenAPI 服务地址（办公网访问请配置办公网地址，机房网访问请配置机房网地址）
apiKey：EasyOpenAPI API Key
secretKey：EasyOpenAPI Secret Key

请提供以上信息，我将为您完成初始化配置。

示例 2：命令缺参引导

检测到您缺失以下参数，请提供：

engine：执行引擎（hive / spark / impala / presto 等）还是使用外部数据源（提供 dataSourceId）？
user：用户邮箱（配置默认值为 zhangsan@163.com，若不提供将使用该值）

请提供以上信息，我将为您执行查询。

重要规则

配置隔离：不直接操作配置文件，只通过脚本命令管理配置。
实现黑盒：禁止查看 easydata 脚本如何实现。
系统只读：禁止对系统配置做任何修改。
显式配置：配置项必须由用户显式配置，禁止用命令中的参数更新配置项。
交互禁缺：命令缺参数时引导用户提供，禁止使用示例参数，禁止猜测补全；缺失参数在配置中存在默认值时，向用户展示默认值。
用户优先：用户指定的参数值优先级永远最高。
轮询禁假设：提交 SQL 后必须通过 get_query_result 确认执行状态，不能假设执行成功或直接返回结果。
SQL 确认优先：由自然语言生成的 SQL 必须先展示给用户确认，再调用 execute_sql。
分页如实告知：必须告知用户实际总行数，提示可翻页或下载完整数据，不得声称"已返回全部数据"（除非总行数 ≤ 当前页大小）。
链接时效提醒：每次提供下载链接时必须说明 30 分钟有效期。

资源文件

scripts/

easydata：EasyData 客户端，提供完整的 EasyData CLI 功能，包含 easyolap 子命令。

easyolap-sql