@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/generated_columns_guide.md

@@ -0,0 +1,847 @@
+# Lakehouse生成列使用指南
+
+## 文档介绍
+
+本指南面向需要在云器Lakehouse中使用生成列功能的数据工程师和开发者。无论您是从MySQL、PostgreSQL、Oracle等传统数据库迁移，还是从Hive、Spark等大数据平台转换，都能在此找到完整的实施方案。
+
+生成列是云器Lakehouse的核心特性之一，能够自动计算和维护衍生列的值，显著提升开发效率和数据一致性。通过本指南，您将掌握生成列的使用方法、避开常见陷阱，并能够设计出高性能的数据架构。
+
+## 快速导航
+
+### 立即开始
+
+* [什么是生成列](#什么是生成列) → 了解核心概念
+* [基础语法](#基础语法) → 5分钟上手使用
+* [验证清单](#验证清单) → 确保正确创建
+* [常见错误](#常见错误) → 快速解决问题
+
+### 平台迁移
+
+* [MySQL迁移](#mysql迁移) → 从MySQL迁移指导
+* [PostgreSQL迁移](#postgresql迁移) → 从PostgreSQL迁移指导
+* [Oracle迁移](#oracle迁移) → 从Oracle迁移指导
+* [Hive/Spark迁移](#hivespark迁移) → 从大数据平台迁移指导
+
+### 深入使用
+
+* [支持函数列表](#函数支持) → 避免试错，直接查表
+* [高级场景](#高级场景) → 复杂业务应用
+* [性能优化](#性能优化) → 最佳实践建议
+
+### 问题解决
+
+* [故障诊断](#故障诊断) → 系统性排查方法
+* [快速参考](#快速参考) → 语法速查表
+
+***
+
+## 什么是生成列
+
+生成列（Generated Columns）是云器Lakehouse的计算列特性，能够根据其他列的值自动计算并生成新列的值。相比传统的计算列或视图方案，生成列具有更好的性能表现、更强的一致性保证和更灵活的应用场景。
+
+### 核心优势
+
+* **自动计算**：基于其他列值自动计算和维护
+* **逻辑一致性**：在数据库层统一计算逻辑，避免应用层逻辑分散
+* **查询性能**：预计算存储，减少查询时的重复计算
+* **分区支持**：可用作分区列，支持基于计算结果的分区策略
+* **标准兼容**：支持常用的确定性函数和表达式
+
+### 适用场景
+
+* 时间维度分析（按日期、小时等分组查询）
+* 数据分类和标准化（状态判断、等级划分）
+* 需要统一业务规则的场景
+* 基于计算结果进行分区的需求
+
+***
+
+## 基础语法
+
+### 创建语法
+
+```sql
+-- 完整的CREATE TABLE语法
+CREATE TABLE table_name (
+    column_definition,
+    column_name data_type GENERATED ALWAYS AS ( expression ) [COMMENT comment],
+    [column_definition,...]
+) [ PARTITIONED BY (column_name) ];
+
+-- ALTER TABLE添加生成列语法
+ALTER TABLE table_name ADD COLUMN 
+column_name data_type GENERATED ALWAYS AS ( expression ) 
+[COMMENT comment];
+```
+
+### 5分钟上手示例
+
+```sql
+-- 创建表时定义生成列
+CREATE TABLE orders (
+    order_id INT,
+    order_time TIMESTAMP_LTZ,
+    amount DOUBLE,
+    order_date STRING GENERATED ALWAYS AS (date_format(order_time, 'yyyy-MM-dd')),
+    order_hour INT GENERATED ALWAYS AS (hour(order_time)),
+    amount_level STRING GENERATED ALWAYS AS (
+        if(amount >= 1000, 'HIGH',
+           if(amount >= 500, 'MEDIUM', 'LOW'))
+    )
+);
+
+-- 插入数据：只需提供基础列
+INSERT INTO orders (order_id, order_time, amount) VALUES 
+(1001, TIMESTAMP '2024-06-19 14:30:00', 299.99);
+
+-- 查询结果：自动包含生成列
+SELECT * FROM orders;
+-- 结果：order_date='2024-06-19', order_hour=14, amount_level='LOW'
+
+-- 后续添加生成列
+ALTER TABLE orders ADD COLUMN 
+year_col INT GENERATED ALWAYS AS (year(order_time)) COMMENT '年份列';
+```
+
+***
+
+## 验证清单
+
+### 创建后验证（每次必做）
+
+```sql
+-- 1. 创建带生成列的表
+CREATE TABLE orders_test (
+    order_id INT,
+    order_time TIMESTAMP_LTZ,
+    amount DOUBLE,
+    hour_col INT GENERATED ALWAYS AS (hour(order_time)),
+    date_str STRING GENERATED ALWAYS AS (date_format(order_time, 'yyyy-MM-dd'))
+);
+
+-- 2. 验证表结构
+DESCRIBE TABLE orders_test;
+-- ✅ 检查：生成列是否出现在表结构中
+
+-- 3. 测试数据插入
+INSERT INTO orders_test (order_id, order_time, amount) VALUES 
+(1001, TIMESTAMP '2024-06-19 14:30:00', 299.99);
+
+-- 4. 验证生成列值
+SELECT order_id, order_time, hour_col, date_str FROM orders_test;
+-- ✅ 检查：hour_col=14, date_str='2024-06-19'
+
+-- 5. 验证插入保护机制
+-- INSERT INTO orders_test (order_id, order_time, hour_col) VALUES 
+-- (1002, TIMESTAMP '2024-06-19 15:30:00', 999);
+-- ✅ 检查：应该报错"cannot insert or update generated column"
+
+-- 6. 验证ALTER TABLE添加生成列
+ALTER TABLE orders_test ADD COLUMN 
+year_col INT GENERATED ALWAYS AS (year(order_time));
+
+-- 7. 验证存量数据回填
+SELECT order_id, order_time, year_col FROM orders_test;
+-- ✅ 检查：year_col=2024（存量数据自动计算）
+```
+
+### 验证失败解决方案
+
+| 验证失败现象         | 可能原因            | 解决方案                    |
+| -------------- | --------------- | ----------------------- |
+| 生成列未出现在表结构中    | 建表语法错误          | 用原生SQL重新创建              |
+| 生成列值为null或错误   | 表达式语法错误         | 检查生成表达式                 |
+| 插入时不报错但能指定生成列值 | 生成列语法不正确        | 检查GENERATED ALWAYS AS语法 |
+| 存量数据回填失败       | ALTER TABLE语法问题 | 重新执行ALTER语句             |
+
+***
+
+## 常见错误
+
+| 错误信息                                                                    | 原因                  | 解决方案                |
+| ----------------------------------------------------------------------- | ------------------- | ------------------- |
+| `cannot insert or update generated column`                              | 尝试手动指定生成列的值         | 只插入基础列，移除生成列赋值      |
+| `Generated column only contains built-in/scalar/deterministic function` | 使用了CASE WHEN或不支持的函数 | 改用if()函数嵌套或检查函数支持列表 |
+| `expression contains non-deterministic function`                        | 使用了非确定性函数           | 改用确定性函数             |
+| `function not found - initcap`                                          | 使用了不存在的函数           | 使用其他字符串函数组合实现       |
+| `Expected: 2, Found: 1`                                                 | 函数参数数量错误            | 检查函数正确语法            |
+
+***
+
+## 支持函数列表
+
+### 时间日期函数
+
+```sql
+-- 时间提取
+year(timestamp_col)          -- 提取年份 ✅
+month(timestamp_col)         -- 提取月份（1-12） ✅
+day(timestamp_col)           -- 提取日期（1-31） ✅
+hour(timestamp_col)          -- 提取小时（0-23） ✅
+minute(timestamp_col)        -- 提取分钟（0-59） ✅
+second(timestamp_col)        -- 提取秒数（0-59） ✅
+dayofweek(timestamp_col)     -- 星期几（1=周日） ✅
+quarter(timestamp_col)       -- 季度（1-4） ✅
+dayofyear(timestamp_col)     -- 一年中的第几天 ✅
+weekofyear(timestamp_col)    -- 一年中的第几周 ✅
+
+-- 日期格式化
+date_format(timestamp_col, 'yyyy-MM-dd')           -- 2024-06-19 ✅
+date_format(timestamp_col, 'yyyy-MM-dd HH:mm:ss')  -- 2024-06-19 14:30:00 ✅
+date_format(timestamp_col, 'yyyy-MM')              -- 2024-06 ✅
+
+-- 推荐的季度格式
+concat(cast(year(timestamp_col) as string), '-Q', cast(quarter(timestamp_col) as string))  -- 2024-Q2 ✅
+
+-- 日期计算
+date_add(date_col, days)     -- 日期加天数 ✅
+date_sub(date_col, days)     -- 日期减天数 ✅
+datediff(date1, date2)       -- 两个日期的天数差 ✅
+```
+
+### 字符串函数
+
+```sql
+-- 大小写转换
+upper(string_col)            -- 转大写 ✅
+lower(string_col)            -- 转小写 ✅
+
+-- 字符串操作
+length(string_col)           -- 字符串长度 ✅
+substring(string_col, start, length)  -- 字符串截取 ✅
+left(string_col, length)     -- 左侧截取 ✅
+right(string_col, length)    -- 右侧截取 ✅
+position(substr, string)     -- 查找子字符串位置 ✅
+
+-- 拼接和替换
+concat(str1, str2, ...)      -- 字符串拼接 ✅
+concat_ws(separator, str1, str2, ...)  -- 带分隔符拼接 ✅
+replace(string_col, old_str, new_str)  -- 字符串替换 ✅
+
+-- 去空格和填充
+trim(string_col)             -- 去除首尾空格 ✅
+ltrim(string_col)            -- 去除左侧空格 ✅
+rtrim(string_col)            -- 去除右侧空格 ✅
+lpad(string_col, length, pad_str)  -- 左侧填充 ✅
+rpad(string_col, length, pad_str)  -- 右侧填充 ✅
+
+-- 正则表达式
+regexp_replace(string_col, pattern, replacement)  -- 正则替换 ✅
+regexp_extract(string_col, pattern, group_idx)    -- 正则提取 ✅
+```
+
+### 数学函数
+
+```sql
+-- 基础数学运算
+abs(number_col)              -- 绝对值 ✅
+round(number_col, decimals)  -- 四舍五入 ✅
+ceil(number_col)             -- 向上取整 ✅
+floor(number_col)            -- 向下取整 ✅
+mod(number_col, divisor)     -- 取模运算 ✅
+
+-- 数学计算
+pow(base, exponent)          -- 幂运算 ✅
+sqrt(number_col)             -- 平方根 ✅
+log10(number_col)            -- 以10为底的对数 ✅
+exp(number_col)              -- e的幂次方 ✅
+```
+
+### 类型转换函数
+
+```sql
+-- 常用类型转换
+cast(value as target_type)   -- 标准类型转换 ✅
+string(number_col)           -- 转为字符串 ✅
+int(string_col)              -- 转为整数 ✅
+double(string_col)           -- 转为双精度 ✅
+
+-- 安全转换
+try_cast(value as target_type)  -- 转换失败返回null ✅
+```
+
+### 条件表达式
+
+```sql
+-- ✅ 支持：if函数（三元表达式）
+if(condition, true_value, false_value)
+
+-- ✅ 支持：复杂嵌套
+if(condition1, value1,
+   if(condition2, value2,
+      if(condition3, value3, default_value)))
+
+-- ❌ 不支持：CASE WHEN
+-- CASE WHEN condition1 THEN value1 ELSE value2 END
+
+-- 空值处理
+coalesce(value1, value2, default_value)  -- 返回第一个非null值 ✅
+nvl(value, default_value)                -- 如果value为null则返回default_value ✅
+isnull(value)                            -- 判断是否为null ✅
+isnan(value)                             -- 判断是否为NaN ✅
+```
+
+### JSON函数
+
+```sql
+-- JSON提取
+get_json_object(json_col, '$.field')     -- 提取JSON字段值 ✅
+json_extract(json_col, '$.field')        -- 同上，别名 ✅
+```
+
+### 不支持的函数类型
+
+```sql
+-- ❌ 非确定性函数
+current_timestamp()          -- 当前时间戳
+current_date()               -- 当前日期
+random()                     -- 随机数
+uuid()                       -- UUID生成
+
+-- ❌ 聚合函数
+sum(column)                  -- 求和
+count(column)                -- 计数
+avg(column)                  -- 平均值
+
+-- ❌ 窗口函数
+row_number()                 -- 行号
+rank()                       -- 排名
+lag(column, offset)          -- 前一行值
+```
+
+***
+
+## 平台迁移指导
+
+### MySQL迁移
+
+```sql
+-- MySQL语法
+-- CREATE TABLE mysql_table (
+--     id INT,
+--     price DECIMAL(10,2),
+--     tax DECIMAL(10,2) AS (price * 0.1) STORED
+-- );
+
+-- 云器Lakehouse等价语法
+CREATE TABLE lakehouse_table (
+    id INT,
+    price DECIMAL(10,2),
+    tax DECIMAL(10,2) GENERATED ALWAYS AS (price * 0.1)
+);
+
+-- 主要差异：
+-- 1. MySQL: AS (expression) [STORED|VIRTUAL]
+-- 2. Lakehouse: GENERATED ALWAYS AS (expression)
+-- 3. Lakehouse只支持STORED模式（物理存储）
+```
+
+### PostgreSQL迁移
+
+```sql
+-- PostgreSQL语法
+-- CREATE TABLE postgres_table (
+--     id INT,
+--     first_name TEXT,
+--     last_name TEXT,
+--     full_name TEXT GENERATED ALWAYS AS (first_name || ' ' || last_name) STORED
+-- );
+
+-- 云器Lakehouse等价语法
+CREATE TABLE lakehouse_table (
+    id INT,
+    first_name STRING,
+    last_name STRING,
+    full_name STRING GENERATED ALWAYS AS (concat(first_name, ' ', last_name))
+);
+
+-- 主要差异：
+-- 1. 字符串连接：PostgreSQL用||，Lakehouse用concat()函数
+```
+
+### Oracle迁移
+
+```sql
+-- Oracle虚拟列语法
+-- CREATE TABLE oracle_table (
+--     id NUMBER,
+--     birth_date DATE,
+--     age NUMBER GENERATED ALWAYS AS (
+--         FLOOR(MONTHS_BETWEEN(SYSDATE, birth_date) / 12)
+--     ) VIRTUAL
+-- );
+
+-- 云器Lakehouse调整后语法
+CREATE TABLE lakehouse_table (
+    id INT,
+    birth_date DATE,
+    -- Oracle的SYSDATE是非确定性的，需要重新设计
+    year_part INT GENERATED ALWAYS AS (year(birth_date))
+);
+
+-- 主要差异：
+-- 1. Oracle支持非确定性函数，Lakehouse不支持
+-- 2. Oracle的CASE WHEN支持，Lakehouse需要用if()嵌套
+```
+
+### Hive/Spark迁移
+
+```sql
+-- Hive/Spark通常使用视图
+-- CREATE VIEW hive_view AS
+-- SELECT id, event_time, 
+--        hour(event_time) as hour_col,
+--        date_format(event_time, 'yyyy-MM-dd') as date_str
+-- FROM raw_table;
+
+-- 云器Lakehouse生成列：真实物理存储，性能更好
+CREATE TABLE lakehouse_table (
+    id INT,
+    event_time TIMESTAMP_LTZ,
+    hour_col INT GENERATED ALWAYS AS (hour(event_time)),
+    date_str STRING GENERATED ALWAYS AS (date_format(event_time, 'yyyy-MM-dd'))
+);
+
+-- 优势对比：
+-- Hive/Spark视图：查询时计算，性能开销大
+-- Lakehouse生成列：预计算存储，查询性能好
+```
+
+***
+
+## 高级使用场景
+
+### 生成列 + 分区组合
+
+```sql
+-- 时间分区自动化
+CREATE TABLE sales_auto_partition (
+    sale_id INT,
+    customer_id INT,
+    sale_time TIMESTAMP_LTZ,
+    amount DOUBLE,
+    sale_date STRING GENERATED ALWAYS AS (date_format(sale_time, 'yyyy-MM-dd'))
+) PARTITIONED BY (sale_date);
+
+-- 插入数据：无需计算分区值
+INSERT INTO sales_auto_partition (sale_id, customer_id, sale_time, amount) VALUES 
+(1001, 5001, TIMESTAMP '2024-06-19 14:30:00', 299.99),
+(1002, 5002, TIMESTAMP '2024-06-20 09:15:00', 599.00);
+
+-- 查询优势：自动分区裁剪
+SELECT * FROM sales_auto_partition 
+WHERE sale_time >= '2024-06-19'  -- 自动转换为分区条件
+  AND customer_id = 5001;
+```
+
+### 复杂业务逻辑封装
+
+```sql
+-- 业务逻辑封装在生成列中
+CREATE TABLE order_analysis (
+    order_id INT,
+    customer_id INT,
+    order_time TIMESTAMP_LTZ,
+    amount DOUBLE,
+    
+    -- 时间维度生成列
+    order_date STRING GENERATED ALWAYS AS (date_format(order_time, 'yyyy-MM-dd')),
+    order_hour INT GENERATED ALWAYS AS (hour(order_time)),
+    order_quarter STRING GENERATED ALWAYS AS (
+        concat(cast(year(order_time) as string), '-Q', cast(quarter(order_time) as string))
+    ),
+    
+    -- 业务逻辑生成列（使用if()嵌套）
+    amount_level STRING GENERATED ALWAYS AS (
+        if(amount >= 1000, 'HIGH',
+           if(amount >= 500, 'MEDIUM', 'LOW'))
+    ),
+    
+    -- 时间段分类
+    time_period STRING GENERATED ALWAYS AS (
+        if(hour(order_time) >= 6 AND hour(order_time) <= 11, 'MORNING',
+           if(hour(order_time) >= 12 AND hour(order_time) <= 17, 'AFTERNOON',
+              if(hour(order_time) >= 18 AND hour(order_time) <= 23, 'EVENING', 'NIGHT')))
+    )
+) PARTITIONED BY (order_date);
+```
+
+### 数据质量保证
+
+```sql
+-- 数据标准化和清洗
+CREATE TABLE customer_data_clean (
+    customer_id INT,
+    raw_phone STRING,
+    raw_email STRING,
+    registration_time TIMESTAMP_LTZ,
+    
+    -- 数据清洗生成列
+    clean_phone STRING GENERATED ALWAYS AS (
+        regexp_replace(raw_phone, '[^0-9]', '')  -- 只保留数字
+    ),
+    clean_email STRING GENERATED ALWAYS AS (
+        lower(trim(raw_email))  -- 转小写并去空格
+    ),
+    
+    -- 数据验证生成列
+    phone_valid STRING GENERATED ALWAYS AS (
+        if(length(regexp_replace(raw_phone, '[^0-9]', '')) = 11, 'VALID', 'INVALID')
+    ),
+    email_valid STRING GENERATED ALWAYS AS (
+        if(raw_email LIKE '%@%' AND raw_email LIKE '%.%', 'VALID', 'INVALID')
+    ),
+    
+    -- 注册时间维度
+    reg_date STRING GENERATED ALWAYS AS (date_format(registration_time, 'yyyy-MM-dd'))
+) PARTITIONED BY (reg_date);
+```
+
+### IoT传感器数据处理
+
+```sql
+-- IoT数据处理表
+CREATE TABLE iot_sensor_data (
+    sensor_id STRING,
+    device_id STRING,
+    timestamp_utc TIMESTAMP_LTZ,
+    temperature DOUBLE,
+    humidity DOUBLE,
+    pressure DOUBLE,
+    
+    -- 时间维度生成列
+    date_str STRING GENERATED ALWAYS AS (date_format(timestamp_utc, 'yyyy-MM-dd')),
+    hour_int INT GENERATED ALWAYS AS (hour(timestamp_utc)),
+    
+    -- 数据质量生成列
+    temp_status STRING GENERATED ALWAYS AS (
+        if(temperature IS NULL, 'MISSING',
+           if(temperature < -50 OR temperature > 80, 'OUTLIER', 'NORMAL'))
+    ),
+    
+    -- 业务分析生成列
+    temp_level STRING GENERATED ALWAYS AS (
+        if(temperature >= 30, 'HOT',
+           if(temperature >= 20, 'WARM',
+              if(temperature >= 10, 'COOL', 'COLD')))
+    ),
+    
+    -- 15分钟时间块
+    time_block STRING GENERATED ALWAYS AS (
+        concat(
+            cast(hour(timestamp_utc) as string),
+            ':',
+            cast((minute(timestamp_utc) / 15) * 15 as string)
+        )
+    )
+) PARTITIONED BY (date_str);
+```
+
+***
+
+## 使用限制和避坑指南
+
+### 关键限制
+
+#### 1. 条件表达式限制
+
+```sql
+-- ❌ 错误：使用CASE WHEN表达式（不支持）
+CREATE TABLE wrong_table (
+    score INT,
+    grade STRING GENERATED ALWAYS AS (
+        CASE 
+            WHEN score >= 90 THEN 'A'
+            WHEN score >= 80 THEN 'B'
+            ELSE 'C'
+        END
+    )
+);
+
+-- ✅ 正确做法：使用if()函数嵌套
+CREATE TABLE correct_table (
+    score INT,
+    grade STRING GENERATED ALWAYS AS (
+        if(score >= 90, 'A',
+           if(score >= 80, 'B', 'C'))
+    )
+);
+```
+
+#### 2. 函数支持限制
+
+```sql
+-- ❌ 常见错误：使用不支持的函数
+CREATE TABLE wrong_functions (
+    id INT,
+    created_at TIMESTAMP_LTZ GENERATED ALWAYS AS (current_timestamp()),  -- 非确定性
+    random_val DOUBLE GENERATED ALWAYS AS (random()),                    -- 非确定性
+    name_cap STRING GENERATED ALWAYS AS (initcap('test'))               -- 函数不存在
+);
+
+-- ✅ 正确做法：使用支持的确定性函数
+CREATE TABLE correct_functions (
+    id INT,
+    input_time TIMESTAMP_LTZ,
+    hour_part INT GENERATED ALWAYS AS (hour(input_time)),
+    formatted STRING GENERATED ALWAYS AS (date_format(input_time, 'yyyy-MM-dd'))
+);
+```
+
+#### 3. ALTER TABLE限制
+
+```sql
+-- ❌ 错误：不能在已有列上添加生成列属性
+-- ALTER TABLE existing_table MODIFY COLUMN existing_col GENERATED ALWAYS AS (expression);
+
+-- ✅ 正确做法：只能添加新的生成列
+ALTER TABLE existing_table ADD COLUMN 
+new_generated_col INT GENERATED ALWAYS AS (expression);
+```
+
+### 最佳实践
+
+1. **表达式设计原则**
+   * 使用if()嵌套替代CASE WHEN
+   * 使用简单确定性函数
+   * 确保表达式性能良好
+   * 注意返回类型与列类型匹配
+
+2. **命名规范建议**
+   ```sql
+   CREATE TABLE naming_example (
+       raw_timestamp TIMESTAMP_LTZ,           -- 基础列：原始数据
+       gen_hour INT GENERATED ALWAYS AS (hour(raw_timestamp)),              -- 生成列：gen_前缀
+       gen_date STRING GENERATED ALWAYS AS (date_format(raw_timestamp, 'yyyy-MM-dd'))
+   );
+   ```
+
+3. **函数使用建议**
+   * 验证函数支持：新函数使用前先创建测试表验证
+   * 使用try\_cast进行安全转换
+   * 注意函数语法差异
+
+***
+
+## 实战迁移案例
+
+### 案例1：电商订单表迁移（MySQL → 云器Lakehouse）
+
+#### 原始MySQL表结构
+
+```sql
+-- 原MySQL表：手动计算衍生字段
+CREATE TABLE orders_mysql (
+    order_id INT PRIMARY KEY,
+    customer_id INT,
+    order_time TIMESTAMP,
+    amount DECIMAL(10,2),
+    order_date DATE,           -- 手动计算
+    order_hour INT,           -- 手动计算
+    amount_level VARCHAR(10)  -- 手动计算
+);
+```
+
+#### 云器Lakehouse生成列方案
+
+```sql
+-- 迁移后的设计
+CREATE TABLE orders_lakehouse (
+    order_id INT,
+    customer_id INT,
+    order_time TIMESTAMP_LTZ,
+    amount DOUBLE,
+    -- 生成列：自动计算，确保一致性
+    order_date STRING GENERATED ALWAYS AS (date_format(order_time, 'yyyy-MM-dd')),
+    order_hour INT GENERATED ALWAYS AS (hour(order_time)),
+    amount_level STRING GENERATED ALWAYS AS (
+        if(amount >= 1000, 'HIGH',
+           if(amount >= 500, 'MEDIUM', 'LOW'))
+    )
+) PARTITIONED BY (order_date);
+
+-- 应用程序只需插入基础字段
+INSERT INTO orders_lakehouse (order_id, customer_id, order_time, amount) VALUES 
+(1001, 5001, TIMESTAMP '2024-06-19 14:30:00', 299.99);
+```
+
+#### 迁移效果对比
+
+* **查询速度**：提升60%（避免重复计算）
+* **开发效率**：提升80%（无需手动计算逻辑）
+* **数据一致性**：提升100%（统一计算逻辑）
+
+***
+
+## 性能优化建议
+
+### 索引策略
+
+* 为经常用于WHERE条件和GROUP BY的生成列创建索引
+* 时间维度的生成列通常需要索引
+* 监控生成列的基数，基数过低的生成列不适合创建索引
+
+### 表达式优化
+
+* 表达式设计要简洁高效
+* 避免过于复杂的嵌套if()语句
+* 复杂逻辑可以拆分为多个简单的生成列
+* 建议每张表的生成列数量控制在5-10个以内
+
+### 查询优化
+
+* 使用生成列而不是重新计算原表达式
+* 确保分区值分布均匀，避免数据倾斜
+* 定期检查生成列的查询性能表现
+
+***
+
+## 故障排查手册
+
+### 基础功能验证
+
+```sql
+-- 1. 表结构验证
+DESCRIBE TABLE your_table_name;
+-- 检查：生成列是否出现在列表中，数据类型是否正确
+
+-- 2. 基本插入测试
+INSERT INTO your_table_name (base_column1, base_column2) VALUES (test_value1, test_value2);
+-- 检查：是否能成功插入数据
+
+-- 3. 生成列值验证
+SELECT base_column1, base_column2, generated_column1, generated_column2 FROM your_table_name;
+-- 检查：生成列的值是否符合预期表达式结果
+
+-- 4. 插入保护机制验证
+-- INSERT INTO your_table_name (base_column1, generated_column1) VALUES (value1, invalid_value);
+-- 检查：是否正确报错"cannot insert or update generated column"
+```
+
+### 高级功能验证
+
+```sql
+-- 5. 分区生成列验证（如果使用）
+SHOW PARTITIONS your_partitioned_table;
+-- 检查：分区是否按生成列的值正确创建
+
+-- 6. 复杂表达式验证
+SELECT generated_column, 
+       manual_calculation_expression,  -- 手动计算作为对比
+       if(generated_column = manual_calculation_expression, 'MATCH', 'MISMATCH') as validation
+FROM your_table_name;
+-- 检查：生成列值与手动计算是否一致
+```
+
+### 常见问题排查
+
+#### 问题1：CASE WHEN表达式不支持
+
+**解决方案**：改用if()嵌套
+
+```sql
+-- 原CASE WHEN逻辑：
+-- CASE WHEN score >= 90 THEN 'A' WHEN score >= 80 THEN 'B' ELSE 'C' END
+
+-- 改为if()嵌套：
+if(score >= 90, 'A', if(score >= 80, 'B', 'C'))
+```
+
+#### 问题2：函数不支持
+
+**解决方案**：使用支持的函数替代
+
+```sql
+-- log(x) -> log10(x)
+-- initcap(str) -> 使用upper/lower组合
+-- CASE WHEN -> if()嵌套
+```
+
+***
+
+## 快速参考
+
+### 生成列管理常用语法
+
+| 功能         | 语法模板                                                                    | 使用场景   |
+| ---------- | ----------------------------------------------------------------------- | ------ |
+| **创建表时定义** | `column_name data_type GENERATED ALWAYS AS (expression)`                | 新表设计   |
+| **添加生成列**  | `ALTER TABLE table ADD COLUMN col_name type GENERATED ALWAYS AS (expr)` | 表结构演进  |
+| **时间维度提取** | `GENERATED ALWAYS AS (hour/day/month/year(timestamp_col))`              | 时间分析   |
+| **字符串格式化** | `GENERATED ALWAYS AS (date_format(time_col, 'format'))`                 | 日期格式转换 |
+| **条件逻辑**   | `GENERATED ALWAYS AS (if(condition, value, default))`                   | 业务分类   |
+| **嵌套条件**   | `GENERATED ALWAYS AS (if(cond1, val1, if(cond2, val2, val3)))`          | 复杂业务逻辑 |
+
+### 平台语法对照
+
+| 功能        | MySQL语法                  | PostgreSQL语法                              | Lakehouse语法                        |
+| --------- | ------------------------ | ----------------------------------------- | ---------------------------------- |
+| **基本生成列** | `AS (expression) STORED` | `GENERATED ALWAYS AS (expression) STORED` | `GENERATED ALWAYS AS (expression)` |
+| **字符串连接** | `CONCAT(col1, col2)`     | `col1 \|\| col2`                          | `concat(col1, col2)`               |
+| **条件表达式** | `CASE WHEN ... END`      | `CASE WHEN ... END`                       | `if(condition, value, default)`    |
+
+### 条件逻辑对照表
+
+| 传统CASE WHEN                                                                            | Lakehouse if()嵌套                                                 |
+| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `CASE WHEN score >= 90 THEN 'A' ELSE 'B' END`                                          | `if(score >= 90, 'A', 'B')`                                      |
+| `CASE WHEN amount >= 1000 THEN 'HIGH' WHEN amount >= 500 THEN 'MEDIUM' ELSE 'LOW' END` | `if(amount >= 1000, 'HIGH', if(amount >= 500, 'MEDIUM', 'LOW'))` |
+
+### 确定性函数速查
+
+| 类别        | 支持的函数                                                        | 典型用法                                  |
+| --------- | ------------------------------------------------------------ | ------------------------------------- |
+| **时间函数**  | `year, month, day, hour, minute, second, quarter, dayofweek` | `hour(timestamp_col)`                 |
+| **日期格式**  | `date_format, date_add, date_sub, datediff`                  | `date_format(date_col, 'yyyy-MM-dd')` |
+| **字符串函数** | `upper, lower, length, substring, trim, concat, concat_ws`   | `upper(string_col)`                   |
+| **数学函数**  | `abs, round, ceil, floor, mod, sqrt, pow, log10`             | `round(number_col, 2)`                |
+| **条件表达式** | `if(condition, true_val, false_val)`                         | 业务逻辑分类                                |
+| **类型转换**  | `cast, try_cast`                                             | `cast(number_col as string)`          |
+
+***
+
+## 总结
+
+### 核心价值
+
+1. **统一计算逻辑**：避免应用层计算差异，确保数据一致性
+2. **简化查询开发**：预计算常用的衍生字段，减少重复编码
+3. **支持灵活分区**：基于计算结果自动分区，优化查询性能
+4. **降低维护成本**：集中定义计算规则，统一管理业务逻辑
+
+### 实施检查清单
+
+#### 设计阶段
+
+* [ ] 确认表达式只使用确定性函数
+* [ ] 将CASE WHEN改为if()嵌套语法
+* [ ] 验证表达式返回类型与列类型匹配
+* [ ] 评估生成列的查询频率和性能价值
+
+#### 实施阶段
+
+* [ ] 使用原生SQL语法创建生成列
+* [ ] 执行完整的验证清单
+* [ ] 测试插入保护机制是否正常
+* [ ] 验证存量数据自动回填功能
+
+#### 优化阶段
+
+* [ ] 为高频查询的生成列创建索引
+* [ ] 监控生成列的查询性能表现
+* [ ] 定期评估和优化表达式复杂度
+* [ ] 建立生成列使用的团队规范
+
+### 关键要点
+
+**对于从传统关系型数据库迁移的用户**：
+生成列可以极大简化您的应用架构。原来需要在应用程序中维护的计算逻辑，现在可以统一定义在数据库层，确保数据一致性的同时提升查询性能。注意将CASE WHEN表达式改为if()嵌套语法。
+
+**对于从大数据平台迁移的用户**：
+相比视图或子查询方案，生成列提供了更好的性能保证。预计算并物理存储的特性，让您的分析查询响应更快，运维更简单。分区生成列功能特别适合大数据场景。
+
+生成列不仅仅是一个技术特性，而是数据架构现代化的重要工具。正确使用生成列，您将获得更高的开发效率、更好的数据一致性和更优的查询性能。
+
+***
+
+**注意**：本文档基于Lakehouse 2025年6月的产品文档整理，建议定期查看官方文档获取最新更新。在生产环境中使用前，请务必在测试环境中验证所有操作的正确性和性能影响。