@clickzetta/cz-cli-linux-x64 0.3.0 → 0.3.1

package/bin/skills/clickzetta-studio-overview/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: clickzetta-studio-overview
+description: |
+  ClickZetta Lakehouse Studio 功能全貌概览。Studio 是内置于 Lakehouse 的一站式
+  Web IDE，集数据开发、任务调度、数据集成、数据目录、数据质量、运维监控六大模块于一体，
+  是 ClickZetta 区别于 Snowflake/Databricks 的核心差异化能力（后两者需第三方工具）。
+  覆盖：六大模块定位与边界、任务类型（SQL/Python/Shell/JDBC/同步/动态表）、
+  任务组 DAG 编排、任务参数（${var} 和 $[时间表达式]）、调度配置、
+  数据目录（Data Catalog）、数据质量规则六大维度、运维监控告警。
+  当用户说"Studio 是什么"、"Studio 有哪些功能"、"Studio 和其他 Lakehouse 的区别"、
+  "任务调度怎么配"、"DAG 编排"、"任务组"、"任务参数"、"${} 参数怎么用"、
+  "数据目录"、"数据质量"、"运维监控"、"告警配置"、"补数据"、"任务依赖"时触发。
+  Keywords: Studio, Web IDE, scheduler, DAG, data catalog, data quality, monitoring
+---
+
+# ClickZetta Lakehouse Studio 功能概览
+
+阅读 [references/studio-modules.md](references/studio-modules.md) 了解各模块详细说明。
+
+---
+
+## Studio 是什么
+
+Studio 是 ClickZetta Lakehouse **内置的一站式 Web IDE**，无需安装任何客户端，直接在浏览器中完成从数据接入、开发、调度到运维的全链路操作。
+
+**这是 ClickZetta 与 Snowflake、Databricks 等产品的核心差异之一**：
+
+| 能力 | ClickZetta Studio | Snowflake | Databricks |
+|---|---|---|---|
+| Web SQL 开发 | ✅ 内置 | ✅ Snowsight | ✅ Notebooks |
+| 可视化数据集成（无代码同步） | ✅ 内置 30+ 数据源 | ❌ 需第三方 | ❌ 需第三方 |
+| 任务调度 + DAG 编排 | ✅ 内置 | ❌ 需第三方 | ❌ 需第三方 |
+| 数据目录（Data Catalog） | ✅ 内置 | 部分 | 部分 |
+| 数据质量规则 | ✅ 内置 6 维度 | ❌ 需第三方 | ❌ 需第三方 |
+| 运维监控 + 告警 | ✅ 内置 | 部分 | 部分 |
+
+---
+
+## Studio 六大模块
+
+### 1. 数据开发（IDE）
+
+Web 在线 IDE，支持多种任务类型：
+
+| 任务类型 | 说明 | 使用集群 |
+|---|---|---|
+| SQL 任务 | 编写 DDL/DML，支持自动补全、结果可视化 | GP 或 AP |
+| Python 任务 | SQLAlchemy / ZettaPark 脚本，支持安装依赖 | 不使用 VCluster |
+| Shell 任务 | Shell 脚本，支持调用外部命令 | 不使用 VCluster |
+| JDBC 任务 | 连接 MySQL/Hive/ClickHouse 等执行 SQL | 不使用 VCluster |
+| 动态表任务 | 向导式创建 Dynamic Table，配置刷新周期 | GP 或 AP |
+| 数据同步任务 | 无代码配置离线/实时/CDC 同步 | 同步型 VCluster |
+
+### 2. 任务调度与编排
+
+- **周期调度**：Cron 表达式，支持分钟/小时/天/月级别
+- **任务依赖**：上下游依赖，支持跨工作空间依赖
+- **任务组（DAG）**：可视化拖拽编排，批量管理一组任务
+- **补数据**：对历史周期重新触发执行
+- **任务参数**：动态变量替换，支持时间表达式
+
+### 3. 数据集成（同步任务）
+
+内置 30+ 数据源，无代码配置数据同步：
+
+- **离线同步**：全量/增量，支持整库迁移、Schema Evolution
+- **实时同步**（单表）：Kafka、MySQL、PostgreSQL 实时写入
+- **多表实时 CDC**：整库镜像、分库分表合并，基于 Binlog/WAL
+
+### 4. 数据目录（Data Catalog）
+
+- 全局数据资产搜索（按名称、描述、负责人）
+- 表详情：DDL、字段、数据预览（100行）、数据血缘、作业历史
+- 可视化创建 Schema/表（内置 DDL 模板）
+
+### 5. 数据质量
+
+6 大维度质量规则：完整性、唯一性、一致性、准确性、有效性、及时性。
+
+- 支持定时触发、调度任务触发、手动触发
+- 质量规则大盘：覆盖表数、校验通过率、高质量表
+
+### 6. 运维监控与告警
+
+- 任务实例运维：启停、重跑、批量操作
+- 内置告警规则：周期任务失败、数据质量失败等
+- 自定义告警规则
+- 告警通知：飞书/企业微信 webhook
+
+---
+
+## 任务参数详解
+
+任务参数是 Studio 调度的核心能力，实现代码与配置分离。
+
+### 参数格式
+
+```sql
+-- 在 SQL 中使用参数（格式：${参数名}）
+SELECT * FROM orders
+WHERE city = '${city}'
+  AND dt = '${yesterday}';
+```
+
+### 参数赋值方式
+
+| 赋值类型 | 示例 | 说明 |
+|---|---|---|
+| 常量 | `Shanghai` | 固定值 |
+| 系统内置时间函数 | `$[yyyy-MM-dd, -1d]` | 昨天日期 |
+| 系统内置时间函数 | `$[yyyy-MM-dd HH:mm:ss]` | 当前时间 |
+| 系统内置时间函数 | `$[yyyyMM, -1M]` | 上月 |
+| 系统内置参数 | `sys_plan_datetime` | 任务计划执行时间 |
+
+```sql
+-- 示例：每天处理前一天数据
+SELECT date, SUM(amount)
+FROM sales
+WHERE dt = '${yesterday}'   -- 赋值：$[yyyy-MM-dd, -1d]
+GROUP BY date;
+```
+
+### 参数作用域
+
+- **任务参数**：仅当前任务有效
+- **任务组参数**：任务组内所有任务共享，任务组提交后生效
+
+---
+
+## 任务组（DAG）编排
+
+任务组是 Studio 的核心调度能力，用于管理有依赖关系的一批任务。
+
+```
+任务组（Task Group）
+├── 节点 A：离线同步（MySQL → Lakehouse）
+├── 节点 B：SQL 任务（ODS 清洗）  依赖 A
+├── 节点 C：SQL 任务（DWD 加工）  依赖 B
+└── 节点 D：SQL 任务（DWS 聚合）  依赖 C
+```
+
+**关键限制：**
+- 任务组内仅支持周期任务，不支持实时任务
+- 一个任务节点只能归属于一个任务组
+- 任务组参数需提交后才对任务节点生效
+- 跨工作空间依赖支持，但下游链路复制不包含其他空间节点
+
+---
+
+## 数据目录（Data Catalog）核心功能
+
+```sql
+-- 数据目录中的表详情页提供：
+-- 1. DDL 语句（一键复制）
+-- 2. 字段信息（名称/类型/描述/主键标识）
+-- 3. 数据预览（100行，需 SELECT 权限 + 指定 VCluster）
+-- 4. 数据血缘（上下游表关系）
+-- 5. 作业历史（该表相关的查询记录）
+-- 6. 上传（本地文件直接上传到表）
+```
+
+---
+
+## 与其他系统的对比
+
+**为什么 Studio 是差异化能力？**
+
+Snowflake 和 Databricks 的数据集成、调度、数据质量通常需要对接 Fivetran、dbt、Airflow、Great Expectations 等第三方工具，形成复杂的技术栈。
+
+ClickZetta Studio 将这些能力**内置在平台中**，统一的权限体系、统一的监控告警、统一的数据血缘，降低了运维复杂度，特别适合中小团队和希望减少工具链复杂度的企业。

package/bin/skills/clickzetta-studio-overview/references/studio-modules.md

@@ -0,0 +1,173 @@
+# Studio 各模块详细说明
+
+> 来源：https://www.yunqi.tech/documents/LakehouseStudioTour 等官方文档
+
+---
+
+## 任务类型完整列表
+
+| 任务类型 | 触发方式 | 使用 VCluster | 典型用途 |
+|---|---|---|---|
+| SQL 任务 | 周期调度 / 手动 | GP 或 AP | ETL、Ad-Hoc 查询、DDL 操作 |
+| Python 任务 | 周期调度 / 手动 | 不使用 | ZettaPark 数据处理、文件操作 |
+| Shell 任务 | 周期调度 / 手动 | 不使用 | 系统命令、文件处理 |
+| JDBC 任务 | 周期调度 / 手动 | 不使用 | 操作 MySQL/Hive/ClickHouse 等 |
+| 动态表任务 | 向导式创建 | GP 或 AP | 声明式增量计算 |
+| 离线同步任务 | 周期调度 | 同步型 | 全量/增量批量同步 |
+| 实时同步任务（单表） | 持续运行 | 同步型 | Kafka/MySQL/PG 实时写入 |
+| 多表实时 CDC | 持续运行 | 同步型 | 整库镜像、分库分表合并 |
+| 组合任务 | 周期调度 | 取决于子任务 | 封装多个任务统一调度 |
+| 虚拟节点 | 周期调度 | 不使用 | 占位节点，用于依赖编排 |
+
+---
+
+## 任务状态说明
+
+| 状态 | 含义 |
+|---|---|
+| 已提交，有修改 | 任务已提交到生产，但本地有未提交的修改 |
+| 已提交，无修改 | 生产版本与本地版本一致 |
+| 已下线 | 任务已停止调度 |
+| 未提交 | 仅在开发环境，未发布到生产 |
+
+---
+
+## 调度配置关键参数
+
+### Cron 表达式示例
+
+```
+# 每天凌晨 2 点执行
+0 2 * * *
+
+# 每小时执行一次
+0 * * * *
+
+# 每 5 分钟执行一次
+*/5 * * * *
+
+# 每月 1 号凌晨 1 点执行
+0 1 1 * *
+```
+
+### 依赖策略
+
+| 策略 | 说明 | 适用场景 |
+|---|---|---|
+| 默认 | 上游当天实例完成后触发下游 | 标准 ETL 链路 |
+| 向前 | 上游最近一个完成的实例触发 | 上游频率高于下游 |
+| 向前就近 | 上游最近且时间最接近的实例触发 | 时间对齐要求高 |
+
+---
+
+## 任务参数内置时间函数
+
+| 表达式 | 含义 | 示例（今天 2024-01-15） |
+|---|---|---|
+| `$[yyyy-MM-dd]` | 当天日期 | 2024-01-15 |
+| `$[yyyy-MM-dd, -1d]` | 昨天 | 2024-01-14 |
+| `$[yyyy-MM-dd, +1d]` | 明天 | 2024-01-16 |
+| `$[yyyyMM]` | 当月 | 202401 |
+| `$[yyyyMM, -1M]` | 上月 | 202312 |
+| `$[yyyy-MM-dd HH:mm:ss]` | 当前时间 | 2024-01-15 10:30:00 |
+| `$[HH:mm:ss]` | 当前时间（仅时分秒） | 10:30:00 |
+| `sys_plan_datetime` | 任务计划执行时间 | 系统内置参数 |
+
+---
+
+## 数据质量规则六大维度
+
+| 维度 | 说明 | 示例规则 |
+|---|---|---|
+| 完整性 | 字段非空率 | `user_id` 非空率 ≥ 99% |
+| 唯一性 | 主键/唯一键重复检测 | `order_id` 无重复 |
+| 一致性 | 跨表数据一致 | 订单表与明细表金额一致 |
+| 准确性 | 数值范围合理性 | `age` 在 0-150 之间 |
+| 有效性 | 格式/枚举值合法 | `status` 在 ['active','inactive'] 中 |
+| 及时性 | 数据更新时效 | 每天 8 点前数据已更新 |
+
+### 触发方式
+
+- **定时触发**：Cron 表达式，独立于任务调度
+- **调度任务触发**：绑定到某个 SQL/同步任务，任务完成后自动触发质量检测
+- **手动触发**：在 Studio 界面手动执行
+
+---
+
+## 数据目录（Data Catalog）功能
+
+### 表详情页六大 Tab
+
+| Tab | 内容 |
+|---|---|
+| 详情 | DDL 语句（一键复制）、权限管理入口 |
+| 字段 | 字段名/类型/描述/主键/标准化标签 |
+| 预览 | 100 行数据预览（需 SELECT 权限 + 指定 VCluster） |
+| 血缘 | 上下游表关系图（数据血缘） |
+| 作业 | 该表相关的查询历史 |
+| 上传 | 本地文件直接上传到表 |
+
+### 搜索支持的过滤条件
+
+- 对象类型：Table / View / Materialized View
+- 工作空间 / Schema
+- 创建时间范围
+- 负责人
+
+---
+
+## 运维监控告警
+
+### 内置告警规则
+
+| 规则 | 触发条件 |
+|---|---|
+| 周期任务实例运行失败 | 任务实例执行失败 |
+| 数据质量检测失败 | 质量规则校验不通过 |
+| Pipe 延迟告警 | Kafka/OSS Pipe 消费延迟超阈值 |
+| 同步任务失败 | 离线/实时同步任务异常 |
+| 自定义规则 | 用户自定义 SQL 条件 |
+
+### 告警通知渠道
+
+- 飞书 webhook
+- 企业微信 webhook
+- 邮件（部分版本）
+
+---
+
+## 数据同步支持的数据源（部分）
+
+### 离线同步（批量）
+
+MySQL · PostgreSQL · SQL Server · Oracle · Aurora · PolarDB · ClickHouse · Hive · HDFS · OSS/S3/COS · Lakehouse
+
+### 实时同步（CDC）
+
+MySQL（Binlog）· PostgreSQL（WAL）· Kafka（JSON/Avro/CSV）
+
+### 连接方式
+
+- 公网直连
+- SSH Tunnel（连接 VPC 内数据库）
+- 私网连接（PrivateLink）
+
+---
+
+## Python 任务中使用数据源
+
+Studio Python 任务内置 `clickzetta-dbutils` 工具包，可直接使用预配置的数据源：
+
+```python
+from clickzetta import dbutils
+
+# 使用预配置的 Lakehouse 数据源
+conn = dbutils.get_connection('my_lakehouse_datasource')
+cursor = conn.cursor()
+cursor.execute("SELECT * FROM my_schema.my_table LIMIT 10")
+rows = cursor.fetchall()
+print(rows)
+
+# 使用预配置的 MySQL 数据源
+mysql_conn = dbutils.get_connection('my_mysql_datasource')
+```

package/bin/skills/clickzetta-table-stream-pipeline/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: clickzetta-table-stream-pipeline
+description: |
+  搭建和管理 ClickZetta Table Stream 变更数据捕获管道，覆盖从源表配置、Stream 创建、
+  数据消费到增量 ETL 的端到端工作流。当用户说"创建 Table Stream"、"Table Stream CDC"、
+  "Table Stream 管道"、"Table Stream 增量消费"、"Stream 消费"时触发。
+  包含变更跟踪开启、模式选择、offset 管理、元数据字段使用、幂等消费等 ClickZetta 特有逻辑。
+  Keywords: table stream, CDC, change capture, incremental ETL, stream
+---
+
+# Table Stream 变更数据捕获工作流
+
+## 指令
+
+### 步骤 1：开启源表变更跟踪（必需前置）
+使用 `write_query` 开启源表的 change_tracking：
+```sql
+ALTER TABLE <source_table> SET PROPERTIES ('change_tracking' = 'true');
+```
+- 这是强制性前置步骤，不执行则 Stream 无法正确捕获变更
+- 使用 `read_query` 验证属性是否生效：
+```sql
+SHOW CREATE TABLE <source_table>;
+```
+
+### 步骤 2：创建 Table Stream
+使用 `write_query` 创建 Stream：
+```sql
+CREATE [ OR REPLACE ] TABLE STREAM <stream_name>
+  ON TABLE <source_table>
+  [ TIMESTAMP AS OF '<timestamp>' ]
+  [ COMMENT '<描述>' ]
+  WITH PROPERTIES (
+    'TABLE_STREAM_MODE' = 'STANDARD | APPEND_ONLY',
+    'SHOW_INITIAL_ROWS' = 'TRUE | FALSE'
+  );
+```
+关键参数选择：
+- **STANDARD 模式**：捕获 INSERT/UPDATE/DELETE，反映表当前状态 → 适用于数据同步、增量 ETL
+- **APPEND_ONLY 模式**：仅捕获 INSERT，保留所有历史插入记录 → 适用于审计、历史记录保留
+- **SHOW_INITIAL_ROWS = TRUE**：首次消费返回建 Stream 时表中已有行
+- **SHOW_INITIAL_ROWS = FALSE**（默认）：首次消费仅返回建 Stream 后的新变更
+- 可选：指定起始时间点
+```sql
+-- ⚠️ TIMESTAMP AS OF 功能在 ClickZetta 中不稳定，建议仅在必要时使用
+-- 如需使用，时间戳必须用 CAST() 形式
+CREATE TABLE STREAM <stream_name>
+  ON TABLE <source_table>
+  TIMESTAMP AS OF CAST('<timestamp>' AS TIMESTAMP)
+  WITH PROPERTIES ('TABLE_STREAM_MODE' = 'STANDARD');
+```
+
+### 步骤 3：准备目标表
+使用 `write_query` 或 `create_table` 创建与源表结构兼容的目标表：
+- 目标表列定义需包含源表的业务列
+- 建议额外添加元数据列（如 sync_version、sync_timestamp）用于追踪
+
+### 步骤 4：查询 Stream 数据（预览，不移动 offset）
+使用 `read_query` 预览 Stream 中的变更数据：
+```sql
+SELECT *, __change_type, __commit_version, __commit_timestamp
+FROM <stream_name>;
+```
+- 仅 SELECT 不会移动 offset
+- 元数据字段：`__change_type`（值：`INSERT` / `UPDATE_BEFORE` / `UPDATE_AFTER` / `DELETE`）、`__commit_version`、`__commit_timestamp`
+- UPDATE 产生两条记录：`UPDATE_BEFORE`（更新前旧值）和 `UPDATE_AFTER`（更新后新值），消费时通常忽略 `UPDATE_BEFORE`
+
+### 步骤 5：消费 Stream 数据（移动 offset）
+使用 `write_query` 执行 DML 操作消费数据：
+
+#### 方式 A：全量消费（INSERT INTO）
+```sql
+INSERT INTO <target_table>
+SELECT <columns> FROM <stream_name>;
+```
+
+#### 方式 B：幂等消费（MERGE，推荐）
+```sql
+MERGE INTO <target_table> t
+USING <stream_name> s
+ON t.<pk_column> = s.<pk_column>
+WHEN MATCHED AND s.__change_type = 'UPDATE_AFTER' THEN UPDATE SET t.col1 = s.col1, t.col2 = s.col2
+WHEN MATCHED AND s.__change_type = 'DELETE' THEN DELETE
+WHEN NOT MATCHED AND s.__change_type = 'INSERT' THEN INSERT (<columns>) VALUES (s.<columns>);
+```
+- DML 操作（INSERT/UPDATE/MERGE）会移动 offset
+- 即使使用 WHERE 条件过滤，所有数据的 offset 仍会移动
+- 推荐使用 MERGE 实现幂等性，避免重复消费导致数据重复
+
+### 步骤 6：验证消费状态
+使用 `read_query` 确认消费完成：
+```sql
+SELECT COUNT(*) FROM <stream_name>;
+```
+- 消费成功后 COUNT 应为 0 或仅包含新变更
+- 记录最后消费的 `__commit_version` 用于故障恢复
+
+## 模式选择速查
+
+| 需求 | 推荐模式 |
+|------|---------|
+| 数据同步（保持目标与源一致） | STANDARD |
+| 增量 ETL 流程 | STANDARD |
+| 审计所有插入记录 | APPEND_ONLY |
+| 历史记录保留 | APPEND_ONLY |
+
+## 性能优化要点
+
+- 只 SELECT 必要列，避免 `SELECT *`
+- 定期消费 Stream，避免数据累积
+- 高变更率表：更频繁消费；低变更率表：降低频率
+- 大型 Stream 可按主键范围拆分并行处理
+- 在源表上设置适当的数据保留期
+
+## 示例
+
+### 示例 1：订单表实时同步
+```
+1. write_query("ALTER TABLE orders SET PROPERTIES ('change_tracking' = 'true')")
+2. write_query("CREATE TABLE STREAM orders_stream ON TABLE orders WITH PROPERTIES ('TABLE_STREAM_MODE' = 'STANDARD', 'SHOW_INITIAL_ROWS' = 'FALSE')")
+3. write_query("CREATE TABLE orders_sync LIKE orders")  -- 或手动建表
+4. read_query("SELECT *, __commit_version, __commit_timestamp FROM orders_stream")  -- 预览
+5. write_query("MERGE INTO orders_sync t USING orders_stream s ON t.order_id = s.order_id WHEN MATCHED THEN UPDATE SET t.status = s.status, t.amount = s.amount WHEN NOT MATCHED THEN INSERT (order_id, status, amount) VALUES (s.order_id, s.status, s.amount)")
+6. read_query("SELECT COUNT(*) FROM orders_stream")  -- 验证 offset 已移动
+```
+
+### 示例 2：用户行为审计（保留全部插入历史）
+```
+1. write_query("ALTER TABLE user_actions SET PROPERTIES ('change_tracking' = 'true')")
+2. write_query("CREATE TABLE STREAM user_actions_audit_stream ON TABLE user_actions WITH PROPERTIES ('TABLE_STREAM_MODE' = 'APPEND_ONLY', 'SHOW_INITIAL_ROWS' = 'TRUE')")
+3. read_query("SELECT *, __commit_version, __commit_timestamp FROM user_actions_audit_stream")
+4. write_query("INSERT INTO user_actions_audit SELECT *, __commit_version AS audit_version, __commit_timestamp AS audit_time FROM user_actions_audit_stream")
+```
+
+## 故障排除
+
+Stream 不捕获变更：
+原因：源表未开启 change_tracking
+解决方案：执行 `ALTER TABLE <table> SET PROPERTIES ('change_tracking' = 'true')`，确认 DML 在 Stream 创建后执行
+
+无法区分变更类型：
+原因：未在 MERGE/INSERT 中过滤 `__change_type`，导致 `UPDATE_BEFORE` 旧值也被写入目标表
+解决方案：MERGE 时过滤 `__change_type IN ('UPDATE_AFTER', 'DELETE')`，忽略 `UPDATE_BEFORE` 记录
+
+消费后 offset 未移动：
+原因：仅使用 SELECT 查询，未执行 DML
+解决方案：必须通过 INSERT INTO / MERGE INTO / UPDATE 等 DML 操作消费数据
+
+重复消费导致目标表数据重复：
+原因：使用 INSERT INTO 而非 MERGE，或消费逻辑非幂等
+解决方案：改用 MERGE 语句；记录最后消费的 `__commit_version` 和 `__commit_timestamp` 用于断点恢复
+
+COMMENT 语法错误：
+原因：使用了 `COMMENT = '...'`（带等号）而非 `COMMENT '...'`
+解决方案：正确语法为 `COMMENT '注释内容'`，不带等号