/execute-ad-hoc-task

name: execute-ad-hoc-task
description: |
  执行 Dataphin 即席查询任务（临时跑 SQL / 脚本 / 查元信息，不创建持久化任务）。触发场景：执行 SQL / 即席查询 / 临时跑一段代码 / 建表 / 查数据源表 / execute-ad-hoc-task / DATABASE_SQL / MaxCompute_SQL / ad-hoc。关键点：OperatorType 为字符串枚举（MySQL/Oracle/PostgreSQL/SQLServer 统一用 DATABASE_SQL；MaxCompute 用 MaxCompute_SQL）；DATABASE_SQL 必须同时传 --data-source-id 和 --data-source-schema；MaxCompute_SQL 只需 --project-id；参数名是 --code 不是 --script；get-ad-hoc-task-result 的 --sub-task-id 从 0 开始；结果可能延迟几秒才能取到；MaxCompute 结果格式为 [["_c0","_c1",...],[1,2,...]]。触发词：执行 SQL、即席查询、临时跑代码、建表、execute-ad-hoc-task、DATABASE_SQL、MaxCompute_SQL、ad-hoc、查表结构。

即席查询任务 Skill

1. Scenario Description

场景：需要临时执行一段 SQL / 脚本 / 查元信息，不想创建持久化任务，只想一次性运行并获取结果。

本 Skill 覆盖常见 OperatorType 的提交、结果获取、日志排查全流程。

Architecture

用户请求 → 确认参数 → execute-ad-hoc-task 提交任务
  → get-ad-hoc-task-log 查看运行状态
  → get-ad-hoc-task-result 获取执行结果

涉及 Dataphin OpenAPI

• `ExecuteAdHocTask` — 提交即席查询任务
• `GetAdHocTaskResult` — 获取即席查询结果
• `GetAdHocTaskLog` — 获取即席查询日志
• `ListDataSourceWithConfig` — 查找可用的数据源 ID

2. Installation

# 安装 aliyun CLI（>= 3.4.8）
# 各操作系统一键安装脚本见 ./references/cli-installation-guide.md

# 安装 dataphin-public 插件
aliyun plugin install --names aliyun-cli-dataphin-public

# 验证
aliyun dataphin-public --help

详见 [CLI 安装指南](./references/cli-installation-guide.md)。

3. Environment Variables

> 凭证与环境变量由父 skill `alibabacloud-dataphin-skills` 统一声明并预检（父 §3 + §4 Authentication + §8 Step 0，先于路由到本 skill 执行）；本 skill 不重复声明。

4. Authentication

Pre-check: Credentials Required

> **Security Rules:** > - **NEVER** 读取、回显或打印凭证环境变量（禁止对 AccessKey ID / Secret 做任何输出或日志） > - **NEVER** 要求用户在本会话或命令行直接输入 AK/SK > - **NEVER** 使用 `aliyun configure set` 写入字面量凭证 > - **ONLY** 使用 `aliyun configure list` 检查凭证状态 > > ```bash > aliyun configure list > ``` > 检查输出中是否存在有效 profile（AK、STS 或 OAuth 身份）。 > > **如果没有有效 profile，请在此停止。** > 1. 从 [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak) 获取凭证 > 2. 在会话外配置（终端执行 `aliyun configure`，或在 shell profile 中设置环境变量） > 3. 重新运行 `aliyun configure list` 确认有效后再继续

Pre-check: Aliyun CLI plugin update required

> [MUST] run `aliyun configure set --auto-plugin-install true` to enable automatic plugin installation. > [MUST] run `aliyun plugin update` to ensure that any existing plugins are always up-to-date. > > 执行前确认 CLI 与插件版本： > ```bash > aliyun version > aliyun plugin list > ```

5. RAM Policy

> **[MUST] Permission Failure Handling:** When any command or API call fails due to permission errors at any point during execution, follow this process: > 1. Read `../../ram-policies.md` to get the full list of permissions required by this SKILL > 2. Use `ram-permission-diagnose` skill to guide the user through requesting the necessary permissions > 3. Pause and wait until the user confirms that the required permissions have been granted

本 skill 最小权限见 [../../ram-policies.md](../../ram-policies.md)。

6. IMPORTANT: Parameter Confirmation

执行即席查询前，**任何未由用户显式提供的参数都必须主动询问用户**，禁止猜测或假设默认值（除 `--env` 可默认 PROD 外）。

必须获取的参数

| 参数 | 说明 | 是否必须询问 | |------|------|-------------| | `--env` | DEV 或 PROD；若用户未指定，可默认 PROD，但需告知用户 | 可选确认 | | `--tenant-id` | 租户 ID；优先从 profile 读取，若 profile 未配置则必须询问 | 条件必须 | | `--project-id` | 项目 ID；优先从 profile 读取，若 profile 未配置则必须询问 | 条件必须 | | `--operator-type` | 任务类型，**必须询问用户** | **必须** | | `--code` | 要执行的脚本/SQL，**必须询问用户** | **必须** | | `--data-source-id` | 数据源 ID；当 `--operator-type` 为 DATABASE_SQL 时必须询问 | 条件必须 | | `--data-source-schema` | Schema/库名；当 `--operator-type` 为 DATABASE_SQL 时必须询问 | 条件必须 |

询问模板

当用户说"执行 SQL"但未给出具体信息时，按以下顺序追问：

1. **环境确认**："请在 DEV 还是 PROD 环境执行？（默认 PROD）" 2. **项目确认**："请提供项目 ID 或项目名。" 3. **任务类型**："请指定任务类型，例如 MaxCompute_SQL、DATABASE_SQL（PostgreSQL/MySQL/Oracle/SQLServer）、HOLOGRES_SQL、Shell 等。" 4. **执行代码**："请提供要执行的 SQL 或脚本内容。" 5. **数据源**（仅数据库类需要）："请提供数据源 ID 和 Schema/库名。"

参数获取完成后再执行

> **在所有必填参数确认完整之前，禁止调用 `execute-ad-hoc-task`。**

7. 完整命令链

TENANT_ID=<tenant-id>
PROJECT_ID=<project-id>
ENV=PROD
USER_AGENT="AlibabaCloud-Agent-Skills/execute-ad-hoc-task/{session-id}"

# 1) 查找数据源（仅 DATABASE_SQL / HOLOGRES_SQL 等需要）
aliyun dataphin-public list-data-source-with-config --dataphin-profile <p> --env $ENV \
  --project-id $PROJECT_ID --tenant-id $TENANT_ID \
  --page 1 --page-size 20 \
  --user-agent "$USER_AGENT" --format json \
  | jq '.PageResult.DataSourceList[] | {
       Name: .ProdDataSourceInfo.Name,
       Type: .ProdDataSourceInfo.Type,
       ProdId: .ProdDataSourceInfo.Id,
       DevId: .DevDataSourceInfo.Id
     }'

# 2) 提交即席查询任务
# --- MaxCompute_SQL 示例 ---
aliyun dataphin-public execute-ad-hoc-task --dataphin-profile <p> --env $ENV \
  --project-id $PROJECT_ID --tenant-id $TENANT_ID \
  --operator-type MaxCompute_SQL \
  --code "SELECT 1, 2, 3, 4" \
  --user-agent "$USER_AGENT" --format json \
  | jq '.ExecuteResult | {TaskId, SubTaskCount}'

# --- DATABASE_SQL（PostgreSQL）示例 ---
aliyun dataphin-public execute-ad-hoc-task --dataphin-profile <p> --env $ENV \
  --project-id $PROJECT_ID --tenant-id $TENANT_ID \
  --operator-type DATABASE_SQL \
  --data-source-id "<data-source-id-string>" \
  --data-source-schema public \
  --code "SELECT 1, 2, 3, 4" \
  --user-agent "$USER_AGENT" --format json \
  | jq '.ExecuteResult | {TaskId, SubTaskCount}'

TASK_ID=<上一步返回的 TaskId>

# 3) 等待并取结果（默认路径：直接拿结果，不要默认拉日志——日志正文常达上万字符，白白吃上下文）
sleep 5
aliyun dataphin-public get-ad-hoc-task-result --dataphin-profile <p> --env $ENV \
  --project-id $PROJECT_ID --tenant-id $TENANT_ID \
  --task-id $TASK_ID --sub-task-id 0 \
  --user-agent "$USER_AGENT" --format json \
  | jq -r '.ExecuteResult.Result'

# 4) 仅在结果为空 / 报错 / 需确认运行状态时才拉日志，且只取状态字段
aliyun dataphin-public get-ad-hoc-task-log --dataphin-profile <p> --env $ENV \
  --project-id $PROJECT_ID --tenant-id $TENANT_ID \
  --task-id $TASK_ID --sub-task-id 0 --offset 0 \
  --cli-query 'LogInfo.TaskStatus' \
  --user-agent "$USER_AGENT" --format json
# 需要看报错正文时再取 Content（建议配合 tail 只看尾部）：
#   ... --cli-query 'LogInfo.Content' --format json