@clickzetta/cz-cli-darwin-arm64 0.3.40 → 0.3.41

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

@@ -0,0 +1,90 @@
+---
+name: clickzetta-table-lineage
+description: |
+  表血缘可视化工具。从 ClickZetta information_schema.job_history 获取表依赖关系和成本数据，
+  导出 CSV 后嵌入 HTML 模板生成交互式血缘图。
+  当用户说"表血缘"、"table lineage"、"依赖关系图"、"数据流向"、"上下游分析"、
+  "血缘可视化"、"pipeline 可视化"时触发。
+---
+
+# 表血缘可视化工作流
+
+## 参考文件
+
+| 文件 | 说明 |
+|------|------|
+| `references/normalize_func.sql` | 归一化 UDF 定义（`__normalize_table` 和 `__normalize_objects`） |
+| `references/table_relation.sql` | 表关系查询 SQL（依赖 UDF，`{N}` 为天数占位符） |
+| `references/table_cost.sql` | 表成本查询 SQL（依赖 UDF，`{N}` 为天数占位符） |
+| `references/table_lineage_standalone.html` | 可视化 HTML 模板 |
+
+## 指令
+
+### 步骤 0：确定时间范围
+
+询问用户需要分析多长时间的血缘数据。默认 1 天。用户可指定天数如 1、7、30 等。
+SQL 中的 `{N}` 占位符将替换为用户指定的天数。
+
+### 步骤 1：创建归一化 UDF
+
+通过 cz-cli sql -f 执行 `references/normalize_func.sql`（已存在则跳过）。
+
+### 步骤 2：导出表关系数据
+
+读取 `references/table_relation.sql`，将 `{N}` 替换为用户指定的天数，通过 cz-cli sql --no-limit 执行，将结果保存为 `table_relation.csv`。
+
+### 步骤 3：导出表成本数据
+
+读取 `references/table_cost.sql`，将 `{N}` 替换为用户指定的天数，通过 cz-cli sql --no-limit 执行，将结果保存为 `table_cost.csv`。
+
+### 步骤 4：生成可视化页面
+
+1. 读取 `references/table_lineage_standalone.html` 作为模板
+2. 找到注释 `<!-- Data injection point` 所在行，在其**后面**插入：
+
+```html
+<script>
+window.LINEAGE_DATA = {
+  relation: `...table_relation.csv 原始文本...`,
+  cost: `...table_cost.csv 原始文本...`
+};
+</script>
+```
+
+3. 将结果写入目标文件（如 `table_lineage.html`），用浏览器打开。
+
+页面检测到 `window.LINEAGE_DATA` 后自动渲染，跳过文件选择。
+
+### 步骤 5：引导用户使用可视化功能
+
+- **点击节点**：高亮上游（橙色）和下游（青色）完整依赖路径
+- **搜索**：顶部搜索框过滤表名（快捷键 `/` 或 `Cmd+K`）
+- **缩放/平移**：鼠标滚轮缩放，拖拽平移，`F` 键适配屏幕
+- **右下角小地图**：点击或拖拽快速导航
+- **主题切换**：支持亮色/暗色主题
+- **悬停查看详情**：DML CRU/day、累计成本、查询成本等指标
+
+## 平台特有知识
+
+- `information_schema.job_history` 的 `input_objects` 和 `output_objects` 是逗号分隔的表名列表
+- 归一化通过 UDF `public.__normalize_table` 和 `public.__normalize_objects` 完成，首次使用需创建
+- Kafka 源表名格式：`xxx_$kafka$_yyy`，归一化为 `KAFKA.xxx`
+- Volume 源表名格式：`xxx_t_<32位hash>`，归一化为 `VOLUME.xxx`
+- `__delta__`、`__incr__`、`__DIRECTORY__EXTERNAL__` 中间表/目录被过滤
+- `COMPACTION_JOB` 类型作业不参与血缘构建
+- 有 output 的作业视为产出作业（DML），无 output 的视为查询作业
+- 成本数据为日均值：总量除以查询天数
+
+## 故障排除
+
+可视化为空
+原因：缺少作业运行历史
+解决方案：首先确认表关系和表成本 sql 正确运行，若结果为空，是正常现象。
+
+节点过多导致卡顿
+原因：浏览器渲染大量 DOM 节点
+解决方案：在 SQL 查询中添加 schema 过滤条件，缩小分析范围
+
+查询 job_history 超时
+原因：数据量过大
+解决方案：缩短时间窗口，如 `interval 30 day` 改为 `interval 1 day`

package/bin/skills/clickzetta-table-lineage/eval_cases.jsonl

@@ -0,0 +1 @@
+{"case_id":"001","type":"should_call","user_input":"分析过去 7 天的表血缘关系，生成可视化页面","expected_skill":"clickzetta-table-lineage"}

package/bin/skills/clickzetta-table-lineage/references/normalize_func.sql

@@ -0,0 +1,14 @@
+CREATE OR REPLACE FUNCTION public.__normalize_table(t STRING) 
+RETURNS STRING
+RETURN case when contains(t, '__delta__') or contains(t, '__incr__') then NULL -- remove delta/incr tables
+    when contains(t, '__DIRECTORY__EXTERNAL__') then NULL -- show volume directory
+    when contains(t, '_$kafka$_') then regexp_replace(t, r'([\w\.\-]+)_\$kafka\$_\w+$', r'KAFKA.$1') -- kafka pipe
+    when t rlike r'_t_\w{32}$' then regexp_replace(t, r'([\w\.]+)_t_\w{32}$', r'VOLUME.$1') -- volume
+    else t -- as it is
+    end
+;
+
+CREATE OR REPLACE FUNCTION public.__normalize_objects(ts ARRAY<STRING>) 
+RETURNS ARRAY<STRING>
+RETURN TRANSFORM(FILTER(ts, x -> x is not null and x != ''), x -> public.__normalize_table(x))
+;

package/bin/skills/clickzetta-table-lineage/references/table_cost.sql

@@ -0,0 +1,38 @@
+-- 根据过去 {N} 天的作业运行情况，计算表的产出代价和查询量
+with raw as (
+    select cru, split(input_objects, ',') as input, split(output_objects, ',') as output
+    from information_schema.job_history
+    where start_time>=now() - interval {N} day
+),
+normalized as (
+    select cru,
+        public.__normalize_objects(input) as input,
+        public.__normalize_objects(output) as output    
+    from raw
+),
+as_output (
+    select table_name, sum(cru) as dml_cru, count(1) as dml_job_cnt
+    from (
+        select explode(output) as table_name, cru
+        from normalized
+        where output is not null and size(output) > 0 -- 有 output 的作业认为是产出作业
+    )
+    group by table_name
+),
+as_input (
+    select table_name, sum(cru) as query_cru, count(1) as query_job_cnt
+    from (
+        select explode(input) as table_name, cru
+        from normalized
+        where output is null or size(output) == 0 -- 没有 output 的作业认为是查询作业
+    )
+    where not contains(table_name, '__dql__') -- 过滤掉 show tables/pipes 之类查询
+        and not starts_with(table_name, 'system_meta_warehouse.information_schema.') -- 过滤掉查询 information_schema
+    group by table_name
+)
+select coalesce(a.table_name, b.table_name) as table_name,
+    -- per day
+    round(dml_cru / {N}, 3) as dml_cru, dml_job_cnt / {N} as dml_job_cnt,
+    round(query_cru / {N}, 3) as query_cru, query_job_cnt / {N} as query_job_cnt
+from as_output a full join as_input b on a.table_name = b.table_name
+;