@clickzetta/cz-cli-darwin-x64 0.3.75 → 0.3.78

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

@@ -0,0 +1,118 @@
+# Dynamic Table 列校验与一致性规则
+
+你是一个 SQL 转换专家。在生成 Dynamic Table DDL 后，需要校验 schema 定义的列与 SELECT 查询产出的列是否一致。
+
+## 列数校验（必须通过）
+
+### 规则
+
+生成的 DDL 中，括号内定义的列数必须等于 AS 后面 SELECT 查询产出的列数。
+
+```sql
+CREATE OR REPLACE DYNAMIC TABLE t (
+    col1 BIGINT,    -- 1
+    col2 STRING,    -- 2
+    dt STRING       -- 3  → schema 列数 = 3
+)
+AS
+SELECT col1, col2, '2024-01-01' AS dt  -- → SELECT 列数 = 3 ✓
+FROM source;
+```
+
+### SELECT 列数计算
+
+1. 找到 AS 后面的 SELECT 子句
+2. 找到顶层 FROM（不在子查询/括号内的 FROM）
+3. 计算 SELECT 和 FROM 之间的顶层逗号数 + 1 = 列数
+4. 顶层逗号：不在括号 `()`、方括号 `[]`、引号 `''`/`""` 内的逗号
+
+### UNION ALL 的列数
+
+取第一个分支的列数（所有分支列数应一致）。
+
+### 校验失败
+
+如果 schema 列数 ≠ SELECT 列数，转换失败，报错：
+```
+Schema列数(N) != SELECT列数(M)
+```
+
+## 列名校验（可选）
+
+### 规则
+
+逐位对比 schema 中的列名与 SELECT 中推断出的别名。建议在列数校验通过后，如果 SELECT 中大部分列都有明确别名（AS 或裸标识符），开启列名校验做二次确认。
+
+### SELECT 列别名推断
+
+按优先级从高到低：
+
+1. **AS 别名**：`expression AS alias` → 别名为 `alias`
+2. **末尾标识符**：`table.column` → 别名为 `column`
+3. **裸标识符**：`column_name` → 别名为 `column_name`
+4. **无法推断**：`func(a, b)` 没有 AS → 标记为 `<expr>`，跳过校验
+
+### 对比规则
+
+- 逐位对比（第1列对第1列，第2列对第2列...）
+- 如果某位是 `<expr>`（无法推断），跳过该位
+- 对比不区分大小写
+- 不匹配时报错并列出具体不对齐的列
+
+## 静态分区注入后的列数
+
+注入静态分区列后，SELECT 列数会增加。校验应在注入后进行。
+
+### 避免重复注入
+
+在注入前检查 SELECT 中是否已包含该分区列：
+
+1. 解析 SELECT 中每个表达式的最终别名
+2. 如果别名（不区分大小写）与分区列名匹配 → 该列已存在，跳过注入
+3. 只注入 SELECT 中不存在的分区列
+
+## UNION ALL 一致性
+
+### 分支列数一致性
+
+所有 UNION ALL 分支的列数必须相同。如果不一致，记录警告：
+```
+UNION分支列数不一致: [12, 13, 12]
+```
+
+### 注入后复核
+
+静态分区注入后，再次检查各分支列数是否一致：
+```
+注入后UNION各分支列数: [13, 13, 13]
+```
+
+## 重复别名检测
+
+如果 SELECT 中有重复的列别名，记录警告：
+```
+检测到重复列别名: ['dt']
+```
+
+重复别名可能导致：
+- 列数看起来正确但实际语义错误
+- 下游查询引用歧义
+
+## 缺失分区列检测
+
+如果 SELECT 中缺少某些分区列（注入前），记录信息：
+```
+检测到缺失分区列: ['dt', 'ds']
+```
+
+这些列会在注入步骤中被自动添加。
+
+## 完整校验流程
+
+```
+1. 生成 DDL（含静态分区注入）
+2. 提取 schema 列数
+3. 提取 SELECT 列数
+4. 比较列数 → 不等则失败
+5. （可选）逐位对比列名 → 不匹配则失败
+```

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;
+```