@clickzetta/cz-cli-darwin-x64 0.3.92 → 0.3.94

package/bin/skills/{clickzetta-sql-syntax-guide → clickzetta-sql-migration}/references/migration-snowflake.md

@@ -1,28 +1,28 @@
-# Snowflake → ClickZetta 迁移指南
+# Snowflake → ClickZetta Migration Guide
 
-> 全面覆盖从 Snowflake 迁移到 ClickZetta Lakehouse 时遇到的 SQL 兼容性问题，所有结论均经过真实 Lakehouse 验证。
+> Comprehensive coverage of SQL compatibility issues when migrating from Snowflake to ClickZetta Lakehouse. All conclusions verified on a real Lakehouse instance.
 
 ---
 
-## 对象概念映射
+## Object Concept Mapping
 
-| Snowflake | ClickZetta | 说明 |
+| Snowflake | ClickZetta | Description |
 |---|---|---|
-| DATABASE | WORKSPACE | 顶层容器 |
-| SCHEMA | SCHEMA | 相同 |
-| WAREHOUSE | VCLUSTER | 计算集群 |
-| STAGE | VOLUME | 文件存储区域 |
-| STORAGE INTEGRATION | STORAGE CONNECTION | 对象存储认证 |
-| SNOWPIPE | PIPE | 持续导入管道 |
-| STREAM | TABLE STREAM | CDC 变更捕获 |
-| DYNAMIC TABLE | DYNAMIC TABLE | 语法不同 |
-| TASK | Studio 任务 | 调度任务 |
-| SEQUENCE | IDENTITY 列 | 自增序列 |
-| SHARE | SHARE | 跨实例数据共享（语法相同） |
+| DATABASE | WORKSPACE | Top-level container |
+| SCHEMA | SCHEMA | Same |
+| WAREHOUSE | VCLUSTER | Compute cluster |
+| STAGE | VOLUME | File storage area |
+| STORAGE INTEGRATION | STORAGE CONNECTION | Object storage authentication |
+| SNOWPIPE | PIPE | Continuous ingestion pipeline |
+| STREAM | TABLE STREAM | CDC change capture |
+| DYNAMIC TABLE | DYNAMIC TABLE | Different syntax |
+| TASK | Studio Task | Scheduled tasks |
+| SEQUENCE | IDENTITY column | Auto-increment sequence |
+| SHARE | SHARE | Cross-instance data sharing (same syntax) |
 
 ---
 
-## DDL 差异
+## DDL Differences
 
 ### CREATE TABLE
 
@@ -38,7 +38,7 @@ CREATE OR REPLACE TABLE orders (
     tags ARRAY
 ) CLUSTER BY (DATE_TRUNC('month', created_at));
 
--- ClickZetta 等价写法
+-- ClickZetta equivalent
 CREATE TABLE IF NOT EXISTS orders (
     id BIGINT IDENTITY(1),          -- AUTOINCREMENT → IDENTITY
     customer_id INT,                 -- NUMBER(10,0) → INT
@@ -46,99 +46,99 @@ CREATE TABLE IF NOT EXISTS orders (
     status STRING DEFAULT 'pending',
     created_at TIMESTAMP DEFAULT current_timestamp(),
     meta JSON,                       -- VARIANT → JSON
-    tags ARRAY<STRING>               -- ARRAY → ARRAY<T>（需指定元素类型）
+    tags ARRAY<STRING>               -- ARRAY → ARRAY<T> (must specify element type)
 )
 CLUSTERED BY (customer_id) INTO 16 BUCKETS;  -- CLUSTER BY → CLUSTERED BY ... BUCKETS
 ```
 
-### 不支持的 DDL
+### Unsupported DDL
 
 ```sql
--- ❌ CREATE OR REPLACE TABLE（用 IF NOT EXISTS）
+-- ❌ CREATE OR REPLACE TABLE (use IF NOT EXISTS)
 CREATE OR REPLACE TABLE t (...);
 -- ✅ ClickZetta
 CREATE TABLE IF NOT EXISTS t (...);
 
--- ❌ CREATE SEQUENCE（用 IDENTITY 列）
+-- ❌ CREATE SEQUENCE (use IDENTITY column)
 CREATE SEQUENCE my_seq START 1 INCREMENT 1;
 -- ✅ ClickZetta
 CREATE TABLE t (id BIGINT IDENTITY(1), ...);
 
--- ❌ CREATE TEMPORARY TABLE（用 CTE 替代）
+-- ❌ CREATE TEMPORARY TABLE (use CTE instead)
 CREATE TEMPORARY TABLE temp_t AS SELECT ...;
 -- ✅ ClickZetta
 WITH temp_t AS (SELECT ...) SELECT * FROM temp_t;
 
--- ❌ CREATE TRANSIENT TABLE（用 data_lifecycle 控制）
+-- ❌ CREATE TRANSIENT TABLE (use data_lifecycle to control)
 CREATE TRANSIENT TABLE t (...);
 -- ✅ ClickZetta
 CREATE TABLE t (...) PROPERTIES ('data_lifecycle' = '1');
 
--- ❌ CLUSTER BY（列级别）
+-- ❌ CLUSTER BY (column-level)
 CREATE TABLE t (...) CLUSTER BY (col1, col2);
--- ✅ ClickZetta（分桶）
+-- ✅ ClickZetta (bucketing)
 CREATE TABLE t (...) CLUSTERED BY (col1) INTO 16 BUCKETS;
 ```
 
 ---
 
-## 数据类型映射
+## Data Type Mapping
 
-| Snowflake | ClickZetta | 注意事项 |
+| Snowflake | ClickZetta | Notes |
 |---|---|---|
 | `NUMBER(p,s)` / `NUMERIC(p,s)` | `DECIMAL(p,s)` | |
 | `NUMBER(10,0)` / `INTEGER` | `INT` / `BIGINT` | |
 | `FLOAT` / `FLOAT4` | `FLOAT` | |
 | `FLOAT8` / `DOUBLE` | `DOUBLE` | |
-| `VARCHAR(n)` / `TEXT` | `STRING` 或 `VARCHAR(n)` | |
-| `CHAR(n)` | `CHAR(n)` | 相同 |
-| `BOOLEAN` | `BOOLEAN` | 相同，但写入规则不同（见下） |
-| `DATE` | `DATE` | 相同 |
-| `TIMESTAMP_LTZ` | `TIMESTAMP` | 带本地时区 |
-| `TIMESTAMP_NTZ` | `TIMESTAMP_NTZ` | 无时区 |
-| `TIMESTAMP_TZ` | `TIMESTAMP` | ClickZetta 无独立 TZ 类型 |
-| `VARIANT` | `JSON` | 访问语法不同（见下） |
-| `ARRAY` | `ARRAY<T>` | 需指定元素类型 |
-| `OBJECT` | `MAP<STRING,STRING>` 或 `STRUCT<...>` | |
-| `GEOGRAPHY` | 不支持 | |
-| `VECTOR(FLOAT, N)` | `VECTOR(FLOAT, N)` | 相同 |
+| `VARCHAR(n)` / `TEXT` | `STRING` or `VARCHAR(n)` | |
+| `CHAR(n)` | `CHAR(n)` | Same |
+| `BOOLEAN` | `BOOLEAN` | Same, but different write rules (see below) |
+| `DATE` | `DATE` | Same |
+| `TIMESTAMP_LTZ` | `TIMESTAMP` | With local timezone |
+| `TIMESTAMP_NTZ` | `TIMESTAMP_NTZ` | Without timezone |
+| `TIMESTAMP_TZ` | `TIMESTAMP` | ClickZetta has no separate TZ type |
+| `VARIANT` | `JSON` | Different access syntax (see below) |
+| `ARRAY` | `ARRAY<T>` | Must specify element type |
+| `OBJECT` | `MAP<STRING,STRING>` or `STRUCT<...>` | |
+| `GEOGRAPHY` | Not supported | |
+| `VECTOR(FLOAT, N)` | `VECTOR(FLOAT, N)` | Same |
 
 ---
 
-## ⚠️ 写入时类型转换（重要差异）
+## ⚠️ Type Conversion on Write (Important Difference)
 
-Snowflake 允许字符串隐式转换为日期/布尔等类型，ClickZetta **不允许**：
+Snowflake allows implicit string conversion to date/boolean types; ClickZetta **does not**:
 
 ```sql
--- ❌ Snowflake 可以，ClickZetta 报错
+-- ❌ Works in Snowflake, errors in ClickZetta
 INSERT INTO t VALUES ('2024-01-15', 'true', '123');
 
--- ✅ ClickZetta 必须显式转换
+-- ✅ ClickZetta requires explicit conversion
 INSERT INTO t VALUES (DATE '2024-01-15', TRUE, CAST('123' AS INT));
 INSERT INTO t VALUES (CAST('2024-01-15' AS DATE), CAST('true' AS BOOLEAN), 123);
 ```
 
-| 目标类型 | Snowflake | ClickZetta |
+| Target Type | Snowflake | ClickZetta |
 |---|---|---|
-| `DATE` ← `'2024-01-15'` | ✅ 隐式 | ❌ 需 `DATE '...'` 或 `CAST` |
-| `TIMESTAMP` ← `'2024-01-15 12:00'` | ✅ 隐式 | ❌ 需 `TIMESTAMP '...'` 或 `CAST` |
-| `BOOLEAN` ← `'true'` | ✅ 隐式 | ❌ 需 `TRUE`/`FALSE` 或 `CAST` |
-| `BOOLEAN` ← `1` | ✅ 隐式 | ❌ 需 `CAST(1 AS BOOLEAN)` |
-| `INT` ← `'123'` | ✅ 隐式 | ❌ 需 `CAST('123' AS INT)` |
-| `JSON` ← `'{"k":1}'` | ✅ 隐式 | ❌ 需 `PARSE_JSON(...)` 或 `CAST` |
-| WHERE 中字符串比较 | ✅ | ✅ 允许 |
+| `DATE` ← `'2024-01-15'` | ✅ Implicit | ❌ Requires `DATE '...'` or `CAST` |
+| `TIMESTAMP` ← `'2024-01-15 12:00'` | ✅ Implicit | ❌ Requires `TIMESTAMP '...'` or `CAST` |
+| `BOOLEAN` ← `'true'` | ✅ Implicit | ❌ Requires `TRUE`/`FALSE` or `CAST` |
+| `BOOLEAN` ← `1` | ✅ Implicit | ❌ Requires `CAST(1 AS BOOLEAN)` |
+| `INT` ← `'123'` | ✅ Implicit | ❌ Requires `CAST('123' AS INT)` |
+| `JSON` ← `'{"k":1}'` | ✅ Implicit | ❌ Requires `PARSE_JSON(...)` or `CAST` |
+| String comparison in WHERE | ✅ | ✅ Allowed |
 
 ---
 
-## DML 差异
+## DML Differences
 
 ### INSERT / UPDATE
 
 ```sql
--- Snowflake：字符串可隐式转换
+-- Snowflake: strings can be implicitly converted
 INSERT INTO orders VALUES (1, '2024-01-15', 'true');
 
--- ClickZetta：必须显式转换
+-- ClickZetta: must explicitly convert
 INSERT INTO orders VALUES (1, DATE '2024-01-15', TRUE);
 UPDATE orders SET dt = CAST('2024-06-01' AS DATE) WHERE id = 1;
 ```
@@ -146,41 +146,41 @@ UPDATE orders SET dt = CAST('2024-06-01' AS DATE) WHERE id = 1;
 ### MERGE INTO
 
 ```sql
--- Snowflake：支持多个 WHEN NOT MATCHED，支持 WHEN NOT MATCHED BY SOURCE
+-- Snowflake: supports multiple WHEN NOT MATCHED, supports WHEN NOT MATCHED BY SOURCE
 MERGE INTO t USING s ON t.id = s.id
 WHEN MATCHED THEN UPDATE SET ...
 WHEN NOT MATCHED THEN INSERT ...
-WHEN NOT MATCHED BY SOURCE THEN DELETE;  -- ❌ ClickZetta 不支持
+WHEN NOT MATCHED BY SOURCE THEN DELETE;  -- ❌ ClickZetta does not support
 
--- ClickZetta：WHEN NOT MATCHED 只能有一个，UPDATE 必须在 DELETE 前
+-- ClickZetta: WHEN NOT MATCHED can only appear once, UPDATE must come before DELETE
 MERGE INTO t USING s ON t.id = s.id
-WHEN MATCHED AND s.flag = 0 THEN UPDATE SET t.val = s.val  -- UPDATE 在前
-WHEN MATCHED AND s.flag = 1 THEN DELETE                    -- DELETE 在后
+WHEN MATCHED AND s.flag = 0 THEN UPDATE SET t.val = s.val  -- UPDATE first
+WHEN MATCHED AND s.flag = 1 THEN DELETE                    -- DELETE second
 WHEN NOT MATCHED THEN INSERT (id, val) VALUES (s.id, s.val);
 ```
 
-### 事务
+### Transactions
 
 ```sql
--- ❌ ClickZetta 不支持事务语法
+-- ❌ ClickZetta does not support transaction syntax
 BEGIN;
 BEGIN TRANSACTION;
 START TRANSACTION;
 COMMIT;
 ROLLBACK;
 
--- ✅ 用 MERGE 实现原子性 UPSERT
+-- ✅ Use MERGE for atomic UPSERT
 MERGE INTO target USING source ON ...
 ```
 
 ---
 
-## DQL 差异
+## DQL Differences
 
-### QUALIFY（窗口函数过滤）
+### QUALIFY (Window Function Filtering)
 
 ```sql
--- 两者都支持 QUALIFY
+-- Both support QUALIFY
 SELECT * FROM orders
 QUALIFY ROW_NUMBER() OVER (PARTITION BY customer_id ORDER BY created_at DESC) = 1;
 ```
@@ -188,11 +188,11 @@ QUALIFY ROW_NUMBER() OVER (PARTITION BY customer_id ORDER BY created_at DESC) =
 ### PIVOT / UNPIVOT
 
 ```sql
--- Snowflake：原生支持
+-- Snowflake: natively supported
 SELECT * FROM sales
 PIVOT (SUM(amount) FOR month IN ('Jan', 'Feb', 'Mar'));
 
--- ClickZetta：用 CASE WHEN
+-- ClickZetta: use CASE WHEN
 SELECT product,
     SUM(CASE WHEN month = 'Jan' THEN amount END) AS Jan,
     SUM(CASE WHEN month = 'Feb' THEN amount END) AS Feb
@@ -202,35 +202,35 @@ FROM sales GROUP BY product;
 ### LATERAL FLATTEN → LATERAL VIEW EXPLODE
 
 ```sql
--- Snowflake：LATERAL FLATTEN
+-- Snowflake: LATERAL FLATTEN
 SELECT f.value::STRING AS skill
 FROM employees, LATERAL FLATTEN(input => skills) f;
 
--- ClickZetta：LATERAL VIEW EXPLODE
+-- ClickZetta: LATERAL VIEW EXPLODE
 SELECT skill
 FROM employees
 LATERAL VIEW EXPLODE(skills) lv AS skill;
 
--- 带位置索引
+-- With position index
 SELECT pos, skill
 FROM employees
 LATERAL VIEW POSEXPLODE(skills) lv AS pos, skill;
 ```
 
-### JSON 访问语法
+### JSON Access Syntax
 
 ```sql
--- Snowflake：冒号语法
+-- Snowflake: colon syntax
 SELECT data:address:city AS city FROM users;
 SELECT data[0]:name AS name FROM users;
 SELECT data:scores[2] AS score FROM users;
 
--- ClickZetta：方括号语法
+-- ClickZetta: bracket syntax
 SELECT data['address']['city'] AS city FROM users;
 SELECT data['phoneNumbers'][0]['name'] AS name FROM users;
 SELECT data['scores'][2] AS score FROM users;
 
--- 类型转换
+-- Type conversion
 -- Snowflake: data:age::INT
 -- ClickZetta: CAST(data['age'] AS INT)
 ```
@@ -243,92 +243,92 @@ SELECT OBJECT_CONSTRUCT('name', 'Alice', 'age', 30) AS obj;
 SELECT ARRAY_CONSTRUCT(1, 2, 3) AS arr;
 
 -- ClickZetta
-SELECT MAP('name', 'Alice') AS obj;          -- 简单 MAP
-SELECT named_struct('id', 1, 'name', 'Alice') AS person;  -- ✅ 命名字段用 named_struct
-SELECT STRUCT(1, 'Alice') AS person;         -- 位置参数写法
+SELECT MAP('name', 'Alice') AS obj;          -- simple MAP
+SELECT named_struct('id', 1, 'name', 'Alice') AS person;  -- ✅ named fields use named_struct
+SELECT STRUCT(1, 'Alice') AS person;         -- positional parameter syntax
 SELECT ARRAY(1, 2, 3) AS arr;               -- ARRAY_CONSTRUCT → ARRAY()
 ```
 
 ### ASOF JOIN / MATCH_RECOGNIZE
 
 ```sql
--- ❌ ClickZetta 不支持
+-- ❌ ClickZetta does not support
 SELECT * FROM t1 ASOF JOIN t2 ON t1.id = t2.id;
 SELECT * FROM t MATCH_RECOGNIZE (...);
 ```
 
 ---
 
-## 函数差异
+## Function Differences
 
-### 日期函数
+### Date Functions
 
 ```sql
 -- Snowflake → ClickZetta
-DATEADD(day, 7, dt)          → DATEADD(day, 7, dt)  ✅ 相同；也可用 DATE_ADD(dt, 7)
-DATEDIFF(day, start, end)    → DATEDIFF(end, start)  ⚠️ 参数顺序相反！
-DATE_TRUNC('month', dt)      → DATE_TRUNC('month', dt)  相同
-TO_DATE('2024-01-01')        → TO_DATE('2024-01-01')  相同
+DATEADD(day, 7, dt)          → DATEADD(day, 7, dt)  ✅ same; also DATE_ADD(dt, 7)
+DATEDIFF(day, start, end)    → DATEDIFF(end, start)  ⚠️ parameter order reversed!
+DATE_TRUNC('month', dt)      → DATE_TRUNC('month', dt)  same
+TO_DATE('2024-01-01')        → TO_DATE('2024-01-01')  same
 CONVERT_TIMEZONE(tz, dt)     → CONVERT_TZ(dt, from_tz, to_tz)
 SYSDATE() / GETDATE()        → CURRENT_TIMESTAMP() / NOW()
-LAST_DAY(dt)                 → LAST_DAY(dt)  相同
-YEAR(dt) / MONTH(dt)         → YEAR(dt) / MONTH(dt)  相同
+LAST_DAY(dt)                 → LAST_DAY(dt)  same
+YEAR(dt) / MONTH(dt)         → YEAR(dt) / MONTH(dt)  same
 ```
 
-### 字符串函数
+### String Functions
 
 ```sql
 -- Snowflake → ClickZetta
-CHARINDEX(sub, s)            → INSTR(s, sub)  ⚠️ 参数顺序相反！
+CHARINDEX(sub, s)            → INSTR(s, sub)  ⚠️ parameter order reversed!
 EDITDISTANCE(s1, s2)         → LEVENSHTEIN(s1, s2)
 STRTOK(s, delim, n)          → SPLIT_PART(s, delim, n)
-ILIKE(s, pattern)            → ILIKE(s, pattern)  ✅ ClickZetta 也支持！
+ILIKE(s, pattern)            → ILIKE(s, pattern)  ✅ ClickZetta also supports!
 CONTAINS(s, sub)             → INSTR(s, sub) > 0
 STARTSWITH(s, prefix)        → s LIKE 'prefix%'
 ENDSWITH(s, suffix)          → s LIKE '%suffix'
-INITCAP(s)                   → INITCAP(s)  相同
-REGEXP_LIKE(s, p)            → RLIKE(s, p) 或 s RLIKE p
+INITCAP(s)                   → INITCAP(s)  same
+REGEXP_LIKE(s, p)            → RLIKE(s, p) or s RLIKE p
 ```
 
-### 聚合函数
+### Aggregate Functions
 
 ```sql
 -- Snowflake → ClickZetta
 LISTAGG(col, ',') WITHIN GROUP (ORDER BY col)  → GROUP_CONCAT(col ORDER BY col SEPARATOR ',')
-ARRAY_AGG(col) WITHIN GROUP (ORDER BY col)     → ARRAY_AGG(col)  ⚠️ 不支持 WITHIN GROUP
+ARRAY_AGG(col) WITHIN GROUP (ORDER BY col)     → ARRAY_AGG(col)  ⚠️ WITHIN GROUP not supported
 OBJECT_AGG(key, value)                         → MAP_AGG(key, value)
-APPROX_COUNT_DISTINCT(col)                     → APPROX_COUNT_DISTINCT(col)  相同
-MEDIAN(col)                                    → MEDIAN(col)  相同
+APPROX_COUNT_DISTINCT(col)                     → APPROX_COUNT_DISTINCT(col)  same
+MEDIAN(col)                                    → MEDIAN(col)  same
 ```
 
-### 条件函数
+### Conditional Functions
 
 ```sql
 -- Snowflake → ClickZetta
 IFF(cond, a, b)              → IF(cond, a, b)
-ZEROIFNULL(x)                → COALESCE(x, 0) 或 NVL(x, 0)
+ZEROIFNULL(x)                → COALESCE(x, 0) or NVL(x, 0)
 NULLIFZERO(x)                → NULLIF(x, 0)
-DECODE(expr, v1, r1, ...)    → DECODE(expr, v1, r1, ...)  相同
+DECODE(expr, v1, r1, ...)    → DECODE(expr, v1, r1, ...)  same
 BOOLAND(a, b)                → a AND b
 BOOLOR(a, b)                 → a OR b
 ```
 
 ---
 
-## Stream 元数据字段
+## Stream Metadata Fields
 
 ```sql
 -- Snowflake Stream
 METADATA$ACTION        -- 'INSERT' / 'DELETE'
-METADATA$ISUPDATE      -- TRUE/FALSE（UPDATE 会产生一对 DELETE+INSERT）
-METADATA$ROW_ID        -- 行唯一标识
+METADATA$ISUPDATE      -- TRUE/FALSE (UPDATE produces a DELETE+INSERT pair)
+METADATA$ROW_ID        -- row unique identifier
 
 -- ClickZetta Table Stream
 __change_type          -- 'INSERT' / 'UPDATE_BEFORE' / 'UPDATE_AFTER' / 'DELETE'
-__commit_version       -- 提交版本号
-__commit_timestamp     -- 提交时间戳
+__commit_version       -- commit version number
+__commit_timestamp     -- commit timestamp
 
--- 消费 Stream 的 MERGE 写法
+-- MERGE pattern for consuming Stream
 -- Snowflake
 MERGE INTO target t USING stream s ON t.id = s.id
 WHEN MATCHED AND s.METADATA$ACTION = 'DELETE' THEN DELETE
@@ -344,7 +344,7 @@ WHEN NOT MATCHED AND s.__change_type = 'INSERT' THEN INSERT ...;
 
 ---
 
-## Dynamic Table 差异
+## Dynamic Table Differences
 
 ```sql
 -- Snowflake
@@ -353,7 +353,7 @@ CREATE DYNAMIC TABLE product_sales
     WAREHOUSE = my_warehouse
 AS SELECT ...;
 
--- ClickZetta（不支持 TARGET_LAG）
+-- ClickZetta (does not support TARGET_LAG)
 CREATE DYNAMIC TABLE product_sales
     REFRESH INTERVAL 1 MINUTE VCLUSTER default_ap
 AS SELECT ...;
@@ -361,13 +361,13 @@ AS SELECT ...;
 
 ---
 
-## 已验证的兼容性（Snowflake 有，ClickZetta 也有）
+## Verified Compatibility (Snowflake has it, ClickZetta also has it)
 
 - `SEMI JOIN` / `ANTI JOIN` ✅
-- `QUALIFY` ✅（ClickZetta 也支持）
-- `ILIKE` ✅（ClickZetta 也支持）
-- `DATEADD` ✅（ClickZetta 也支持）
-- `MINUS`（等价于 EXCEPT）✅
+- `QUALIFY` ✅ (ClickZetta also supports)
+- `ILIKE` ✅ (ClickZetta also supports)
+- `DATEADD` ✅ (ClickZetta also supports)
+- `MINUS` (equivalent to EXCEPT) ✅
 - `DECODE` ✅
 - `INITCAP` ✅
 - `MEDIAN` ✅
@@ -379,4 +379,4 @@ AS SELECT ...;
 - `REGEXP_LIKE` / `RLIKE` ✅
 - `SPLIT_PART` ✅
 - `LAST_DAY` ✅
-- `IDENTITY` 列（替代 AUTOINCREMENT/SEQUENCE）✅
+- `IDENTITY` column (replaces AUTOINCREMENT/SEQUENCE) ✅