@clickzetta/cz-cli-linux-x64 0.3.0 → 0.3.1

package/bin/skills/clickzetta-sql-syntax-guide/references/vs-snowflake.md

@@ -0,0 +1,346 @@
+# ClickZetta Lakehouse vs Snowflake SQL 差异
+
+> 来源：产品文档 + 迁移实践
+
+## 对象概念映射
+
+| ClickZetta Lakehouse | Snowflake | 说明 |
+|---|---|---|
+| WORKSPACE | DATABASE | 工作空间 ≈ 数据库 |
+| SCHEMA | SCHEMA | 相同 |
+| VCLUSTER | WAREHOUSE | 计算集群 |
+| STORAGE CONNECTION | STORAGE INTEGRATION | 对象存储认证 |
+| VOLUME | STAGE | 文件存储区域 |
+| TABLE | TABLE | 相同 |
+| PIPE | SNOWPIPE | 持续导入管道 |
+| TABLE STREAM | STREAM | 变更数据捕获 |
+| DYNAMIC TABLE | DYNAMIC TABLE | 增量计算表（语法不同） |
+| Studio 任务 | TASK | 调度任务 |
+
+---
+
+## DDL 差异
+
+### CREATE OR REPLACE vs IF NOT EXISTS
+
+```sql
+-- Snowflake：支持 CREATE OR REPLACE
+CREATE OR REPLACE TABLE orders (id INT, amount DECIMAL);
+
+-- ClickZetta：不支持 CREATE OR REPLACE，用 IF NOT EXISTS
+CREATE TABLE IF NOT EXISTS orders (id INT, amount DECIMAL);
+-- 修改已有表用 ALTER TABLE
+```
+
+### 注释语法
+
+```sql
+-- Snowflake：支持 // 和 ///
+// 这是注释
+/// 这也是注释
+
+-- ClickZetta：只支持 -- 和 /* */
+-- 这是注释
+/* 这也是注释 */
+```
+
+### 数据类型差异
+
+| ClickZetta | Snowflake | 说明 |
+|---|---|---|
+| `STRING` | `VARCHAR` / `TEXT` | ClickZetta 推荐用 STRING |
+| `TIMESTAMP` | `TIMESTAMP_LTZ` | 本地时区时间戳 |
+| `TIMESTAMP_NTZ` | `TIMESTAMP_NTZ` | 无时区时间戳 |
+| `JSON` | `VARIANT` | 半结构化数据 |
+| `ARRAY<T>` | `ARRAY` | ClickZetta 需指定元素类型 |
+| `MAP<K,V>` | `OBJECT` | 键值对 |
+| `STRUCT<f:T,...>` | `OBJECT` | 结构体 |
+| `VECTOR(FLOAT, N)` | 无原生支持 | 向量类型（ClickZetta 特有） |
+| `TINYINT` | `NUMBER(3,0)` | 1字节整数 |
+| `SMALLINT` | `NUMBER(5,0)` | 2字节整数 |
+| 无 `NUMBER` | `NUMBER(p,s)` | ClickZetta 用 `DECIMAL(p,s)` |
+
+### ⚠️ 写入时隐式类型转换（重要差异）
+
+Snowflake 允许写入时字符串隐式转换为日期/布尔等类型，ClickZetta **不允许**：
+
+| 操作 | Snowflake | ClickZetta |
+|---|---|---|
+| INSERT 字符串→DATE | ✅ 允许 | ❌ 报错，需 `CAST` 或 `DATE '...'` |
+| INSERT 字符串→TIMESTAMP | ✅ 允许 | ❌ 报错，需 `CAST` 或 `TIMESTAMP '...'` |
+| INSERT 字符串→BOOLEAN | ✅ 允许 | ❌ 报错，需 `TRUE`/`FALSE` 或 `CAST` |
+| INSERT 字符串→INT | ✅ 允许 | ❌ 报错，需 `CAST('123' AS INT)` |
+| INSERT 字符串→JSON | ✅ 允许 | ❌ 报错，需 `PARSE_JSON(...)` 或 `CAST` |
+| UPDATE 字符串→DATE | ✅ 允许 | ❌ 报错，需 `CAST` |
+| WHERE 字符串=DATE | ✅ 允许 | ✅ 允许（查询中可隐式比较） |
+
+### 建表语法差异
+
+```sql
+-- Snowflake：CLUSTER BY
+CREATE TABLE orders (id INT, dt DATE)
+CLUSTER BY (dt);
+
+-- ClickZetta：CLUSTERED BY + PARTITIONED BY
+CREATE TABLE orders (
+    id INT,
+    dt DATE
+)
+PARTITIONED BY (dt)
+CLUSTERED BY (id) INTO 8 BUCKETS;
+
+-- ClickZetta 特有：Sort Key（内联索引）
+CREATE TABLE orders (
+    id INT,
+    amount DECIMAL,
+    INDEX amount_bf (amount) USING BLOOM_FILTER
+);
+```
+
+---
+
+## DML 差异
+
+### INSERT
+
+```sql
+-- 两者基本相同，ClickZetta 额外支持：
+INSERT OVERWRITE TABLE orders SELECT * FROM staging;  -- 覆盖写入（Hive 风格）
+INSERT INTO orders PARTITION (dt='2024-01-01') VALUES (1, 100);  -- 静态分区
+```
+
+### UPDATE
+
+```sql
+-- Snowflake
+UPDATE orders SET amount = amount * 1.1 WHERE status = 'VIP';
+
+-- ClickZetta：相同语法，额外支持 ORDER BY + LIMIT
+UPDATE orders SET amount = amount * 1.1
+WHERE status = 'VIP'
+ORDER BY created_at DESC
+LIMIT 1000;
+```
+
+### MERGE INTO
+
+```sql
+-- ClickZetta 限制：WHEN NOT MATCHED 只能有一个
+-- Snowflake 支持多个 WHEN NOT MATCHED
+
+-- ClickZetta MERGE 示例（⚠️ UPDATE 必须在 DELETE 之前）
+MERGE INTO target t
+USING source s ON t.id = s.id
+WHEN MATCHED THEN UPDATE SET t.amount = s.amount
+WHEN MATCHED AND s.action = 'DELETE' THEN DELETE
+WHEN NOT MATCHED THEN INSERT (id, amount) VALUES (s.id, s.amount);
+```
+
+---
+
+## 查询语法差异
+
+### SELECT 扩展
+
+```sql
+-- ClickZetta 特有：SELECT * EXCEPT(col)
+SELECT * EXCEPT(sensitive_col) FROM users;
+
+-- ClickZetta 特有：GROUP BY ALL（自动推断分组列）
+SELECT year, month, SUM(amount)
+FROM orders
+GROUP BY ALL;
+
+-- 两者都支持：GROUPING SETS / ROLLUP / CUBE
+SELECT region, product, SUM(sales)
+FROM orders
+GROUP BY GROUPING SETS ((region), (product), ());
+```
+
+### JSON 查询
+
+```sql
+-- Snowflake：VARIANT 类型，用 : 访问
+SELECT data:address:city FROM users;
+SELECT data[0]:name FROM users;
+
+-- ClickZetta：JSON 类型，用 [] 访问
+SELECT data['address']['city'] FROM users;
+SELECT data['phoneNumbers'][0]['number'] FROM users;
+
+-- 两者都支持 PARSE_JSON
+SELECT parse_json('{"name":"Alice"}')['name'];
+```
+
+### LATERAL VIEW（展开数组）
+
+```sql
+-- ClickZetta（Hive 风格）
+SELECT e.id, s.skill
+FROM employees e
+LATERAL VIEW EXPLODE(e.skills) s AS skill;
+
+-- Snowflake（用 FLATTEN）
+SELECT e.id, f.value::STRING AS skill
+FROM employees e,
+LATERAL FLATTEN(input => e.skills) f;
+```
+
+### QUALIFY（窗口函数过滤）
+
+```sql
+-- 两者都支持 QUALIFY
+SELECT * FROM orders
+QUALIFY ROW_NUMBER() OVER (PARTITION BY customer_id ORDER BY created_at DESC) = 1;
+```
+
+### PIVOT / UNPIVOT
+
+```sql
+-- Snowflake 原生支持 PIVOT
+SELECT * FROM sales
+PIVOT (SUM(amount) FOR month IN ('Jan', 'Feb', 'Mar'));
+
+-- ClickZetta：用 CASE WHEN 实现
+SELECT
+    product,
+    SUM(CASE WHEN month = 'Jan' THEN amount END) AS Jan,
+    SUM(CASE WHEN month = 'Feb' THEN amount END) AS Feb
+FROM sales GROUP BY product;
+```
+
+---
+
+## 流（Stream）差异
+
+```sql
+-- Snowflake Stream 元数据字段
+METADATA$ACTION        -- 'INSERT' / 'DELETE'
+METADATA$ISUPDATE      -- TRUE/FALSE
+METADATA$ROW_ID        -- 行唯一标识
+
+-- ClickZetta Table Stream 元数据字段
+__change_type          -- 'INSERT' / 'UPDATE_BEFORE' / 'UPDATE_AFTER' / 'DELETE'
+__commit_version       -- 提交版本号
+__commit_timestamp     -- 提交时间戳
+```
+
+---
+
+## 动态表（Dynamic Table）差异
+
+```sql
+-- Snowflake Dynamic Table
+CREATE DYNAMIC TABLE product_sales
+    TARGET_LAG = '1 minutes'
+    WAREHOUSE = my_warehouse
+AS SELECT ...;
+
+-- ClickZetta Dynamic Table（不支持 TARGET_LAG）
+CREATE DYNAMIC TABLE product_sales
+    REFRESH INTERVAL 1 MINUTE VCLUSTER default_ap
+AS SELECT ...;
+```
+
+---
+
+## 对象存储（Stage vs Volume）
+
+```sql
+-- Snowflake：Stage
+CREATE STAGE my_stage
+    URL = 's3://bucket/path'
+    STORAGE_INTEGRATION = my_integration;
+
+COPY INTO orders FROM @my_stage/data.csv;
+
+-- ClickZetta：Volume
+CREATE EXTERNAL VOLUME my_volume
+    LOCATION = 'oss://bucket/path'
+    USING CONNECTION my_oss_conn;
+
+COPY INTO orders FROM VOLUME my_volume USING CSV;
+```
+
+---
+
+## 函数差异
+
+### 日期函数
+
+```sql
+-- Snowflake
+DATEADD(day, 7, order_date)
+DATEDIFF(day, start_date, end_date)
+DATE_TRUNC('month', order_date)
+TO_DATE('2024-01-01')
+CURRENT_TIMESTAMP()
+
+-- ClickZetta（兼容 Hive/Spark 风格，同时也支持 Snowflake 风格）
+DATEADD(day, 7, order_date)       -- ✅ 与 Snowflake 相同语法也支持
+DATE_ADD(order_date, 7)           -- 或 Hive 风格
+DATEDIFF(end_date, start_date)    -- 注意参数顺序相反！
+DATE_TRUNC('month', order_date)   -- 相同
+TO_DATE('2024-01-01')             -- 相同
+CURRENT_TIMESTAMP()               -- 相同，也支持 NOW()
+```
+
+### 字符串函数
+
+```sql
+-- Snowflake
+CHARINDEX('sub', str)     -- 查找子串位置
+EDITDISTANCE(s1, s2)      -- 编辑距离
+SOUNDEX(str)              -- 语音相似度
+INITCAP(str)              -- 首字母大写
+
+-- ClickZetta
+INSTR(str, 'sub')         -- 查找子串位置（Hive 风格）
+LOCATE('sub', str)        -- 也支持
+LEVENSHTEIN(s1, s2)       -- 编辑距离
+INITCAP(str)              -- 相同
+```
+
+### 条件函数
+
+```sql
+-- Snowflake
+IFF(condition, true_val, false_val)
+ZEROIFNULL(expr)
+NULLIFZERO(expr)
+DECODE(expr, val1, res1, val2, res2, default)
+
+-- ClickZetta
+IF(condition, true_val, false_val)   -- 或 CASE WHEN
+COALESCE(expr, 0)                    -- 替代 ZEROIFNULL
+NULLIF(expr, 0)                      -- 替代 NULLIFZERO
+DECODE(expr, val1, res1, ...)        -- 支持（兼容）
+```
+
+### 聚合函数
+
+```sql
+-- Snowflake
+LISTAGG(col, ',') WITHIN GROUP (ORDER BY col)
+ARRAY_AGG(col)
+OBJECT_AGG(key, value)
+APPROX_COUNT_DISTINCT(col)
+
+-- ClickZetta
+GROUP_CONCAT(col ORDER BY col SEPARATOR ',')  -- 替代 LISTAGG
+ARRAY_AGG(col)                                -- 相同
+MAP_AGG(key, value)                           -- 替代 OBJECT_AGG
+APPROX_COUNT_DISTINCT(col)                    -- 相同
+```
+
+---
+
+## 权限体系差异
+
+| 概念 | ClickZetta | Snowflake |
+|---|---|---|
+| 顶层容器 | WORKSPACE | DATABASE |
+| 权限对象 | VCLUSTER / SCHEMA / TABLE / VIEW | WAREHOUSE / DATABASE / SCHEMA / TABLE |
+| 角色授予 | `GRANT ROLE r TO USER u` | `GRANT ROLE r TO USER u` |
+| 查看权限 | `SHOW GRANTS TO USER u` | `SHOW GRANTS TO USER u` |
+| 系统角色 | instance_admin / workspace_admin / workspace_dev / workspace_analyst | ACCOUNTADMIN / SYSADMIN / USERADMIN |

package/bin/skills/clickzetta-sql-syntax-guide/references/vs-spark.md

@@ -0,0 +1,229 @@
+# ClickZetta Lakehouse vs Spark SQL 差异
+
+> 来源：产品文档 + Spark Connector 文档
+
+## 数据类型映射
+
+| ClickZetta | Spark SQL | 说明 |
+|---|---|---|
+| `BOOLEAN` | `BooleanType` | 相同 |
+| `TINYINT` | `ByteType` | 1字节 |
+| `SMALLINT` | `ShortType` | 2字节 |
+| `INT` | `IntegerType` | 4字节 |
+| `BIGINT` | `LongType` | 8字节 |
+| `FLOAT` | `FloatType` | 4字节浮点 |
+| `DOUBLE` | `DoubleType` | 8字节浮点 |
+| `DECIMAL(p,s)` | `DecimalType(p,s)` | 精确数值 |
+| `STRING` / `VARCHAR` | `StringType` | 字符串 |
+| `BINARY` | `BinaryType` | 二进制 |
+| `DATE` | `DateType` | 日期 |
+| `TIMESTAMP` | `TimestampType` | 带时区时间戳 |
+| `TIMESTAMP_NTZ` | `TimestampNTZType` | 无时区时间戳 |
+| `ARRAY<T>` | `ArrayType` | 数组 |
+| `MAP<K,V>` | `MapType` | 键值对 |
+| `STRUCT<f:T>` | `StructType` | 结构体 |
+
+---
+
+## 建表语法差异
+
+### 分区
+
+```sql
+-- Spark SQL：PARTITIONED BY
+CREATE TABLE orders (id INT, amount DECIMAL, dt STRING)
+USING PARQUET
+PARTITIONED BY (dt);
+
+-- ClickZetta：相同语法，但不需要 USING 子句
+CREATE TABLE orders (id INT, amount DECIMAL, dt STRING)
+PARTITIONED BY (dt);
+```
+
+### Bucket（分桶）
+
+```sql
+-- Spark SQL
+CREATE TABLE orders (id INT, amount DECIMAL)
+CLUSTERED BY (id) INTO 8 BUCKETS;
+
+-- ClickZetta：相同语法
+CREATE TABLE orders (id INT, amount DECIMAL)
+CLUSTERED BY (id) INTO 8 BUCKETS;
+```
+
+### 表属性
+
+```sql
+-- Spark SQL：TBLPROPERTIES
+CREATE TABLE orders (id INT)
+TBLPROPERTIES ('delta.enableChangeDataFeed' = 'true');
+
+-- ClickZetta：PROPERTIES
+CREATE TABLE orders (id INT)
+PROPERTIES ('data_lifecycle' = '30');  -- 数据保留天数
+```
+
+---
+
+## 查询语法差异
+
+### LATERAL VIEW（展开数组）
+
+```sql
+-- 两者语法相同（ClickZetta 兼容 Hive/Spark 风格）
+SELECT id, skill
+FROM employees
+LATERAL VIEW EXPLODE(skills) t AS skill;
+
+-- POSEXPLODE（带位置索引）
+SELECT id, pos, skill
+FROM employees
+LATERAL VIEW POSEXPLODE(skills) t AS pos, skill;
+```
+
+### 窗口函数
+
+```sql
+-- 两者基本相同
+SELECT id, amount,
+    ROW_NUMBER() OVER (PARTITION BY customer_id ORDER BY created_at DESC) AS rn,
+    SUM(amount) OVER (PARTITION BY customer_id
+                      ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) AS running_total
+FROM orders;
+```
+
+### CTE（公用表表达式）
+
+```sql
+-- 两者语法相同
+WITH
+    monthly_sales AS (
+        SELECT DATE_TRUNC('month', order_date) AS month, SUM(amount) AS total
+        FROM orders GROUP BY 1
+    ),
+    ranked AS (
+        SELECT *, RANK() OVER (ORDER BY total DESC) AS rnk FROM monthly_sales
+    )
+SELECT * FROM ranked WHERE rnk <= 3;
+```
+
+### STRUCT / ARRAY 操作
+
+```sql
+-- Spark SQL
+SELECT address.city FROM users;                    -- STRUCT 字段访问
+SELECT skills[0] FROM employees;                   -- ARRAY 索引
+SELECT EXPLODE(skills) FROM employees;             -- 展开数组
+SELECT TRANSFORM(skills, x -> UPPER(x)) FROM emp; -- 数组变换
+
+-- ClickZetta（相同语法）
+SELECT address.city FROM users;
+SELECT skills[0] FROM employees;
+SELECT EXPLODE(skills) FROM employees;
+SELECT TRANSFORM(skills, x -> UPPER(x)) FROM emp;
+```
+
+---
+
+## 函数差异
+
+### 日期函数
+
+```sql
+-- 两者基本兼容
+DATE_ADD(date, days)
+DATE_SUB(date, days)
+DATEDIFF(end_date, start_date)   -- 注意：ClickZetta 参数顺序与 Snowflake 相反
+DATE_TRUNC('month', date)
+DATE_FORMAT(date, 'yyyy-MM-dd')
+FROM_UNIXTIME(unix_ts)
+UNIX_TIMESTAMP(date_str)
+```
+
+### 字符串函数
+
+```sql
+-- 两者基本兼容
+CONCAT(s1, s2, ...)
+CONCAT_WS(',', s1, s2, ...)
+SPLIT(str, ',')
+REGEXP_EXTRACT(str, pattern, group)
+REGEXP_REPLACE(str, pattern, replacement)
+INSTR(str, substr)
+SUBSTR(str, pos, len)
+TRIM(str) / LTRIM(str) / RTRIM(str)
+```
+
+### 聚合函数
+
+```sql
+-- 两者基本兼容
+COUNT(*) / COUNT(DISTINCT col)
+SUM / AVG / MAX / MIN
+COLLECT_LIST(col)    -- Spark：返回数组（含重复）
+COLLECT_SET(col)     -- Spark：返回去重数组
+ARRAY_AGG(col)       -- ClickZetta：等价于 COLLECT_LIST
+```
+
+---
+
+## ClickZetta 特有功能（Spark 无对应）
+
+```sql
+-- 1. VCLUSTER（计算集群管理）
+CREATE VCLUSTER my_vc VCLUSTER_TYPE = ANALYTICS VCLUSTER_SIZE = 4;
+USE VCLUSTER my_vc;
+
+-- 2. DYNAMIC TABLE（增量计算）
+CREATE DYNAMIC TABLE sales_summary
+    REFRESH INTERVAL 5 MINUTE VCLUSTER default_ap
+AS SELECT customer_id, SUM(amount) FROM orders GROUP BY 1;
+
+-- 3. TABLE STREAM（CDC 变更捕获）
+CREATE TABLE STREAM orders_stream ON TABLE orders
+    WITH PROPERTIES ('TABLE_STREAM_MODE' = 'STANDARD');
+
+-- 4. PIPE（持续导入）
+CREATE PIPE my_pipe
+    AS COPY INTO orders FROM VOLUME my_volume USING CSV;
+
+-- 5. VECTOR 类型（向量检索）
+CREATE TABLE embeddings (id INT, vec VECTOR(FLOAT, 1024));
+SELECT id, cosine_distance(vec, vector(0.1, 0.2, ...)) AS dist
+FROM embeddings ORDER BY dist LIMIT 10;
+
+-- 6. Time Travel
+SELECT * FROM orders TIMESTAMP AS OF '2024-01-01 00:00:00';
+RESTORE TABLE orders TO TIMESTAMP AS OF '2024-01-01 00:00:00';
+UNDROP TABLE orders;
+
+-- 7. SHARE（跨实例数据共享）
+CREATE SHARE my_share;
+GRANT SELECT, READ METADATA ON TABLE public.orders TO SHARE my_share;
+```
+
+---
+
+## Spark SQL 特有功能（ClickZetta 无对应或语法不同）
+
+```sql
+-- 1. Delta Lake 特有语法（ClickZetta 无对应）
+OPTIMIZE table_name ZORDER BY (col);   -- ClickZetta 有 OPTIMIZE 但无 ZORDER
+VACUUM table_name RETAIN 168 HOURS;   -- ClickZetta 自动管理，无需手动 VACUUM
+
+-- 2. SHOW TABLES EXTENDED（ClickZetta 无对应）
+SHOW TABLES EXTENDED IN schema LIKE 'orders*';
+
+-- 3. DESCRIBE HISTORY（Delta）→ ClickZetta 用 DESC HISTORY
+-- Spark/Delta:
+DESCRIBE HISTORY orders;
+-- ClickZetta:
+DESC HISTORY orders;
+
+-- 4. 生成列（语法不同）
+-- Spark:
+CREATE TABLE orders (id INT, year INT GENERATED ALWAYS AS (YEAR(order_date)));
+-- ClickZetta（相同语法，也支持）:
+CREATE TABLE orders (id INT, year INT GENERATED ALWAYS AS (YEAR(order_date)));
+```