@clickzetta/cz-cli-linux-x64 0.3.10 → 0.3.12

package/bin/skills/clickzetta-dynamic-table/best-practices/medallion-and-stream-patterns.md

@@ -0,0 +1,124 @@
+# Medallion 架构与 Table Stream 组合模式
+
+## Medallion 三层管道
+
+```
+Bronze（原始数据）
+    ↓ Dynamic Table（清洗，INCREMENTAL）
+Silver（清洗数据）
+    ↓ Dynamic Table（聚合，FULL）
+Gold（指标数据）
+    ↓ BI 工具直接查询
+```
+
+### Bronze → Silver（增量清洗）
+
+```sql
+-- 前提：源表开启变更跟踪
+ALTER TABLE bronze.raw_orders SET PROPERTIES ('change_tracking' = 'true');
+
+CREATE DYNAMIC TABLE IF NOT EXISTS silver.orders_cleaned
+REFRESH INTERVAL 15 MINUTE vcluster default
+AS
+SELECT
+  order_id,
+  customer_id,
+  CAST(amount AS DECIMAL(18,2))  AS amount,
+  CAST(created_at AS TIMESTAMP)  AS created_at,
+  COALESCE(region, 'unknown')    AS region
+FROM bronze.raw_orders
+WHERE order_id IS NOT NULL AND amount > 0;
+```
+
+### Silver → Gold（聚合指标，通常 FULL）
+
+```sql
+CREATE DYNAMIC TABLE IF NOT EXISTS gold.orders_daily_summary
+REFRESH INTERVAL 60 MINUTE vcluster default
+AS
+SELECT
+  DATE(created_at)              AS stat_date,
+  region,
+  COUNT(*)                      AS order_count,
+  SUM(amount)                   AS total_revenue,
+  COUNT(DISTINCT customer_id)   AS unique_customers
+FROM silver.orders_cleaned
+GROUP BY 1, 2;
+```
+
+---
+
+## 与 Table Stream 组合（事件驱动）
+
+Table Stream 捕获源表变更，Dynamic Table 消费 Stream 做增量处理。
+
+### 基本模式
+
+```sql
+-- 1. 源表开启变更跟踪
+ALTER TABLE bronze.raw_orders SET PROPERTIES ('change_tracking' = 'true');
+
+-- 2. 创建 Table Stream
+CREATE TABLE STREAM bronze.orders_stream
+  ON TABLE bronze.raw_orders
+  WITH PROPERTIES ('TABLE_STREAM_MODE' = 'STANDARD');
+
+-- 3. Dynamic Table 消费 Stream
+-- 注意：Stream 作为 DT 源时，每次刷新会消费 offset
+CREATE DYNAMIC TABLE IF NOT EXISTS silver.orders_incremental
+REFRESH INTERVAL 5 MINUTE vcluster default
+AS
+SELECT order_id, customer_id, amount, status
+FROM bronze.orders_stream
+WHERE __change_type IN ('INSERT', 'UPDATE_AFTER');
+```
+
+### MERGE INTO + Table Stream（替代非分区 DT 的去重场景）
+
+当需要按主键去重且源表持续写入时，推荐用 MERGE INTO 替代 Dynamic Table：
+
+```sql
+-- 1. 创建 Table Stream
+CREATE TABLE STREAM source_stream ON TABLE source_table
+WITH PROPERTIES ('TABLE_STREAM_MODE' = 'STANDARD', 'SHOW_INITIAL_ROWS' = 'TRUE');
+
+-- 2. 创建目标表
+CREATE TABLE target_table (
+    id BIGINT,
+    col1 STRING,
+    col2 INT,
+    event_time TIMESTAMP
+);
+
+-- 3. 定时调度 MERGE INTO 消费 Stream
+MERGE INTO target_table t
+USING (
+    SELECT id, col1, col2, event_time,
+        CASE WHEN `value` IS NULL OR `value` = '' THEN 'DELETE' ELSE 'UPSERT' END AS op
+    FROM source_stream
+) s ON t.id = s.id
+WHEN MATCHED AND s.op = 'UPSERT' THEN UPDATE SET
+    t.col1 = s.col1, t.col2 = s.col2, t.event_time = s.event_time
+WHEN NOT MATCHED AND s.op = 'UPSERT' THEN INSERT
+    (id, col1, col2, event_time) VALUES (s.id, s.col1, s.col2, s.event_time);
+```
+
+---
+
+## 实时报表物化
+
+```sql
+-- 每小时刷新销售汇总，供 BI 工具直接查询
+CREATE DYNAMIC TABLE IF NOT EXISTS rpt.sales_hourly
+REFRESH INTERVAL 60 MINUTE vcluster default
+AS
+SELECT
+  DATE_TRUNC('hour', order_time) AS hour_bucket,
+  product_category,
+  SUM(amount)                    AS revenue,
+  COUNT(*)                       AS order_cnt,
+  AVG(amount)                    AS avg_order_value
+FROM silver.orders_cleaned
+WHERE order_time >= DATEADD(day, -30, CURRENT_DATE)
+GROUP BY 1, 2;
+```

package/bin/skills/clickzetta-dynamic-table/best-practices/non-partitioned-merge-into-warning.md

@@ -0,0 +1,96 @@
+# 非分区表 + 持续写入：DT 风险告警与 MERGE INTO 替代建议
+
+## 触发条件
+
+当用户要创建的 DT 同时满足以下条件时，**必须向用户发出告警**：
+
+1. DT 本身是非分区表（没有 `PARTITIONED BY`，也没有 `SESSION_CONFIGS()` 引用）
+2. 源表也是非分区表，且数据会持续写入（如 Kafka 消费落地表、CDC 明细表）
+3. SQL 中包含按主键去重的窗口函数模式：`ROW_NUMBER() OVER (PARTITION BY key ORDER BY ts DESC) WHERE rn = 1`
+
+## 告警内容
+
+向用户说明以下三个风险：
+
+### 风险 1：存储无限膨胀
+
+非分区的 DT 和非分区的源表都没有自动的数据生命周期管理机制（`data_lifecycle` 仅对分区表生效）。随着数据持续写入：
+- 源表数据量无限增长
+- DT 的状态表全局维护，随数据量线性膨胀
+- 目标表数据量同步增长
+- 三者叠加，存储成本持续上升且不可控
+
+### 风险 2：源表归档引发性能灾难
+
+当存储膨胀到一定程度，运维人员通常会对源表进行归档——将历史数据迁移到冷存储或归档表，然后从源表中删除以释放空间。此时：
+
+- DT 会捕获源表的删除事件，并将其反映到增量计算结果中
+- `ROW_NUMBER() OVER (PARTITION BY key ORDER BY ts DESC) WHERE rn = 1` 的删除处理代价极高：
+  - 窗口函数无法增量处理删除——需要回读该 key 下的所有历史数据重新排序
+  - 非分区表没有分区边界来限制回读范围，可能需要扫描整张表
+  - 大规模归档会产生海量删除变更，每个 key 都需要独立回算
+- 一次源表归档可能导致 DT REFRESH 耗时从秒级飙升到小时级甚至失败
+
+### 风险 3：无法过滤归档产生的删除事件
+
+DT 的增量引擎自动捕获源表的所有变更（INSERT / UPDATE / DELETE），用户无法干预这个过程。SQL 中的 `WHERE op <> 'DELETE'` 过滤的是业务层面的删除标记，而不是源表物理删除产生的删除变更。用户没有任何手段告诉 DT "这些删除是归档操作，请忽略"。
+
+## 推荐替代方案
+
+建议用户使用 MERGE INTO + Table Stream 替代：
+
+```sql
+-- Step 1: 源表开启变更跟踪
+ALTER TABLE source_table SET PROPERTIES ('change_tracking' = 'true');
+
+-- Step 2: 创建 Table Stream
+CREATE TABLE STREAM source_stream ON TABLE source_table
+WITH (TABLE_STREAM_MODE = 'STANDARD', SHOW_INITIAL_ROWS = TRUE);
+
+-- Step 3: 创建目标表
+CREATE TABLE target_table (
+    id BIGINT,
+    col1 STRING,
+    col2 INT,
+    event_time TIMESTAMP
+);
+
+-- Step 4: 定时调度 MERGE INTO 消费 Stream
+MERGE INTO target_table t
+USING (
+    SELECT id, col1, col2, event_time,
+        CASE WHEN `value` IS NULL OR `value` = '' THEN 'DELETE' ELSE 'UPSERT' END AS op
+    FROM source_stream
+) s ON t.id = s.id
+WHEN MATCHED AND s.op = 'UPSERT' THEN UPDATE SET
+    t.col1 = s.col1, t.col2 = s.col2, t.event_time = s.event_time
+WHEN NOT MATCHED AND s.op = 'UPSERT' THEN INSERT
+    (id, col1, col2, event_time) VALUES (s.id, s.col1, s.col2, s.event_time);
+```
+
+MERGE INTO + Table Stream 的优势：
+- **每次计算独立**：只消费 Stream 中的增量数据，不依赖源表全量状态
+- **归档免疫**：源表归档时，可在 USING 子查询中通过 WHERE 条件过滤归档产生的删除事件
+- **目标表独立管理**：目标表的生命周期与源表解耦，可独立制定归档策略
+- **offset 自动推进**：MERGE INTO 消费 Stream 后 offset 自动推进，下次只处理新变更
+
+## 告警话术模板
+
+当检测到用户的 DT 满足触发条件时，使用以下话术：
+
+> ⚠️ **风险提示**：您正在创建一个非分区的 Dynamic Table，且源表也是非分区的持续写入表。这种组合存在以下长期运维风险：
+>
+> 1. **存储无限膨胀**：源表、DT 目标表、DT 状态表三者都会持续增长，且无法通过 `data_lifecycle` 自动清理
+> 2. **源表归档会引发性能灾难**：当您需要对源表进行归档（迁移历史数据后删除）时，DT 会捕获这些删除事件。由于 SQL 中包含 `ROW_NUMBER() ... WHERE rn = 1` 的去重逻辑，每个被删除的 key 都需要回读历史数据重新排序，非分区表没有边界限制，可能导致 REFRESH 性能严重回退
+> 3. **无法过滤归档删除**：DT 增量引擎自动捕获源表所有变更，您无法告诉 DT 忽略归档操作产生的删除
+>
+> **建议**：对于这类"非分区 CDC 明细表合并为结果表"的场景，推荐使用 MERGE INTO + Table Stream 方案。每次只消费增量数据，源表归档时可通过 WHERE 条件过滤删除事件，不会影响下游。
+
+## 判断逻辑
+
+在帮助用户创建 DT 时，按以下顺序检查：
+
+1. DT 是否有 `PARTITIONED BY` 或 `SESSION_CONFIGS()` → 如果有，不触发告警
+2. 源表是否是持续写入的非分区表（如 Kafka 消费表、CDC 明细表）→ 如果不是，不触发告警
+3. SQL 是否包含 `ROW_NUMBER() OVER (PARTITION BY ... ORDER BY ... DESC) WHERE rn = 1` 模式 → 如果包含，风险最高，必须告警
+4. 即使没有 ROW_NUMBER，只要满足条件 1+2，也应提醒用户注意存储膨胀风险

package/bin/skills/clickzetta-dynamic-table/best-practices/performance-optimization.md

@@ -0,0 +1,109 @@
+# Dynamic Table 性能优化指南
+
+本文档从 SQL 写法、数据特征、管道设计三个维度，帮助用户写出增量刷新性能更好的 DT。
+
+## 核心原则：增量刷新的代价模型
+
+增量刷新的性能取决于三个因素：
+1. **变更量占比**：每次刷新时，源表中有多少数据发生了变化。变更量越小，增量越划算
+2. **算子类型**：不同 SQL 算子的增量代价差异很大
+3. **数据局部性**：变更数据在 JOIN key / GROUP BY key / PARTITION BY key 上的分布是否集中
+
+当变更量超过总数据量的较大比例时，增量刷新可能反而比全量刷新更慢，因为增量需要额外的变更数据计算、去重合并、状态表读写等开销。
+
+## SQL 写法优化
+
+### 1. 优先使用 INNER JOIN 而非 OUTER JOIN
+
+INNER JOIN 的增量计算比 OUTER JOIN 更高效：
+- INNER JOIN：只需要计算 A 的变更数据 JOIN B 的全量数据 + A 的全量数据 JOIN B 的变更数据
+- LEFT/RIGHT/FULL OUTER JOIN：还需要额外处理 NULL 填充、反向撤回等逻辑
+
+如果业务上可以保证参照完整性（即 JOIN key 一定能匹配），优先用 INNER JOIN。
+
+```sql
+-- ❌ 不必要的 LEFT JOIN（如果 product 一定存在）
+SELECT o.*, p.name FROM orders o LEFT JOIN products p ON o.pid = p.id;
+
+-- ✅ 改用 INNER JOIN
+SELECT o.*, p.name FROM orders o INNER JOIN products p ON o.pid = p.id;
+```
+
+### 2. 减少不必要的 DISTINCT
+
+每次增量刷新时，DISTINCT 需要对受影响的 key 做重算。如果上游数据已经去重，或者可以通过其他方式保证唯一性，去掉 DISTINCT。
+
+```sql
+-- ❌ 冗余的 DISTINCT
+SELECT DISTINCT user_id, user_name FROM user_events;
+```
+
+### 3. 窗口函数必须有 PARTITION BY
+
+没有 PARTITION BY 的窗口函数会导致每次增量刷新都全量重算整个窗口。加上 PARTITION BY 后，只需要重算受影响的分区。
+
+```sql
+-- ❌ 全局窗口，每次增量都全量重算
+SELECT *, ROW_NUMBER() OVER (ORDER BY created_at DESC) AS rn FROM events;
+
+-- ✅ 加上 PARTITION BY，只重算有变更的分区
+SELECT *, ROW_NUMBER() OVER (PARTITION BY category ORDER BY created_at DESC) AS rn FROM events;
+```
+
+### 4. 聚合 key 尽量使用简单列引用
+
+复合表达式作为 GROUP BY key 会降低增量效率，因为引擎需要对表达式求值后才能判断哪些 key 受影响。
+
+```sql
+-- ❌ 复合表达式作为 GROUP BY key
+SELECT DATE_TRUNC('hour', ts) AS hour, SUM(amount)
+FROM transactions
+GROUP BY DATE_TRUNC('hour', ts);
+
+-- ✅ 如果可能，在上游预计算好 key 列
+-- 或者拆分为两个 DT（见下文"管道拆分"）
+```
+
+### 5. 尽可能使用分区条件限制数据范围
+
+在 DT 的 SQL 中对源表添加分区过滤条件，可以显著减少每次增量刷新需要扫描的数据量。
+
+```sql
+-- ❌ 不加分区条件，每次扫描全表
+SELECT o.*, p.name
+FROM orders o JOIN products p ON o.pid = p.id;
+
+-- ✅ 通过分区条件限制数据范围
+SELECT o.*, p.name
+FROM orders o JOIN products p ON o.pid = p.id
+WHERE o.ds = SESSION_CONFIGS()['dt.args.ds'];
+```
+
+## 管道拆分：复杂 DT 拆成多级
+
+当一个 DT 的 SQL 包含多个 JOIN + 聚合 + 窗口函数时，考虑拆分为多个 DT，每个 DT 只做一件事。
+
+好处：
+- 每个 DT 的增量计算更简单、更快
+- 中间 DT 可以被多个下游 DT 复用
+- 出问题时更容易定位是哪一层的问题
+- 不同层可以使用不同的优化策略
+
+## 数据特征与增量效率
+
+### 变更量占比
+
+增量刷新在变更量占总数据量比例较小时效果最好。经验值：
+- < 5%：增量刷新通常显著优于全量
+- 5% ~ 20%：取决于具体算子和数据分布
+- \> 20%：可能需要评估是否全量刷新更合适
+
+### Append-Only 源表
+
+如果源表只有 INSERT 没有 UPDATE/DELETE 可以显著优化：
+- 增量引擎知道变更数据只有新增（无撤回），可以跳过去重合并等操作
+- 聚合可以直接累加，不需要维护完整的中间状态
+
+### 变更数据的分布
+
+如果变更数据集中在少数 key 上（如最近时间段的数据），增量效率高。如果变更分散在大量 key 上，聚合和窗口函数需要重算大量分区，效率下降。

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

@@ -0,0 +1,15 @@
+---
+name: dt-creator
+description: |
+  创建 Dynamic Table 的参考资料索引。涵盖静态分区 DT 与动态分区 DT 的声明策略、
+  增量计算支持的 SQL 模式、增量刷新配置项说明、以及刷新历史的查询方式。
+---
+
+# DT Creator — 参考资料索引
+
+## references/
+
+- **dt-declaration-strategy.md** — DT 声明策略（静态分区 DT vs 动态分区 DT 的创建语法与选择）
+- **sql-limitations.md** — SQL 支持矩阵（JOIN、聚合、窗口函数、非确定性函数等的支持情况）
+- **incremental-config-reference.md** — 增量计算配置参考（刷新策略、源表特征声明、状态表管理等）
+- **refresh-history-guide.md** — 增量刷新历史查询（SHOW REFRESH HISTORY / DESC HISTORY / information_schema）

package/bin/skills/clickzetta-dynamic-table/dt-creator/references/dt-declaration-strategy.md

@@ -0,0 +1,185 @@
+# Dynamic Table 声明策略
+
+DT 有两种创建语法：静态分区 DT 和动态分区 DT（非分区 DT 可视为动态分区的特例）。两者在创建语法、刷新方式、增量行为上有本质区别。
+
+## 核心概念
+
+### 静态分区 DT（Partitioned DT with SESSION_CONFIGS args）
+
+SQL 中通过 `SESSION_CONFIGS()` 引用分区参数，每次 REFRESH 时指定具体的分区值。每个分区独立刷新，可以视为每个分区刷新单元都是一个彼此独立的 DT。
+
+```sql
+CREATE DYNAMIC TABLE order_daily (
+    id BIGINT, amount DECIMAL(12,2), ds STRING
+)
+PARTITIONED BY (ds)
+AS
+SELECT id, amount, SESSION_CONFIGS()['dt.args.ds'] AS ds
+FROM orders
+WHERE ds = SESSION_CONFIGS()['dt.args.ds'];
+
+-- 刷新时指定分区（在 Studio 任务中执行，dt.args.ds 通过任务参数传入）
+REFRESH DYNAMIC TABLE order_daily PARTITION(ds = '2025-01-01');
+```
+
+### 动态分区 DT（Non-partitioned DT / DT without args）
+
+SQL 中不引用 `SESSION_CONFIGS()`，或者虽然有分区但分区值由查询逻辑动态产生。每次 REFRESH 处理所有源表的增量数据。
+
+动态分区 DT 不允许除 REFRESH 以外的任何命令修改数据（INSERT/UPDATE/DELETE/MERGE 均不可用），数据完全由 REFRESH 驱动。
+
+因此以下 ETL 场景不适合使用动态分区 DT：
+- 需要手动修补数据（如发现某几行数据有误，需要直接 UPDATE 修正）
+- 需要按条件删除部分数据（如清理脏数据、删除过期记录）
+- 需要 MERGE INTO 做 upsert（如 CDC 场景中消费 stream 合并到目标表）
+- 需要 INSERT INTO 追加外部数据（如手动导入一批补录数据）
+- 需要按分区独立回填或重刷（动态分区 DT 只能整表全量刷新，无法单独刷某个分区）
+- 下游有其他任务需要往同一张表写入数据（DT 独占写入权）
+
+```sql
+CREATE DYNAMIC TABLE order_summary (
+    category STRING, total_amount DECIMAL(12,2)
+)
+AS
+SELECT category, SUM(amount) AS total_amount
+FROM orders
+GROUP BY category;
+
+-- 刷新时不指定分区
+REFRESH DYNAMIC TABLE order_summary;
+```
+
+## 两者的关键区别
+
+| 维度 | 静态分区 DT | 动态分区 DT |
+|------|-----------|-----------|
+| SQL 中是否有 `SESSION_CONFIGS()` | 有，用于引用分区参数 | 无 |
+| REFRESH 语法 | `REFRESH ... PARTITION(ds='xxx')` | `REFRESH ...`（无 PARTITION） |
+| 增量范围 | 只处理指定分区的增量数据 | 处理所有源表的全部增量数据 |
+| 调度方式 | 外部调度器按分区值逐个触发 | 外部调度器定时触发即可 |
+| 数据生命周期 | 按分区管理，可独立回填/删除 | 整表管理 |
+| 状态表 | 按分区独立维护 | 全局维护 |
+| 适合的数据模式 | T+1 批处理、按时间分区的 ETL | 实时流、全局聚合、无明确分区键 |
+
+## 选择决策树
+
+```
+你的数据有明确的时间/业务分区键吗？
+│
+├─ 是 → 原始 ETL 是按分区 INSERT OVERWRITE 的吗？
+│       │
+│       ├─ 是 → 使用静态分区 DT
+│       │       （保持原有的分区粒度，每个分区独立刷新）
+│       │
+│       └─ 否 → 数据量大吗？需要按分区管理生命周期吗？
+│               │
+│               ├─ 是 → 使用静态分区 DT
+│               │       （即使原来不是分区表，也建议加分区以便管理）
+│               │
+│               └─ 否 → 使用动态分区 DT
+│                       （简单场景，不需要分区管理）
+│
+└─ 否 → 使用动态分区 DT
+        （全局聚合、实时汇总等场景）
+```
+
+## 静态分区 DT 详解
+
+### 适用场景
+
+1. **T+1 批处理 ETL 迁移**
+   - 原始 SQL 是 `INSERT OVERWRITE TABLE t PARTITION(ds='${ds}')` 模式
+   - 每天/每小时按分区刷新一次
+   - 需要支持历史分区回填
+
+2. **滑动窗口计算**
+   - 如：最近 7 天的聚合、环比计算
+   - SQL 中引用 `SESSION_CONFIGS()['dt.args.ds']` 和 `sub_days(...)` 做窗口范围
+
+3. **需要按分区管理数据生命周期**
+   - 通过 `data_lifecycle` 自动清理过期分区
+   - 可以单独回填某个分区而不影响其他分区
+
+4. **自引用 DT（日环比、SCD）**
+   - 当前分区依赖上一个分区的结果
+   - 必须用静态分区，因为需要明确指定"当前分区"和"上一分区"
+
+### 刷新方式
+
+> ⚠️ **重要**：静态分区 DT 的 `dt.args.*` 参数**仅在 Studio 任务中可用**，不能在交互式 SQL 中使用 `SET dt.args.xxx`。
+> 必须通过 Studio 创建调度任务，在任务参数中配置 `dt.args.ds` 等值。
+
+```sql
+-- 在 Studio 任务中，参数通过任务配置传入，REFRESH 语句指定分区值：
+REFRESH DYNAMIC TABLE my_dt PARTITION(ds = '2025-01-15');
+
+-- 多级分区
+REFRESH DYNAMIC TABLE my_dt PARTITION(pt = '20250411', pt_hour = '01');
+```
+
+### 注意事项
+
+- 回填时使用 `SET cz.optimizer.incremental.backfill.enabled = TRUE`（此配置在交互式 SQL 中可用）
+- `dt.args.*` 参数仅在 Studio 任务中可用，不能在交互式 SQL 中 SET
+- `cz.optimizer.*` 配置项在交互式 SQL 中可用
+
+## 动态分区 DT 详解
+
+### 适用场景
+
+1. **实时流数据聚合**
+   - 源表持续写入，DT 定时刷新
+   - 不需要按分区管理，每次处理所有新增数据
+
+2. **全局汇总表**
+   - 如：全局 TopN、全局计数、全局去重
+   - 没有明确的分区键
+
+3. **简单的 JOIN + 过滤**
+   - 不涉及分区参数的简单转换
+   - 如：事实表 JOIN 维度表，输出宽表
+
+4. **多源表合并（UNION ALL）**
+   - 多个源表的数据合并到一张表
+   - 不需要按分区管理
+
+### 刷新方式
+
+```sql
+-- 直接刷新，处理所有源表的增量
+REFRESH DYNAMIC TABLE my_dt;
+```
+
+### 注意事项
+
+- 每次刷新处理所有源表的全部增量，如果源表变更量大，刷新可能较慢
+- 状态表全局维护，随着数据量增长可能膨胀
+- 不支持按分区回填，只能全量刷新整表
+- 适合变更量占比小的场景（< 5%）
+
+## 分区粒度选择
+
+当选择静态分区 DT 时，还需要决定分区粒度：
+
+| 数据模式 | 推荐分区粒度 | 说明 |
+|---------|------------|------|
+| 严格有序的时间序列（如日志） | 分钟级 (`dt_min`) | 数据量大、写入频繁 |
+| 大致有序、少量迟到数据 | 小时级 (`dt_hour`) | 平衡粒度和管理复杂度 |
+| T+1 批量导入 | 天级 (`ds`) | 最常见的 ETL 场景 |
+| 按业务周期 | 周/月级 | 报表类场景 |
+| 多级分区 | 天 + 小时 (`ds`, `hour`) | 需要更细粒度的生命周期管理 |
+
+选择原则：
+- 粒度越细，每次刷新处理的数据量越小，增量效率越高
+- 粒度越细，分区数越多，管理和调度越复杂
+- 粒度应与数据写入频率匹配：如果数据每小时写入一次，分区粒度不应细于小时
+
+## 从原始 ETL 判断分区策略
+
+| 原始 ETL 模式 | 推荐 DT 分区策略 |
+|--------------|----------------|
+| `INSERT OVERWRITE TABLE t PARTITION(ds='${ds}')` | 静态分区 DT，天级 |
+| `INSERT OVERWRITE TABLE t PARTITION(ds='${ds}', hour='${hour}')` | 静态分区 DT，天+小时级 |
+| `INSERT OVERWRITE TABLE t PARTITION(ds)` （动态分区写入） | 动态分区 DT 或静态分区 DT（取决于是否需要按分区管理） |
+| `INSERT INTO TABLE t SELECT ...` （无分区） | 动态分区 DT |
+| `INSERT OVERWRITE TABLE t SELECT ...` （全表覆盖） | 动态分区 DT |