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

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

@@ -1,847 +0,0 @@
-# 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月的产品文档整理，建议定期查看官方文档获取最新更新。在生产环境中使用前，请务必在测试环境中验证所有操作的正确性和性能影响。