Studio 任务开发与运维

cz-cli 可以操作 ClickZetta Studio 中的任务，适合数据开发和日常运维。

创建 SQL 任务

cz-cli -p prod task create daily_order_summary --type SQL --description "每日订单汇总"

保存任务 SQL

cz-cli -p prod task save-content daily_order_summary --content "INSERT INTO public.order_summary SELECT current_date(), COUNT(*) FROM public.orders"

配置调度

下面示例表示每天 02:00 执行：

cz-cli -p prod task save-cron daily_order_summary --cron "0 0 2 * * ? *"

发布任务

cz-cli -p prod task deploy daily_order_summary

手动执行任务

cz-cli -p prod task execute daily_order_summary --max-wait-seconds 300

查看运行记录和日志

查看最近运行

cz-cli -p prod runs list --task daily_order_summary --limit 5

查看某次运行详情

cz-cli -p prod runs detail <run_id>

查看某次运行日志

cz-cli -p prod runs logs <run_id>

等待某次运行完成

cz-cli -p prod runs wait <run_id>

任务运维进阶（runs 完整命令）

cz-cli runs

cz-cli runs

除基本的 list / detail / logs / wait 外，还支持以下运维操作：

停止运行中的实例

cz-cli -p prod runs stop <run_id>

重跑失败的实例

cz-cli -p prod runs rerun <run_id>

补数（backfill）

对指定任务补跑某个时间范围内的调度实例，不可逆，执行前需确认：

cz-cli -p prod runs refill <task_name> \ --from "2026-05-01T00:00:00" \ --to "2026-05-07T23:59:59" \ --vc DEFAULT

加

-y

-y

跳过确认提示（CI/CD 场景）：

cz-cli -p prod runs refill <task_name> --from ... --to ... -y

查看运行依赖关系

# 默认查看上游 1 层、下游 1 层 cz-cli -p prod runs deps <run_id> # 指定深度 cz-cli -p prod runs deps <run_id> --parent-level 2 --child-level 2

运行统计汇总

cz-cli -p prod runs stats --task <task_name> --from "2026-05-01" --to "2026-05-07"

runs 与 attempts 的区别

概念	说明
run（运行实例）	一次调度触发对应一个 run，有唯一 run_id；run 可能因失败自动重试多次
attempt（重试记录）	run 内每次实际执行对应一个 attempt；run 失败重试 3 次，就有 3 个 attempt

典型排查流程：

# 1. 找到失败的 run cz-cli -p prod runs list --task daily_order_summary --from "2026-05-26" # 2. 查看 run 详情（含所有 attempt 概览） cz-cli -p prod runs detail <run_id> # 3. 查看该 run 下所有 attempt cz-cli -p prod attempts list <run_id> # 4. 查看某个 attempt 的详细日志 cz-cli -p prod attempts log <attempt_id>

任务高级配置（task save-config）

task save-config

task save-config

用于配置任务的重试策略、依赖关系、计算集群和超时，不影响已配置的 cron 调度：

cz-cli -p prod task save-config <task_name> \ --retry-count 3 \ --retry-interval 5 \ --retry-unit m \ --timeout 60 \ --timeout-unit m \ --vc DEFAULT

参数说明：

参数	说明	示例
`--retry-count` --retry-count	最大重试次数	`3` 3
`--retry-interval` --retry-interval	重试间隔值	`5` 5
`--retry-unit` --retry-unit	重试间隔单位（ `m` m =分钟， `s` s =秒）	`m` m
`--timeout` --timeout	执行超时值	`60` 60
`--timeout-unit` --timeout-unit	超时单位（ `m` m =分钟， `s` s =秒）	`m` m
`--rerun-property` --rerun-property	补数策略： `1` 1 =任意时间可补， `2` 2 =仅失败可补， `3` 3 =不可补	`2` 2
`--self-depends` --self-depends	自依赖： `0` 0 =关闭， `1` 1 =开启（上一周期完成后才触发下一周期）	`1` 1
`--vc` --vc	指定执行的 VCluster 代码	`DEFAULT` DEFAULT
`--deps` --deps	依赖操作： `keep` keep =保留现有， `replace` replace =替换， `clear` clear =清空	`replace` replace
`--dep-tasks` --dep-tasks	上游依赖任务 JSON 数组	`'[{"taskId":123,"taskName":"upstream"}]'` '[{"taskId":123,"taskName":"upstream"}]'

工作流任务（task flow）

工作流（Flow）是将多个子任务编排为 DAG 的组合任务类型：

# 查看工作流 DAG 结构 cz-cli -p prod task flow dag <flow_task_name> # 添加节点 cz-cli -p prod task flow create-node <flow_task_name> --node-name etl_step1 --type SQL # 设置节点间依赖（step2 依赖 step1） cz-cli -p prod task flow bind <flow_task_name> --from etl_step1 --to etl_step2 # 保存节点 SQL 内容 cz-cli -p prod task flow node-save <flow_task_name> --node-name etl_step1 \ --content "INSERT INTO dwd.orders SELECT * FROM ods.raw_orders" # 发布工作流 cz-cli -p prod task flow submit <flow_task_name> # 查看工作流节点运行实例 cz-cli -p prod task flow instances <flow_task_name>