@clickzetta/cz-cli-darwin-x64 0.3.17 → 0.3.19

package/bin/skills/clickzetta-dw-modeling/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: clickzetta-dw-modeling
+description: |
+  ClickZetta Lakehouse 数仓建模向导。先自主探索用户的数据现状，再给出有依据的
+  具体建议让用户选择，而不是让用户填空回答问卷。
+  覆盖三种分层模式：传统数仓分层（ODS/DWD/DWS/ADS）、大奖牌架构（Bronze/Silver/Gold）、
+  混合模式。数据管道与建模一体化设计，DDL 和管道配置同步输出。
+  核心原则：聚合计算层使用 Dynamic Table，不推荐物化视图。
+  当用户说"数仓建模"、"分层设计"、"建模方案"、"ODS/DWD/DWS"、"Medallion"、
+  "Bronze/Silver/Gold"、"事实表"、"维度表"、"宽表设计"、"星型模型"、"雪花模型"、
+  "分层架构"、"数据分层"、"建模向导"、"怎么设计表结构"、"数仓架构"、
+  "数据管道设计"、"数据流转"、"端到端数仓搭建"时触发。
+  Keywords: data warehouse, modeling, star schema, medallion, ODS, DWD, DWS, ADS, layering
+---
+
+# ClickZetta 数仓建模向导
+
+阅读 [references/modeling-patterns.md](references/modeling-patterns.md) 了解各分层模式的详细模板。
+
+---
+
+## 工作模式：先探索，再建议
+
+**不要问问卷式问题。先动手看数据，再给出有依据的选择题。**
+
+用户最多只需要回答 2 个问题：
+1. 选择给出的方案选项（A/B/C）
+2. 补充看不到的信息（业务用途、查询场景）
+
+---
+
+## 第一阶段：自主探索数据现状
+
+收到建模需求后，立即执行以下探索，**不要先问用户任何问题**：
+
+```sql
+-- Step 1: 看有哪些 schema
+SHOW SCHEMAS;
+
+-- Step 2: 看各 schema 下的表（对每个看起来有业务数据的 schema 执行）
+SHOW TABLES IN <schema>;
+
+-- Step 3: 查表大小和行数（先 describe_table 确认字段名）
+SELECT table_schema, table_name, table_type,
+       ROUND(bytes/1024.0/1024/1024, 2) AS size_gb,
+       row_count,
+       last_modify_time
+FROM information_schema.tables
+WHERE table_type = 'MANAGED_TABLE'
+ORDER BY bytes DESC NULLS LAST
+LIMIT 20;
+
+-- Step 4: 对最大的 2-3 张表抽样，了解字段和数据特征
+SELECT * FROM <schema>.<table> LIMIT 5;
+```
+
+**探索时的判断逻辑：**
+
+| 观察到的特征 | 推断 |
+|---|---|
+| 表名含 order/user/product/trade | 业务库原始数据，适合做 ODS/Bronze |
+| 表名含 log/event/track/click | 埋点/日志数据，数据量大，需要分区 |
+| 表名含 dw/ods/dwd/dws/ads | 已有分层，评估现有结构是否合理 |
+| 表名含 tmp/temp/bak | 临时表，不纳入建模范围 |
+| 字段含 _op/_ts/binlog | CDC 同步过来的数据 |
+| 字段含 event_time/log_time | 时序数据，按时间分区 |
+| 单表 > 10GB | 需要分区+分桶 |
+
+---
+
+## 第二阶段：给出有依据的建议
+
+基于探索结果，向用户呈现三部分内容：
+
+### 1. 数据现状摘要（自主总结，不问用户）
+
+```
+我看了一下你的数据：
+- `raw` schema：orders(2.3GB/1200万行)、users(450MB)、products(120MB)
+  → 字段特征像是从 MySQL 同步的业务库，orders 有 _op/_ts 字段（CDC 接入）
+- `events` schema：user_events(18GB/8亿行)
+  → 字段含 event_time、event_type，是埋点日志数据
+- 没有发现已有的分层结构
+```
+
+### 2. 方案选项（给 A/B 或 A/B/C，不超过 3 个）
+
+```
+基于以上数据，建议两个方向：
+
+A. 传统数仓分层
+   raw → ODS（现有数据直接复用）
+   新建 DWD（清洗标准化）+ DWS（聚合，用 Dynamic Table）+ ADS（指标输出）
+   适合：BI 报表为主，有明确的指标体系需求
+
+B. 大奖牌架构（Medallion）
+   raw → Bronze（现有数据直接复用）
+   新建 Silver（标准化）+ Gold（指标，用 Dynamic Table）
+   适合：多场景复用，既做 BI 又做数据科学
+```
+
+### 3. 只问一个问题
+
+```
+你们主要用这些数据做什么？
+- BI 报表（固定报表，指标体系明确）→ 推荐 A
+- 多场景（报表+分析+数据科学）→ 推荐 B
+- 实时看板（分钟级延迟）→ 告诉我，方案会有调整
+```
+
+---
+
+## 第三阶段：方案确认后的完整输出
+
+用户选择方向后，**一次性给出完整方案**，不再追问：
+
+### 分层结构设计
+
+根据选择的模式，给出各层定义、表类型推荐：
+
+**传统分层表类型：**
+
+| 层次 | 推荐表类型 | 说明 |
+|---|---|---|
+| ODS | 内部表 | 贴源，不转换 |
+| DWD | 内部表 | 清洗标准化 |
+| DWS | **Dynamic Table** | 增量聚合，自动刷新 |
+| ADS | **Dynamic Table** | 面向应用，按需刷新 |
+
+**Medallion 表类型：**
+
+| 层次 | 推荐表类型 | 说明 |
+|---|---|---|
+| Bronze | 内部表 | 零转换，保留原始 |
+| Silver | 内部表 或 Dynamic Table | 清洗标准化 |
+| Gold | **Dynamic Table** | 聚合指标，自动刷新 |
+
+> ⚠️ 聚合层**不推荐物化视图**，使用 Dynamic Table：CBO 增量计算，只刷新变化分区，支持 Time Travel。
+
+### 数据接入管道
+
+根据探索到的数据源特征，直接给出管道推荐（不再问用户）：
+
+| 数据源特征 | 推荐管道 | 对应 skill |
+|---|---|---|
+| 有 _op/_ts 字段（CDC） | CDC 同步 | `clickzetta-cdc-sync-pipeline` |
+| Kafka 消息数据 | Kafka Pipe | `clickzetta-kafka-ingest-pipeline` |
+| OSS/S3 文件 | OSS Pipe | `clickzetta-oss-ingest-pipeline` |
+| 普通数据库表（无 CDC 标记） | 批量同步 | `clickzetta-batch-sync-pipeline` |
+
+**ODS/Bronze 层表结构调整（根据管道类型）：**
+- CDC 接入 → 保留 `_op`（I/U/D）和 `_ts` 字段，不要删除
+- 批量接入 → 增加 `dw_batch_date` 标记批次
+- Kafka 接入 → JSON 消息用 `STRING` 或 `MAP<STRING,STRING>` 存储
+
+### 分区与分桶策略
+
+根据探索到的表大小自动推荐：
+
+```sql
+-- 单表 < 1GB：不分区
+-- 单表 1GB-100GB：按天分区
+PARTITIONED BY (days(event_date))
+
+-- 单表 > 100GB：按天分区 + 分桶
+PARTITIONED BY (days(event_date))
+CLUSTERED BY (user_id) INTO 32 BUCKETS
+```
+
+注意：ClickZetta 分区用 `PARTITIONED BY (days(col))`，不是 `PARTITIONED BY (col)`。
+
+### 层间流转
+
+```
+ODS/Bronze → DWD/Silver：SQL 任务（Studio 调度，清洗逻辑需手动控制）
+DWD/Silver → DWS/Gold：Dynamic Table（TARGET_LAG 控制延迟，自动增量）
+DWS → ADS：Dynamic Table 或直接查询
+```
+
+加载 `clickzetta-sql-pipeline-manager` 获取 Dynamic Table 详细语法。
+
+### 数据质量卡点
+
+| 层次 | 检查重点 | 时机 |
+|---|---|---|
+| ODS/Bronze | NULL 比例、CDC _op 分布 | 入库后 |
+| DWD/Silver | 唯一性、关联完整性（LEFT JOIN 验证匹配率） | ETL 后 |
+| DWS/Gold/ADS | 指标环比异常、汇总一致性 | Dynamic Table 刷新后 |
+
+### 调度 DAG
+
+```
+日批场景：
+数据同步（ODS 接入）→ DWD 清洗任务 → 数据质量检查
+                                          ↓
+                              DWS/Gold（Dynamic Table 自动刷新，无需调度）
+
+实时场景：
+CDC/Kafka 持续写入 Bronze → Silver（TARGET_LAG='10min'）→ Gold（TARGET_LAG='1h'）
+```
+
+### DDL 模板
+
+加载 `clickzetta-sql-syntax-guide` 确认语法，生成各层 DDL：
+
+```sql
+-- ODS/Bronze（以 CDC 接入为例）
+CREATE TABLE IF NOT EXISTS ods.orders (
+    order_id       BIGINT,
+    user_id        BIGINT,
+    amount         DECIMAL(18, 2),
+    status         STRING,
+    created_at     TIMESTAMP,
+    _op            STRING,    -- CDC 操作类型：I/U/D
+    _ts            TIMESTAMP, -- 变更时间
+    dw_insert_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+)
+PARTITIONED BY (days(created_at))
+COMMENT 'ODS 订单原始表，贴源不转换';
+
+-- DWD/Silver
+CREATE TABLE IF NOT EXISTS dwd.fact_orders (
+    order_id       BIGINT,
+    user_id        BIGINT,
+    amount         DECIMAL(18, 2),
+    status_code    INT,
+    order_date     DATE,
+    dw_insert_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+)
+PARTITIONED BY (days(order_date))
+CLUSTERED BY (user_id) INTO 32 BUCKETS
+COMMENT 'DWD 订单事实表，清洗标准化';
+
+-- DWS/Gold（Dynamic Table，不用物化视图）
+CREATE DYNAMIC TABLE IF NOT EXISTS dws.user_order_daily
+  REFRESH interval 1 HOUR
+  VCLUSTER default_ap
+AS
+SELECT
+    user_id,
+    order_date,
+    COUNT(order_id)  AS order_cnt,
+    SUM(amount)      AS total_amount,
+    AVG(amount)      AS avg_amount
+FROM dwd.fact_orders
+WHERE status_code = 1
+GROUP BY user_id, order_date;
+```
+
+---
+
+## 核心原则
+
+1. **先探索数据，再给建议**——不问问卷，看完数据再说
+2. **给选择题，不给填空题**——用户选 A/B，不要让用户凭空描述
+3. **聚合层用 Dynamic Table，不用物化视图**
+4. **建模和管道一体**——DDL 和管道配置同步输出
+5. **分区用转换函数**：`days(col)` 不是 `col`
+6. **ODS/Bronze 零转换**，保留原始数据方便回溯

package/bin/skills/clickzetta-dw-modeling/eval_cases.jsonl

@@ -0,0 +1,4 @@
+{"case_id":"001","type":"should_call","user_input":"帮我做数仓分层设计","expected_skill":"clickzetta-dw-modeling","expected_output_contains":["分层"]}
+{"case_id":"002","type":"should_call","user_input":"ODS/DWD/DWS/ADS 分层怎么设计","expected_skill":"clickzetta-dw-modeling","expected_output_contains":["ODS","DWD","DWS"]}
+{"case_id":"003","type":"should_call","user_input":"Medallion 架构 Bronze/Silver/Gold 怎么搭建","expected_skill":"clickzetta-dw-modeling","expected_output_contains":["Bronze","Silver","Gold"]}
+{"case_id":"004","type":"should_call","user_input":"星型模型和雪花模型怎么选","expected_skill":"clickzetta-dw-modeling","expected_output_contains":["星型","雪花"]}

package/bin/skills/clickzetta-dw-modeling/references/modeling-patterns.md

@@ -0,0 +1,100 @@
+# 数仓建模模式参考
+
+## 传统数仓分层详细说明
+
+### 分层职责
+
+```
+ODS（Operational Data Store）
+├── 贴源存储，不做业务转换
+├── 保留原始字段名和类型
+├── 增加 dw_insert_time、dw_source 等元数据字段
+└── 按时间分区，支持增量同步
+
+DWD（Data Warehouse Detail）
+├── 数据清洗：去重、NULL 处理、格式标准化
+├── 维度退化：将常用维度字段冗余到事实表
+├── 业务规则：状态码映射、金额单位统一
+└── 建立主键约束（逻辑主键，ClickZetta 不强制）
+
+DWS（Data Warehouse Summary）
+├── 轻度聚合：按天/周/月汇总
+├── 使用 Dynamic Table 自动增量刷新
+├── 面向主题域：用户域、商品域、交易域
+└── 不直接对外提供查询（由 ADS 层封装）
+
+ADS（Application Data Store）
+├── 面向具体应用/报表的宽表
+├── 使用 Dynamic Table 或直接查询 DWS
+└── 字段命名业务友好
+```
+
+### 命名规范建议
+
+```
+Schema 命名：ods_<业务域> / dwd_<业务域> / dws / ads
+表命名：
+  ODS：ods_<源系统>_<表名>（如 ods_mysql_orders）
+  DWD：dwd_<主题>_<粒度>（如 dwd_trade_order_detail）
+  DWS：dws_<主题>_<维度>_<周期>（如 dws_user_order_1d）
+  ADS：ads_<应用>_<指标>（如 ads_report_gmv_daily）
+```
+
+---
+
+## 大奖牌架构（Medallion）详细说明
+
+### 分层职责
+
+```
+Bronze（铜牌层）
+├── 原始数据，零转换原则
+├── 支持多种格式：结构化/半结构化/非结构化
+├── 保留所有历史版本（Time Travel）
+└── 数据来源标记（source_system、ingestion_time）
+
+Silver（银牌层）
+├── 可信数据：去重、清洗、标准化
+├── 跨源整合：统一字段命名和类型
+├── 业务实体识别：用户、订单、商品
+└── 可直接用于数据科学和探索性分析
+
+Gold（金牌层）
+├── 业务就绪数据：聚合指标、宽表
+├── 使用 Dynamic Table 自动刷新
+├── 面向 BI 工具和应用系统
+└── 语义清晰，字段命名业务友好
+```
+
+### Schema 命名建议
+
+```
+bronze.<source>_<entity>   -- 如 bronze.mysql_orders
+silver.<entity>            -- 如 silver.orders
+gold.<domain>_<metric>     -- 如 gold.trade_gmv_daily
+```
+
+---
+
+## Dynamic Table vs 物化视图对比
+
+| 特性 | Dynamic Table | 物化视图 |
+|---|---|---|
+| 刷新机制 | CBO 增量计算，只刷新变化分区 | 全量或手动增量 |
+| 调度方式 | TARGET_LAG 自动控制 | 需手动配置调度 |
+| Time Travel | ✅ 支持 | ❌ 不支持 |
+| 数据恢复 | ✅ RESTORE TABLE | ❌ 不支持 |
+| 语法复杂度 | 简单，类似 CREATE TABLE | 较复杂 |
+| 推荐场景 | **新项目首选** | 遗留项目兼容 |
+
+**结论：新建项目一律使用 Dynamic Table，不使用物化视图。**
+
+---
+
+## 常见建模陷阱
+
+1. **过度规范化**：DWD 层不要拆太细，适当冗余维度字段，减少下游 JOIN
+2. **分区粒度过细**：按小时分区会产生大量小文件，日批场景用按天分区
+3. **ADS 层直接写 SQL**：ADS 层应该用 Dynamic Table，不要让 BI 工具直接跑复杂 SQL
+4. **忽略数据质量**：ODS 层入库时就应该检查 NULL 比例，不要等到 DWS 层才发现问题
+5. **Bronze 层做转换**：Bronze 层一旦做了转换，原始数据就丢失了，回溯困难

package/bin/skills/clickzetta-dynamic-table/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: clickzetta-dynamic-table
+description: |
+  ClickZetta Dynamic Table（动态表）使用指南，覆盖动态表的创建、修改、增量计算配置和性能优化。
+  包含 DT 声明策略（静态分区 DT vs 动态分区 DT）、SQL 支持矩阵、增量配置参考、刷新历史查询、
+  ALTER 操作指南，以及维度表 JOIN、性能优化、非分区表风险等最佳实践。
+  当用户说"Dynamic Table"、"动态表"、"自动刷新"、"增量刷新"、"物化视图"、
+  "REFRESH interval"、"CREATE DYNAMIC TABLE"、
+  "数据管道自动化"、"增量计算"、"自动物化"、"定时刷新"、
+  "依赖刷新"、"SESSION_CONFIGS"、"静态分区DT"、"动态分区DT"、
+  "状态表"、"state table"、"MERGE INTO"、"Table Stream"时触发。
+  Keywords: dynamic table, incremental refresh, REFRESH interval, materialized, auto-refresh pipeline, SESSION_CONFIGS, partitioned DT, state table, MERGE INTO
+---
+
+# Dynamic Table 使用指南 — 目录索引
+
+## 快速入门
+
+```sql
+-- 1. 创建 Dynamic Table（自动调度刷新）
+CREATE DYNAMIC TABLE IF NOT EXISTS silver.orders_daily
+REFRESH INTERVAL 60 MINUTE vcluster default
+AS
+SELECT DATE(created_at) AS order_date, region, SUM(amount) AS total_amount
+FROM bronze.raw_orders
+GROUP BY 1, 2;
+
+-- 2. 查看状态与刷新历史
+DESC DYNAMIC TABLE silver.orders_daily;
+SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'orders_daily' LIMIT 10;
+
+-- 3. 手动触发刷新
+REFRESH DYNAMIC TABLE silver.orders_daily;
+
+-- 4. 列出所有 Dynamic Table
+SHOW TABLES IN silver WHERE is_dynamic;
+-- 返回列：schema_name, table_name, is_view, is_materialized_view, is_external, is_dynamic
+-- ⚠️ 列名是 table_name（不是 name），过滤用 WHERE table_name = 'xxx'
+
+-- 5. 查看指定表是否为动态表
+SHOW TABLES IN silver WHERE table_name = 'orders_daily';
+```
+
+### 调度方式
+
+| 方式 | 语法 | 适用场景 |
+|---|---|---|
+| 自动调度 | `REFRESH INTERVAL 10 MINUTE vcluster <name>` | 系统按间隔自动刷新（推荐） |
+| 指定开始时间 | `REFRESH START WITH TIMESTAMP '2025-01-01 00:00:00' INTERVAL 1 HOUR vcluster <name>` | 从指定时间开始调度 |
+| 手动触发 | `REFRESH DYNAMIC TABLE my_dt;` | 外部调度器触发，适合静态分区 DT |
+
+INTERVAL 支持的单位：`SECOND`、`MINUTE`、`HOUR`、`DAY`，最小值为 1 分钟。
+
+> 建议使用 GP 型集群刷新动态表。动态表刷新过程中会自动执行小文件合并，AP 型集群不支持此功能。
+> ⚠️ **VCluster 类型限制**：创建动态表时如果指定了 AP 型集群（如 `default_ap`），刷新仍可执行但不会进行小文件合并，长期运行可能导致查询性能下降。建议始终使用 GP 型集群（如 `default`）。
+
+### 开启增量刷新的前提
+
+源表需开启变更跟踪：
+```sql
+ALTER TABLE bronze.raw_orders SET PROPERTIES ('change_tracking' = 'true');
+```
+
+### 增量刷新 vs 全量刷新
+
+通过 `SHOW DYNAMIC TABLE REFRESH HISTORY` 的 `refresh_mode` 字段可查看刷新模式：
+- `INCREMENTAL`：增量刷新（仅处理变更数据，高效）
+- `FULL`：全量刷新（重新计算所有数据）
+- `NO_DATA`：无数据变更，跳过刷新
+
+**触发全量刷新的条件**：
+| 条件 | 说明 |
+|---|---|
+| 源表未开启 `change_tracking` | 系统无法识别增量数据 |
+| 查询含不支持增量的算子 | 如某些复杂 JOIN、子查询 |
+| `CREATE OR REPLACE` 修改了计算逻辑 | 如修改 WHERE、GROUP BY、JOIN key |
+| 手动设置强制全量 | `SET cz.optimizer.incremental.force.full.refresh = true` |
+| 维度表变更 | 被 JOIN 的维度表数据变化时，增量结果可能不一致 |
+
+**确认是否支持增量刷新**：
+```sql
+SET cz.optimizer.explain.can.incrementalize = true;
+EXPLAIN REFRESH DYNAMIC TABLE my_dt;
+-- 查看 CanBeIncrementalized 字段：Yes = 支持增量，No = 不支持（会给出原因）
+```
+
+---
+
+## dt-creator/
+创建 Dynamic Table 的参考资料（声明策略、SQL 支持矩阵、增量配置、刷新历史查询）。
+
+## dynamic-table-alter/
+修改 Dynamic Table 的结构和属性（suspend/resume、加列删列、改刷新间隔等）。
+
+## best-practices/
+Dynamic Table 最佳实践与避坑指南（维度表 JOIN 场景、性能优化、非分区表风险告警）。
+
+---
+
+## 常见问题排障
+
+| 问题 | 原因 | 解决方案 |
+|---|---|---|
+| 刷新一直是 FULL 模式 | 源表未开启 change_tracking，或查询含不支持增量的算子 | 开启 change_tracking；用 `EXPLAIN REFRESH` 检查 |
+| 刷新延迟超过预期 | VCluster 资源不足，或查询复杂度高 | 升级 VCluster 规格；拆分管道 |
+| `SUSPEND` 后数据不更新 | 已暂停 | 执行 `ALTER DYNAMIC TABLE ... RESUME` |
+| 依赖链中下游不刷新 | 上游 Dynamic Table 刷新失败 | 先修复上游，再手动 `REFRESH` 下游 |
+| 删除报错 | 有下游 Dynamic Table 依赖 | 先删除下游，再删除上游 |
+| 增量结果与全量不一致 | 维度表变更未触发重算 | 执行全量刷新：`SET cz.optimizer.incremental.force.full.refresh = true` |
+| 状态表损坏 | 系统异常 | `SET cz.optimizer.incremental.rebuild.rule.based.state.table = true` |
+| 手动 REFRESH 后历史未显示 | 刷新历史有短暂延迟 | 等待几秒后重新查询 `SHOW DYNAMIC TABLE REFRESH HISTORY` |
+| AP 集群刷新后查询变慢 | AP 集群不支持小文件合并 | 改用 GP 型集群（`CREATE OR REPLACE` 重建） |