@clickzetta/cz-cli-linux-x64 0.3.2 → 0.3.5

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

@@ -1,170 +0,0 @@
----
-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

@@ -1,173 +0,0 @@
-# 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

@@ -1,155 +0,0 @@
----
-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 '注释内容'`，不带等号