@clickzetta/cz-cli-darwin-arm64 0.3.81 → 0.3.83

package/bin/skills/clickzetta-dynamic-table/sql-to-dt/references/sql2dt-conversion-rules.md

@@ -0,0 +1,225 @@
+# SQL → Dynamic Table 转换规则
+
+你是一个 SQL 转换专家。给定一个 Hive/Spark SQL 的 CREATE TABLE DDL 和对应的 INSERT OVERWRITE 语句，你需要按以下规则将它们合并为一个 Dynamic Table DDL。
+
+## 总体转换公式
+
+```
+输入1: CREATE TABLE schema.table_name (...) PARTITIONED BY (...) ...
+输入2: INSERT OVERWRITE TABLE schema.table_name PARTITION(...) SELECT ... FROM ...
+输出:  CREATE OR REPLACE DYNAMIC TABLE schema.table_name (...) PARTITIONED BY (...) ... AS SELECT ... FROM ...
+```
+
+核心思想：把 CREATE TABLE 的结构定义 + INSERT OVERWRITE 的查询逻辑，合并成一个 `CREATE OR REPLACE DYNAMIC TABLE ... AS SELECT ...` 语句。
+
+## 第一步：解析 CREATE TABLE DDL
+
+从 DDL 中提取以下信息：
+
+1. **表名**（含 schema）：`schema.table_name`
+2. **普通列**：列名、数据类型、COMMENT（保持原始缩进格式）
+3. **分区列**：PARTITIONED BY 中的列名、数据类型、COMMENT
+4. **存储格式**：STORED AS PARQUET/ORC/AVRO 等
+5. **表属性**：TBLPROPERTIES 或 WITH PROPERTIES 中的键值对
+6. **分桶信息**：CLUSTERED BY / SORTED BY / RANGE CLUSTERED BY / HASH CLUSTERED BY
+7. **生命周期**：LIFECYCLE N
+8. **连接信息**：CONNECTION schema.connection_name
+9. **位置信息**：LOCATION 'path'
+
+## 第二步：解析 INSERT OVERWRITE 语句
+
+从 INSERT 语句中提取：
+
+1. **目标表名**：用于自引用检测
+2. **分区类型**：
+   - 动态分区：`PARTITION (col1, col2)` — 列名无值
+   - 静态分区：`PARTITION (col1='value1', col2=value2)` — 列名有值
+   - 混合分区：`PARTITION (static_col='value', dynamic_col)` — 部分有值
+3. **SELECT 查询**：完整的查询逻辑（含 WHERE、JOIN、GROUP BY 等）
+4. **CTE（WITH 子句）**：如果有，保留完整的 WITH ... AS (...) 结构
+5. **前置语句**：SET 语句、CREATE TEMPORARY FUNCTION 等（保留）
+
+### 需要过滤的语句
+
+从 INSERT 文件中移除：
+- `ALTER TABLE ... ADD PARTITION ...`
+- `ALTER TABLE ... DROP PARTITION ...`
+- 所有 `ALTER TABLE` 开头的语句
+- `ANALYZE TABLE` 语句
+- SQL 注释（`--` 和 `/* */`）
+
+## 第三步：组装 Dynamic Table DDL
+
+按以下顺序组装输出：
+
+```sql
+-- 可选：如果需要删除已存在的同名表，请取消下一行的注释
+-- DROP TABLE IF EXISTS schema.table_name;
+
+CREATE SCHEMA IF NOT EXISTS schema;        -- 仅当表名含 schema 时
+CREATE OR REPLACE DYNAMIC TABLE schema.table_name (
+    col1 BIGINT COMMENT '...',             -- 普通列（保持原始格式）
+    col2 STRING COMMENT '...',
+    part_col1 STRING COMMENT '...'         -- 分区列追加在普通列后面
+)
+PARTITIONED BY (part_col1, part_col2)      -- 仅列名，不含类型
+[CLUSTERED BY (...) [SORTED BY (...)] [INTO N BUCKETS]]
+[STORED AS PARQUET]
+TBLPROPERTIES ('key' = 'value')            -- 合并模板属性和原始属性
+[LIFECYCLE N]
+[CONNECTION schema.connection_name]
+[LOCATION 'original_path_dt']             -- 原路径加 _dt 后缀
+AS
+SELECT查询;                                -- 来自 INSERT OVERWRITE 的查询
+```
+
+### 关键规则
+
+1. **列定义**：普通列 + 分区列合并到一个括号内，保持原始缩进
+2. **PARTITIONED BY**：只写列名，不写类型（与 CREATE TABLE 不同）
+3. **CREATE SCHEMA**：如果表名含 `.`（如 `kscdm.table_name`），在 DDL 前加 `CREATE SCHEMA IF NOT EXISTS kscdm;`
+4. **LOCATION**：原路径加 `_dt` 后缀
+5. **DROP 语句**：注释掉的 `DROP TABLE IF EXISTS` 放在最前面
+
+## 第四步：静态分区注入
+
+当 INSERT OVERWRITE 使用静态分区（`PARTITION(col=value)`）时，需要将分区值注入到 SELECT 子句中。
+
+### 注入规则
+
+在 SELECT 的最后一个列之后、FROM 之前，按 DDL 中分区列的定义顺序追加：
+
+```sql
+-- 原始 SELECT
+SELECT col1, col2 FROM source_table
+
+-- 注入后（假设 PARTITION(year=2024, month='January')）
+SELECT col1, col2,
+    2024 AS year,
+    'January' AS month
+FROM source_table
+```
+
+### 值类型智能处理
+
+注入时根据值的类型决定是否加引号：
+
+| 值类型 | 判断规则 | 处理 | 示例 |
+|--------|----------|------|------|
+| 已有引号 | 以 `'` 或 `"` 开头结尾 | 保持原样 | `'hello'` → `'hello'` |
+| NULL | 值为 `NULL`（不区分大小写） | 不加引号 | `NULL` |
+| 布尔值 | `true` / `false`（不区分大小写） | 不加引号 | `true` |
+| 数字 | 可被 `float()` 解析 | 不加引号 | `123`, `-45.67`, `1.23e-4` |
+| SESSION_CONFIGS | 包含 `SESSION_CONFIGS(` | 不加引号 | `SESSION_CONFIGS()['dt.args.ds']` |
+| 函数调用 | 匹配 `标识符(...)` 且括号平衡 | 不加引号 | `CURRENT_DATE()`, `YEAR(col)` |
+| 字符串 | 以上都不匹配 | 加单引号，内部 `'` 转义为 `''` | `hello` → `'hello'` |
+
+### UNION ALL 处理
+
+如果 SELECT 包含 UNION ALL，每个分支都要独立注入分区列：
+
+```sql
+SELECT col1, col2,
+    2024 AS year
+FROM table_a
+UNION ALL
+SELECT col1, col2,
+    2024 AS year
+FROM table_b
+```
+
+### CTE + UNION ALL
+
+如果有 WITH 子句，先分离 CTE 部分，只对主查询中的 UNION 分支注入。
+
+### 已存在的分区列
+
+如果 SELECT 中已经包含了某个分区列（通过 `AS alias` 或末尾标识符检测），则跳过该列的注入，避免重复。
+
+## 第五步：日期函数后处理
+
+生成 DDL 后，对整个 DDL 文本做一次全局替换：
+
+| 原始形式 | 替换为 |
+|----------|--------|
+| `DATE_SUB(expr, INTERVAL N DAY)` | `sub_days(expr, N)` |
+| `DATE_ADD(expr, INTERVAL N DAY)` | `sub_days(expr, -N)` |
+
+这一步确保最终输出统一使用 `sub_days` 函数。
+
+> 注意：在 SQL 引擎中，`SUB_DAYS` 是 `DATE_SUB` 的别名，两者等价。统一使用 `sub_days` 是为了保持输出一致性。
+
+## 第六步：表属性模板合并
+
+默认模板属性：`data_lifecycle = 15`
+
+合并规则：
+- 模板属性作为基础
+- 原始 DDL 中的 TBLPROPERTIES 覆盖同名模板属性
+- 最终结果写入 TBLPROPERTIES
+
+```sql
+-- 模板: data_lifecycle=15
+-- 原始DDL: TBLPROPERTIES('compression'='snappy', 'data_lifecycle'='30')
+-- 合并结果:
+TBLPROPERTIES ('data_lifecycle' = '30', 'compression' = 'snappy')
+-- data_lifecycle 保留原始值 30，compression 来自原始DDL
+```
+
+## 完整示例
+
+### 输入1：DDL
+```sql
+CREATE TABLE IF NOT EXISTS sales_data (
+    id BIGINT COMMENT '销售记录ID',
+    product_name STRING COMMENT '产品名称',
+    sales_amount DECIMAL(12,2) COMMENT '销售金额'
+)
+PARTITIONED BY (
+    year INT COMMENT '年份',
+    month INT COMMENT '月份'
+)
+STORED AS PARQUET
+LOCATION '/data/warehouse/sales_data';
+```
+
+### 输入2：INSERT OVERWRITE
+```sql
+INSERT OVERWRITE TABLE sales_data
+PARTITION (year, month)
+SELECT
+    s.id,
+    s.product_name,
+    s.price * s.quantity AS sales_amount,
+    YEAR(s.sales_date) AS year,
+    MONTH(s.sales_date) AS month
+FROM raw_sales s
+WHERE s.status = 'completed';
+```
+
+### 输出：Dynamic Table DDL
+```sql
+-- 可选：如果需要删除已存在的同名表，请取消下一行的注释
+-- DROP TABLE IF EXISTS sales_data;
+
+CREATE OR REPLACE DYNAMIC TABLE sales_data (
+    id BIGINT COMMENT '销售记录ID',
+    product_name STRING COMMENT '产品名称',
+    sales_amount DECIMAL(12,2) COMMENT '销售金额',
+    year INT COMMENT '年份',
+    month INT COMMENT '月份'
+)
+PARTITIONED BY (year, month)
+STORED AS PARQUET
+TBLPROPERTIES ('data_lifecycle' = '15')
+LOCATION '/data/warehouse/sales_data_dt'
+AS
+SELECT
+    s.id,
+    s.product_name,
+    s.price * s.quantity AS sales_amount,
+    YEAR(s.sales_date) AS year,
+    MONTH(s.sales_date) AS month
+FROM raw_sales s
+WHERE s.status = 'completed';
+```

package/bin/skills/clickzetta-dynamic-table/sql-to-dt/references/sql2dt-placeholder-rules.md

@@ -0,0 +1,182 @@
+# SQL 占位符 → SESSION_CONFIGS() 转换规则
+
+你是一个 SQL 转换专家。在将传统 SQL 转换为 Dynamic Table SQL 时，需要将各种占位符格式统一转换为 `SESSION_CONFIGS()` 函数调用。
+
+## 占位符格式统一
+
+首先将所有旧格式统一为 `${...}` 格式：
+
+| 旧格式 | 统一为 |
+|--------|--------|
+| `{{ var }}` | `${var}` |
+| `{{ ds }}` | `${ds}` |
+| `{{region}}` | `${region}` |
+
+转换正则：`\{\{\s*([^}]+)\s*\}\}` → `${\1}`
+
+## 基本替换规则
+
+### 简单变量
+
+| 输入 | 输出 |
+|------|------|
+| `${ds}` | `SESSION_CONFIGS()['dt.args.ds']` |
+| `${region}` | `SESSION_CONFIGS()['dt.args.region']` |
+| `${hour}` | `SESSION_CONFIGS()['dt.args.hour']` |
+
+### nodash 变量（特殊处理）
+
+变量名中包含 `nodash` 时，自动包装 DATE_FORMAT，但变量名保持原样：
+
+| 输入 | 输出 |
+|------|------|
+| `${ds_nodash}` | `DATE_FORMAT(SESSION_CONFIGS()['dt.args.ds_nodash'], 'yyyyMMdd')` |
+| `${dsnodash}` | `DATE_FORMAT(SESSION_CONFIGS()['dt.args.dsnodash'], 'yyyyMMdd')` |
+
+注意：变量名保持原样（`ds_nodash` 不会变成 `ds`），只是外层包 DATE_FORMAT。
+
+### 带运算的变量
+
+最终输出统一使用 `sub_days` 函数（有一个后处理步骤会将所有 `DATE_SUB`/`DATE_ADD` 转为 `sub_days`）：
+
+| 输入 | 最终输出 |
+|------|----------|
+| `${ds - 1}` | `DATE_FORMAT(sub_days(SESSION_CONFIGS()['dt.args.ds'], 1), 'yyyy-MM-dd')` |
+| `${ds + 7}` | `DATE_FORMAT(sub_days(SESSION_CONFIGS()['dt.args.ds'], -7), 'yyyy-MM-dd')` |
+| `${ds_nodash - 1}` | `DATE_FORMAT(sub_days(SESSION_CONFIGS()['dt.args.ds_nodash'], 1), 'yyyyMMdd')::STRING` |
+
+规则：
+- `-` 运算 → `sub_days(..., N)`（N 为正数）
+- `+` 运算 → `sub_days(..., -N)`（N 取反为负数）
+- 外层包 `DATE_FORMAT`，格式根据变量名决定：
+  - 含 `nodash` → `'yyyyMMdd'`
+  - 不含 `nodash` → `'yyyy-MM-dd'`
+- 含 `nodash` 的变量带运算时，追加 `::STRING` 类型转换
+
+注意：这是最终输出形式。中间步骤可能先生成 `DATE_SUB`/`DATE_ADD`，但最终会被后处理统一转为 `sub_days`。
+
+### macros.ds_add 函数
+
+| 输入 | 输出 |
+|------|------|
+| `${macros.ds_add(ds, -1)}` | `DATE_FORMAT(sub_days(SESSION_CONFIGS()['dt.args.ds'], 1), 'yyyy-MM-dd')` |
+| `${macros.ds_add(ds, 7)}` | `DATE_FORMAT(sub_days(SESSION_CONFIGS()['dt.args.ds'], -7), 'yyyy-MM-dd')` |
+
+注意：`macros.ds_add` 的第二个参数与 `sub_days` 的参数符号相反。`macros.ds_add(ds, -1)` 表示 ds 减 1 天，对应 `sub_days(ds, 1)`（正数=减天数）；`macros.ds_add(ds, 7)` 表示 ds 加 7 天，对应 `sub_days(ds, -7)`（负数=加天数）。
+
+## 引号上下文规则
+
+占位符的处理方式取决于它所在的引号上下文：
+
+### 情况1：占位符在单引号内（纯占位符）
+
+```sql
+-- 输入
+WHERE dt = '${ds}'
+-- 输出（去除外层引号，直接替换）
+WHERE dt = SESSION_CONFIGS()['dt.args.ds']
+```
+
+### 情况2：占位符在单引号内（混合内容）
+
+当引号内同时包含占位符和字面文本时，使用 CONCAT：
+
+```sql
+-- 输入
+WHERE dt = '${ds_nodash}_done'
+-- 输出
+WHERE dt = CONCAT(DATE_FORMAT(SESSION_CONFIGS()['dt.args.ds_nodash'], 'yyyyMMdd'), '_done')
+```
+
+```sql
+-- 输入
+WHERE path = '/data/${region}/output'
+-- 输出
+WHERE path = CONCAT('/data/', SESSION_CONFIGS()['dt.args.region'], '/output')
+```
+
+### 情况3：占位符不在引号内
+
+```sql
+-- 输入
+WHERE dt = ${ds}
+-- 输出
+WHERE dt = SESSION_CONFIGS()['dt.args.ds']
+```
+
+### 情况4：占位符在单引号内，且是日期运算
+
+```sql
+-- 输入
+WHERE dt = '${ds - 1}'
+-- 输出（去除外层引号，添加 ::STRING 类型转换）
+WHERE dt = DATE_FORMAT(sub_days(SESSION_CONFIGS()['dt.args.ds'], 1), 'yyyy-MM-dd')::STRING
+```
+
+### 引号内的引号选择
+
+当替换后的表达式仍然处于单引号字符串内部时（如 CONCAT 场景），SESSION_CONFIGS 的键名使用双引号以避免引号冲突：
+```sql
+-- 在 CONCAT 等单引号上下文中
+CONCAT('prefix_', SESSION_CONFIGS()["dt.args.ds"])
+
+-- 独立表达式（外层引号已去除）
+SESSION_CONFIGS()['dt.args.ds']
+```
+
+## 静态分区中的占位符
+
+静态分区值中的占位符替换后，值会被注入到 SELECT 子句：
+
+```sql
+-- 输入
+INSERT OVERWRITE TABLE t PARTITION(dt='${ds}', region='${region}')
+SELECT col1 FROM source;
+
+-- 转换后
+SELECT col1,
+    SESSION_CONFIGS()['dt.args.ds'] AS dt,
+    SESSION_CONFIGS()['dt.args.region'] AS region
+FROM source;
+```
+
+## 不可识别的表达式
+
+对于无法解析的复杂表达式（如 Airflow Jinja 模板），进行清洗：
+1. 将 Python strftime 格式符转为 SQL 风格：`%Y`→`yyyy`, `%m`→`MM`, `%d`→`dd`, `%H`→`HH`
+2. 非字母数字下划线字符替换为 `_`
+3. 合并连续下划线，去除首尾下划线
+4. 用清洗后的字符串作为 SESSION_CONFIGS 的键名
+
+```sql
+-- 输入
+${execution_date.strftime("%H00")}
+-- 清洗后键名: execution_date_strftime_HH00
+-- 输出
+SESSION_CONFIGS()['dt.args.execution_date_strftime_HH00']
+```
+
+## 完整示例
+
+### 输入
+```sql
+INSERT OVERWRITE TABLE kscdm.dim_table
+PARTITION(p_date='{{ ds_nodash }}_done', product='done', dt='{{ ds }}')
+SELECT id, name
+FROM source_table
+WHERE dt = '{{ ds }}'
+  AND prev_dt = '{{ ds - 1 }}'
+  AND region = '{{ region }}';
+```
+
+### 输出（占位符替换后）
+```sql
+SELECT id, name,
+    CONCAT(DATE_FORMAT(SESSION_CONFIGS()['dt.args.ds_nodash'], 'yyyyMMdd'), '_done') AS p_date,
+    'done' AS product,
+    SESSION_CONFIGS()['dt.args.ds'] AS dt
+FROM source_table
+WHERE dt = SESSION_CONFIGS()['dt.args.ds']
+  AND prev_dt = DATE_FORMAT(sub_days(SESSION_CONFIGS()['dt.args.ds'], 1), 'yyyy-MM-dd')::STRING
+  AND region = SESSION_CONFIGS()['dt.args.region'];
+```

package/bin/skills/clickzetta-dynamic-table/sql-to-dt/references/sql2dt-refresh-rules.md

@@ -0,0 +1,98 @@
+# Dynamic Table Refresh 与调度文件生成规则
+
+你是一个 SQL 转换专家。在生成 Dynamic Table DDL 之后，还需要生成配套的 refresh 语句、回填语句和调度配置文件。
+
+## Refresh 语句生成
+
+### 变量提取
+
+从转换后的 DDL 中提取所有 `SESSION_CONFIGS()['dt.args.XXX']` 中的变量名 XXX，去重后排序。
+
+注意：只提取 DDL 中实际出现的变量名。例如如果 DDL 中只有 `SESSION_CONFIGS()['dt.args.ds_nodash']`，则只生成 `ds_nodash` 一个变量的 SET 语句。
+
+### 三类 Refresh 文件
+
+对每个转换的表，生成三类文件：
+
+#### 1. 当前周期 refresh（`表名_refresh.sql`）
+
+```sql
+set dt.args.ds = ${ds};
+set dt.args.region = ${region};
+REFRESH DYNAMIC TABLE schema.table_name PARTITION(ds = '${ds}', region = '${region}');
+```
+
+规则：
+- 为每个提取到的变量生成一条 `set dt.args.变量名 = ${变量名};`
+- 变量按字母序排列
+- PARTITION 子句只包含静态分区列（从原始 INSERT OVERWRITE 的 PARTITION 子句中提取）
+- 分区值使用 `'${变量名}'` 格式
+
+#### 2. 上一周期 refresh（`表名_prev_refresh.sql`）
+
+```sql
+set dt.args.ds = ${prev_ds};
+set dt.args.region = ${prev_region};
+REFRESH DYNAMIC TABLE schema.table_name PARTITION(ds = '${prev_ds}', region = '${prev_region}');
+```
+
+规则：每个变量名加 `prev_` 前缀。
+
+#### 3. 回填语句（`表名_backfill.sql`）
+
+```sql
+set cz.optimizer.incremental.backfill.enabled = TRUE;
+
+INSERT OVERWRITE schema.table_name
+SELECT *
+FROM ext_schema.table_name
+WHERE ds = '${ds}' AND region = '${region}';
+```
+
+规则：
+- 固定的 backfill 开关 SET 语句
+- 从扩展表（ext_schema）SELECT * 到目标表
+- WHERE 条件使用静态分区列（从原始 INSERT OVERWRITE 的 PARTITION 子句中提取）
+
+### 无分区表
+
+如果表没有静态分区变量：
+- 只生成当前周期 refresh：`REFRESH DYNAMIC TABLE schema.table_name;`
+- 不生成 prev_refresh 和 backfill 文件
+
+### 扩展表名规则
+
+- 如果指定了 `ext_schema`：`ext_schema.table_name`
+
+## 完整示例
+
+### 输入（转换后的 DDL 含以下变量）
+
+DDL 中包含：`SESSION_CONFIGS()['dt.args.ds']` 和 `SESSION_CONFIGS()['dt.args.region']`
+原始 PARTITION：`PARTITION(dt='${ds}', region='${region}')`
+
+### 输出
+
+**refresh.sql:**
+```sql
+set dt.args.ds = ${ds};
+set dt.args.region = ${region};
+REFRESH DYNAMIC TABLE kscdm.my_table PARTITION(dt = '${ds}', region = '${region}');
+```
+
+**prev_refresh.sql:**
+```sql
+set dt.args.ds = ${prev_ds};
+set dt.args.region = ${prev_region};
+REFRESH DYNAMIC TABLE kscdm.my_table PARTITION(dt = '${prev_ds}', region = '${prev_region}');
+```
+
+**backfill.sql:**
+```sql
+set cz.optimizer.incremental.backfill.enabled = TRUE;
+
+INSERT OVERWRITE kscdm.my_table
+SELECT *
+FROM ext_kscdm.my_table
+WHERE dt = '${ds}' AND region = '${region}';
+```

package/bin/skills/clickzetta-dynamic-table/sql-to-dt/references/sql2dt-self-reference-rules.md

@@ -0,0 +1,76 @@
+# Dynamic Table 自引用表转换规则
+
+你是一个 SQL 转换专家。当 INSERT OVERWRITE 的目标表同时出现在查询的 FROM/JOIN 中时，这是一个自引用（self-reference）场景，需要特殊处理。
+
+## 自引用检测
+
+### 判断条件
+
+1. 从 INSERT OVERWRITE 语句中提取目标表名（含 schema）
+2. 在 SELECT 查询的 FROM 和 JOIN 子句中搜索该表名
+3. 排除 PARTITION 子句中的表名引用（不算自引用）
+4. 如果在 FROM/JOIN 中找到目标表名 → 判定为自引用
+
+### 示例
+
+```sql
+-- 目标表: kscdm.daily_sales
+INSERT OVERWRITE TABLE kscdm.daily_sales PARTITION(ds='${ds}')
+SELECT current.id, current.amount
+FROM source_sales current
+LEFT JOIN kscdm.daily_sales prev ON current.id = prev.id  -- ← 自引用
+WHERE prev.ds = '${ds - 1}';
+```
+
+## 转换规则
+
+自引用表的转换与普通表基本相同，但有以下区别：
+
+### 1. 显式 Schema 声明
+
+自引用表必须在 CREATE DYNAMIC TABLE 中显式声明完整的列定义（含类型），因为 SQL 引擎需要这些信息来推理自依赖列的类型：
+
+```sql
+CREATE OR REPLACE DYNAMIC TABLE kscdm.daily_sales (
+    id BIGINT COMMENT '...',
+    amount DECIMAL(10,2) COMMENT '...',
+    ds STRING COMMENT '...'
+)
+PARTITIONED BY (ds)
+AS
+SELECT current.id, current.amount,
+    SESSION_CONFIGS()['dt.args.ds'] AS ds
+FROM source_sales current
+LEFT JOIN kscdm.daily_sales prev ON current.id = prev.id
+WHERE prev.ds = DATE_FORMAT(sub_days(SESSION_CONFIGS()['dt.args.ds'], 1), 'yyyy-MM-dd')::STRING;
+```
+
+### 2. 查询中保留自引用
+
+转换后的 AS 子句中，自引用表名保持不变，不做任何替换。SQL 引擎会自动处理自引用的版本管理。
+
+## 常见自引用场景
+
+### 日环比计算
+
+```sql
+-- 输入
+INSERT OVERWRITE TABLE metrics PARTITION(ds='${ds}')
+SELECT t.id, t.value,
+    t.value - prev.value AS daily_change
+FROM source t
+LEFT JOIN metrics prev ON t.id = prev.id AND prev.ds = '${ds - 1}';
+
+-- 输出
+CREATE OR REPLACE DYNAMIC TABLE metrics (
+    id BIGINT, value DECIMAL(10,2), daily_change DECIMAL(10,2), ds STRING
+)
+PARTITIONED BY (ds)
+AS
+SELECT t.id, t.value,
+    t.value - prev.value AS daily_change,
+    SESSION_CONFIGS()['dt.args.ds'] AS ds
+FROM source t
+LEFT JOIN metrics prev ON t.id = prev.id
+    AND prev.ds = DATE_FORMAT(sub_days(SESSION_CONFIGS()['dt.args.ds'], 1), 'yyyy-MM-dd')::STRING;
+```

package/bin/skills/clickzetta-dynamic-table/sql-to-dt/references/sql2dt-workflow.md

@@ -0,0 +1,109 @@
+# SQL → Dynamic Table 完整转换工作流
+
+当用户给你一组 CREATE TABLE DDL 和 INSERT OVERWRITE SQL，要求转换为 Dynamic Table 时，按以下步骤顺序执行。
+
+每一步的详细规则在对应的 skill 文件中，你需要同时引用它们。
+
+## 工作流步骤
+
+### Step 1: 预处理输入
+
+从 INSERT OVERWRITE 文件中移除：
+- 所有 `ALTER TABLE` 语句
+- `ANALYZE TABLE` 语句
+- SQL 注释（`--` 和 `/* */`）
+
+保留：CREATE TABLE、INSERT OVERWRITE、WITH、SET、CREATE TEMPORARY FUNCTION。
+
+### Step 2: 占位符替换
+
+按 #[[file:sql2dt-placeholder-rules.md]] 中的规则：
+1. 统一占位符格式（`{{ }}` → `${ }`）
+2. 替换所有占位符为 `SESSION_CONFIGS()` 调用
+3. 处理 nodash 变量、日期运算、macros 函数
+4. 根据引号上下文决定处理方式（去引号 / CONCAT / 直接替换）
+
+### Step 3: 自引用检测
+
+按 #[[file:sql2dt-self-reference-rules.md]] 中的规则：
+1. 检查 INSERT OVERWRITE 目标表是否出现在 FROM/JOIN 中
+2. 如果是自引用表，标记并在后续步骤中添加注释、使用显式 schema
+
+### Step 4: 核心转换
+
+按 #[[file:sql2dt-conversion-rules.md]] 中的规则：
+1. 解析 CREATE TABLE DDL（提取列、分区、属性等）
+2. 解析 INSERT OVERWRITE（提取查询、分区类型）
+3. 组装 `CREATE OR REPLACE DYNAMIC TABLE ... AS SELECT ...`
+4. 注入静态分区值到 SELECT（智能引号处理）
+5. 合并表属性模板（默认 `data_lifecycle=15`）
+6. 处理 UNION ALL（每个分支独立注入）
+7. 日期函数后处理：将所有 `DATE_SUB/DATE_ADD` 统一转为 `sub_days`
+
+### Step 5: 列校验
+
+按 #[[file:sql2dt-column-validation-rules.md]] 中的规则：
+1. 计算 schema 列数和 SELECT 列数
+2. 验证两者相等
+3. 检查重复别名和缺失分区列
+4. UNION ALL 分支列数一致性检查
+
+### Step 6: 生成配套文件
+
+按 #[[file:sql2dt-refresh-rules.md]] 中的规则：
+1. 从 DDL 中提取所有 SESSION_CONFIGS 变量
+2. 生成当前周期 refresh 语句
+3. 生成上一周期 prev_refresh 语句
+4. 生成回填 backfill 语句
+
+### Step 7: 转换后改进建议
+
+DDL 生成完成后，对转换结果做以下检查，并主动向用户提出改进建议：
+
+**检查 1：非分区表 + 持续写入风险**
+
+按 #[[file:../best-practices/non-partitioned-merge-into-warning.md]] 中的判断逻辑：
+- 生成的 DT 是非分区表（无 `PARTITIONED BY` 也无 `SESSION_CONFIGS()`）
+- 且 SQL 中包含 `ROW_NUMBER() OVER (PARTITION BY ... ORDER BY ... DESC) WHERE rn = 1` 去重模式
+
+→ 满足条件时，使用该文档中的告警话术模板向用户发出风险提示，并建议改用 MERGE INTO + Table Stream 方案。
+
+**检查 2：SQL 性能优化机会**
+
+按 #[[file:../best-practices/performance-optimization.md]] 中的规则，扫描生成的 DT SQL：
+- 存在 `LEFT/RIGHT/FULL OUTER JOIN` → 提示如果业务允许，改用 INNER JOIN 可提升增量效率
+- 存在无 `PARTITION BY` 的窗口函数 → 提示添加 PARTITION BY，否则每次增量都全量重算
+- `GROUP BY` 使用了复杂表达式（如 `DATE_TRUNC`、`SUBSTR`）→ 提示考虑在上游预计算或拆分为多级 DT
+
+**检查 3：JOIN 中是否有维度表**
+
+按 #[[file:../best-practices/dimension-table-join-guide.md]] 中的推荐场景：
+- SQL 中存在 JOIN → 询问用户右侧表是否为低频变更的维度表（码表、字典表、配置表等）
+- 如果是 → 建议在 TBLPROPERTIES 中添加 `mv_const_tables` 配置，并说明其行为和数据一致性权衡
+
+## 输出清单
+
+对每个表，最终输出：
+
+| 文件 | 内容 | 条件 |
+|------|------|------|
+| `表名.sql` | Dynamic Table DDL | 始终生成 |
+| `表名_refresh.sql` | 当前周期 REFRESH 语句 | 始终生成 |
+| `表名_prev_refresh.sql` | 上一周期 REFRESH 语句 | 仅有分区变量时 |
+| `表名_backfill.sql` | 回填语句 | 仅有分区变量时 |
+
+## 快速判断路径
+
+```
+输入 DDL + INSERT OVERWRITE
+  │
+  ├─ 有占位符？ → Step 2 占位符替换
+  │
+  ├─ 自引用？ → Step 3 特殊处理
+  │
+  ├─ 有静态分区？ → Step 4 注入分区值到 SELECT
+  │
+  ├─ 有 UNION ALL？ → Step 4 每个分支独立注入
+  │
+  └─ 生成 DDL → Step 5 校验 → Step 6 生成配套文件 → Step 7 改进建议
+```