SQL 执行与数据探索

本页覆盖 cz-cli 的 SQL 执行、Schema 和表管理、Job 诊断及工作空间切换相关命令。

cz-cli sql — 执行 SQL

基本用法

# 同步执行，直接返回结果（默认） cz-cli -p prod sql "SELECT current_timestamp()" # 使用 -e 传入 SQL cz-cli -p prod sql -e "SELECT * FROM public.orders LIMIT 10" # 从文件读取 SQL cz-cli -p prod sql -f query.sql

同步 vs 异步

cz-cli sql

cz-cli sql

默认同步执行（

--sync

--sync

），等待结果返回后退出。对于长时间运行的查询，可以异步提交，获取 job_id 后再查结果：

# 异步提交，立即返回 job_id cz-cli -p prod sql "SELECT * FROM huge_table" --async # 查看 job 状态 cz-cli -p prod sql status <job_id> # 或用 job 命令 cz-cli -p prod job status <job_id> cz-cli -p prod job result <job_id>

写操作保护

INSERT、UPDATE、DELETE、CREATE、DROP 等写操作需要显式加

--write

--write

，防止误操作：

cz-cli -p prod sql --write -e "CREATE TABLE IF NOT EXISTS public.demo (id INT, name STRING)" cz-cli -p prod sql --write -e "INSERT INTO public.demo VALUES (1, 'test')" cz-cli -p prod sql --write -e "DROP TABLE public.demo"

批量执行多条语句

用

--batch

--batch

依次执行分号分隔的多条语句：

cz-cli -p prod sql --write --batch -e " CREATE TABLE IF NOT EXISTS ods.events (id INT, ts TIMESTAMP, type STRING); INSERT INTO ods.events VALUES (1, current_timestamp(), 'click'); INSERT INTO ods.events VALUES (2, current_timestamp(), 'view'); "

变量替换

用

--variable KEY=VALUE

--variable KEY=VALUE

注入变量，SQL 中用

%(KEY)s

%(KEY)s

引用，适合模板化查询：

cz-cli -p prod sql "SELECT %(col)s FROM public.orders LIMIT 10" \ --variable col=order_id cz-cli -p prod sql "SELECT * FROM public.orders WHERE dt = '%(dt)s'" \ --variable dt=2026-05-26

查询提示（Query Hint）

用

--set KEY=VALUE

--set KEY=VALUE

传入查询级别的 hint，例如指定时区：

cz-cli -p prod sql "SELECT current_timestamp()" \ --set cz.sql.timezone=UTC

预执行校验（dry-run）

不实际执行，只做语法检查和 EXPLAIN，适合上线前验证：

cz-cli -p prod sql --dry-run -f deploy.sql

输出控制

# 不截断长字段 cz-cli -p prod sql "SELECT * FROM public.orders" --no-truncate # 取消行数限制（默认 100 行） cz-cli -p prod sql "SELECT * FROM public.orders" --no-limit # 不输出列名 cz-cli -p prod sql "SELECT id, name FROM public.orders" --no-header # 指定输出格式 cz-cli -p prod sql "SELECT * FROM public.orders LIMIT 5" -o table cz-cli -p prod sql "SELECT * FROM public.orders LIMIT 5" -o csv

完整参数说明

参数	说明	默认值
`--sync` --sync / `--no-sync` --no-sync	同步等待结果	`true` true
`--async` --async	异步提交，立即返回 job_id	`false` false
`--write` --write	允许写操作（DDL/DML）	关闭
`--batch` --batch / `-B` -B	批量执行多条分号分隔的语句	`false` false
`--variable KEY=VALUE` --variable KEY=VALUE	变量替换，SQL 中用 `%(KEY)s` %(KEY)s	—
`--set KEY=VALUE` --set KEY=VALUE	查询 hint	—
`--dry-run` --dry-run	仅 EXPLAIN，不实际执行	`false` false
`--timeout` --timeout	Job 超时秒数	`300` 300
`--limit` --limit / `--no-limit` --no-limit	自动截断为 100 行	`true` true
`--truncate` --truncate / `--no-truncate` --no-truncate	截断超长字段（3000 字符）	`true` true
`--header` --header / `--no-header` --no-header / `-N` -N	是否输出列名	`true` true
`-f, --file` -f, --file	从文件读取 SQL	—
`-e, --execute` -e, --execute	SQL 字符串（等价于位置参数）	—
`--stdin` --stdin	从 stdin 读取 SQL	`false` false
`--job-profile` --job-profile	查询已完成 job 的执行 profile	—
`--schema-context` --schema-context	在响应中附加 schema 信息（供 Agent 使用）	`false` false

cz-cli schema — Schema 管理

# 列出所有 Schema cz-cli -p prod schema list # 查看 Schema 详情（含表列表） cz-cli -p prod schema describe public # 创建 Schema cz-cli -p prod schema create dwd # 删除 Schema（需确认） cz-cli -p prod schema drop old_schema

cz-cli table — 表管理与数据探索

# 列出当前 Schema 下所有表 cz-cli -p prod table list # 列出指定 Schema 下的表 cz-cli -p prod -s dwd table list # 查看表结构（列名、类型、注释） cz-cli -p prod table describe public.orders # 预览表数据（默认 10 行） cz-cli -p prod table preview public.orders # 查看表行数和最近 job 统计 cz-cli -p prod table stats public.orders # 查看表历史版本（Time Travel 支持） cz-cli -p prod table history public.orders # 从 DDL 创建表 cz-cli -p prod table create --write "CREATE TABLE public.test (id INT, name STRING)" # 删除表（需确认） cz-cli -p prod table drop public.test

cz-cli job — SQL Job 诊断

异步提交的查询会返回 job_id，用

job

job

命令追踪：

# 查看 job 状态和执行摘要 cz-cli -p prod job status <job_id> # 获取 job 查询结果（如果还在运行则等待） cz-cli -p prod job result <job_id> # 查看 job 执行 profile（分析性能瓶颈） cz-cli -p prod sql --job-profile <job_id>

cz-cli workspace — 工作空间切换

# 查看当前工作空间 cz-cli -p prod workspace current # 列出所有可用工作空间 cz-cli -p prod workspace list # 临时切换工作空间（仅本次命令） cz-cli -p prod workspace use analytics # 持久化切换（保存到 profile） cz-cli -p prod workspace use analytics --persist

常见使用场景

场景一：探索一张新表

cz-cli -p prod table describe public.orders cz-cli -p prod table preview public.orders cz-cli -p prod table stats public.orders

场景二：调试慢查询

# 先异步提交 cz-cli -p prod sql "SELECT * FROM huge_table GROUP BY ..." --async # 记下 job_id，查看执行详情 cz-cli -p prod job status <job_id> cz-cli -p prod sql --job-profile <job_id>

场景三：CI/CD 中执行 DDL

# 先 dry-run 校验语法 cz-cli -p prod sql --dry-run -f migrations/v2.sql # 确认无误后执行 cz-cli -p prod sql --write --batch -f migrations/v2.sql

场景四：模板化查询（Agent 场景）

cz-cli -p prod sql \ "SELECT COUNT(*) FROM public.orders WHERE dt = '%(dt)s' AND status = '%(status)s'" \ --variable dt=2026-05-26 \ --variable status=completed