@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/conditional_functions/coalesce.md

@@ -0,0 +1,51 @@
+### COALESCE 函数
+
+#### 概述
+
+`COALESCE` 函数用于返回其参数列表中第一个非空（non-null）的表达式值。如果所有参数都是空值（null），则返回空值（null）。
+
+#### 语法
+
+```sql
+COALESCE(expr1 [, ...])
+```
+
+#### 参数
+
+* `exprN`: 待验证的表达式，参数数量可变，但至少需要一个。参数类型可以不同，返回值类型与第一个非空参数的类型相同。
+
+#### 返回值
+
+* 返回参数列表中第一个非空的表达式值，如果所有参数均为空值，则返回空值（null）。
+
+#### 使用示例
+
+**示例 1：基本使用**
+
+```sql
+ SELECT COALESCE(null, 'A', null, 'B', 'C') as res;
++-----+
+| res |
++-----+
+| A   |
++-----+
+```
+
+在此示例中，`COALESCE` 函数返回第一个非空参数 `'A'`。
+
+**示例 2：处理多个可能为空的字段**
+
+```sql
+SELECT COALESCE(column1, column2, column3) AS non_null_value
+FROM table_name;
+```
+
+假设 `column1`、`column2` 和 `column3` 均有可能包含空值。此查询将返回这三个字段中的第一个非空值。
+
+#### 注意事项
+
+* `COALESCE` 函数在处理参数时，一旦找到第一个非空值，就会停止检查后续参数。
+* 当所有参数均为空值时，`COALESCE` 函数返回空值（null），不会引发错误。
+* 在比较参数值时，`NULL` 被视为等于 `NULL`，但并不被视为任何其他值，包括它自己。这意味着即使有两个 `NULL` 值，`COALESCE` 也不会将它们视为相等。
+
+

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/conditional_functions/decode.md

@@ -0,0 +1,45 @@
+### DECODE 函数
+```
+DECODE(expr, search1, result1 [, search2, result2,] ... [, default])
+```
+#### 功能描述
+DECODE 函数是一个条件表达式函数，它根据给定的 expr 表达式与 searchN 条件表达式的匹配结果，返回对应的 resultN 结果表达式。当 expr 与任一 searchN 相等时，返回相应的 resultN。如果 expr 与所有 searchN 都不相等，并且提供了 default 默认结果表达式，则返回 default。如果没有提供 default，则返回 null。
+
+在进行比较时，null 和 null 被认为是相等的。
+
+#### 参数说明
+- expr：任意类型的待匹配表达式。
+- searchN：与 expr 类型相同的判断条件表达式，用于与 expr 进行比较。
+- resultN：结果表达式，其类型需与 searchN 相同。
+- default（可选）：默认结果表达式，当 expr 与所有 searchN 都不相等时返回该值，类型需与 resultN 相同。
+
+#### 使用示例
+1. 基本使用：
+   ```sql
+   SELECT DECODE(3, 6, 'Lakehouse', NULL, 'SQL', 4, 'compiler');
+   -- 结果：'compiler'
+   ```
+   在这个例子中，expr 为 3，与 search1（6）不相等，但与 search2（4）相等，因此返回 result2（'compiler'）。
+
+2. 使用默认值：
+   ```sql
+   SELECT DECODE(5, 6, 'Lakehouse', NULL, 'SQL', 4, 'compiler', 'default');
+   -- 结果：'default'
+   ```
+   当 expr 为 5 时，与所有 searchN 都不相等，因此返回指定的 default 值（'default'）。
+
+3. 处理 null 值：
+   ```sql
+   SELECT DECODE(NULL, NULL, 'Lakehouse', 6, 'SQL', NULL, 'default');
+   -- 结果：'Lakehouse'
+   ```
+   在这个例子中，expr 为 null，与 search1（null）相等，因此返回 result1（'Lakehouse'）。
+
+4. 结合其他函数使用：
+   ```sql
+   SELECT DECODE(SUBSTR('Hello World', 1, 1), 'H', 'Yes', 'W', 'No', 'default');
+   -- 结果：'Yes'
+   ```
+   在这个例子中，我们使用 SUBSTR 函数获取字符串 'Hello World' 的第一个字符 'H'，然后使用 DECODE 函数判断该字符是否为 'H'。因为 expr 与 search1 相等，所以返回 result1（'Yes'）。
+
+通过以上示例，您可以更好地理解 DECODE 函数的用法和功能。请根据您的实际需求调整参数和表达式。

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/conditional_functions/if.md

@@ -0,0 +1,56 @@
+### IF 函数
+
+#### 功能描述
+
+IF 函数是一个条件判断函数，根据提供的条件表达式（cond）来判断返回 expr1 或 expr2。当条件表达式的结果为 true 时，IF 函数返回 expr1 的值；当条件表达式的结果为 false 时，返回 expr2 的值。
+
+#### 参数说明
+
+* cond（条件表达式）：一个返回布尔值（true 或 false）的表达式。
+* expr1（表达式1）：当 cond 为 true 时，IF 函数返回该表达式的值。
+* expr2（表达式2）：当 cond 为 false 时，IF 函数返回该表达式的值。
+
+#### 返回结果
+
+IF 函数的返回类型与 expr1 和 expr2 的类型相同。
+
+#### 使用示例
+
+1. 示例 1：比较数值并返回结果
+
+```sql
+SELECT IF(a > 10, '大于10', '小于等于10') AS result FROM VALUES(5), (15), (10) AS t(a);
+
+ result    
++-----------+
+ 小于等于10 
+ 大于10     
+ 小于等于10 
+
+```
+
+2. 示例 2：判断字符串是否为空
+
+```sql
+SELECT IF(name = '', '空字符串', '非空字符串') AS result FROM VALUES('张三'), (''), ('李四') AS t(name);
+result
++-----------+
+非空字符串
+空字符串
+非空字符串
+
+```
+
+3. 示例 3：根据成绩判断等级
+
+```sql
+SELECT IF(score >= 90, '优秀', IF(score >= 60, '及格', '不及格')) AS grade FROM VALUES(85), (95), (55) AS t(score);
+grade
++-----------+
+及格
+优秀
+不及格
+
+```
+
+

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/conditional_functions/in.md

@@ -0,0 +1,33 @@
+### IN 运算符
+
+#### 功能描述
+IN 运算符用于检查某个指定的值（elem）是否在给定的表达式列表（expr1, expr2, ...）或查询结果中。如果 elem 与列表中的任意一个值或查询结果中的某个值相等，则返回 true，否则返回 false。
+
+#### 参数说明
+- `elem`：任意返回可比较类型的表达式。
+- `exprN`：与 `elem` 相同类型的表达式，可以有多个，用逗号分隔。
+- `query`：返回类型与 `elem` 类型相同的查询语句，当前版本仅支持查询返回一列结果。
+
+#### 返回类型
+返回值类型为布尔值（boolean）。
+
+#### 使用示例
+
+1. 检查数字 1 是否在给定的列表中（1, 2, 3）：
+   ```sql
+   SELECT 1 IN (1, 2, 3); -- 结果为 true
+   ```
+
+2. 检查字符串 "apple" 是否在水果列表中：
+   ```sql
+   SELECT 'apple' IN ('banana', 'apple', 'orange'); -- 结果为 true
+   ```
+
+3. 通过查询判断某个学生的成绩是否及格（假设成绩大于等于 60 分为及格）：
+   ```sql
+   SELECT student_id IN (SELECT student_id FROM scores WHERE score >= 60); -- 结果取决于学生的成绩数据
+   ```
+
+#### 注意事项
+- 请确保 `elem` 与 `exprN` 或 `query` 返回的类型相匹配，否则可能导致比较失败。
+- 当使用 IN 运算符与子查询一起使用时，请确保子查询仅返回一列结果。

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/conditional_functions/is_false.md

@@ -0,0 +1,63 @@
+### IS_FALSE 函数
+
+```
+is_false(expr)
+```
+
+#### 功能描述
+
+`IS_FALSE` 函数用于判断表达式的值是否为 `false`。该函数支持布尔值和字符串类型，能够识别多种表示 `false` 的字符串格式。
+
+#### 参数说明
+
+* `expr`：`BOOLEAN` 或 `STRING` 类型，待判断的表达式。
+
+#### 返回类型
+
+* 返回 `BOOLEAN` 类型。
+* 如果表达式值为 `false` 或表示 `false` 的字符串，返回 `true`。
+* 如果表达式值为 `true` 或表示 `true` 的字符串，返回 `false`。
+* 如果表达式值为 `NULL`，返回 `false`。
+
+#### 注意事项
+
+* `IS_FALSE` 函数识别以下字符串为 `false`：'f', 'false', '0', 'no'。
+* `IS_FALSE` 函数识别以下字符串为 `true`：'t', 'true', '1', 'yes'。
+* 与 `NOT expr` 的区别：`is_false(NULL)` 返回 `false`，而 `NOT NULL` 返回 `NULL`。
+* 字符串匹配不区分大小写。
+
+#### 使用示例
+
+1. 布尔值判断
+
+```sql
+SELECT is_false(true), is_false(false), is_false(NULL);
++----------------+-----------------+-----------------+
+| is_false(true) | is_false(false) | is_false(NULL)  |
++----------------+-----------------+-----------------+
+| false          | true            | false           |
++----------------+-----------------+-----------------+
+```
+
+2. 字符串判断（支持多种格式）
+
+```sql
+SELECT is_false('t'), is_false('f');
++---------------+---------------+
+| is_false('t') | is_false('f') |
++---------------+---------------+
+| false         | true          |
++---------------+---------------+
+```
+
+3. 在 WHERE 子句中使用
+
+```sql
+SELECT * FROM VALUES (true), (false), (NULL) AS t(flag)
+WHERE is_false(flag);
++-------+
+| flag  |
++-------+
+| false |
++-------+
+```

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/conditional_functions/is_not_null.md

@@ -0,0 +1,40 @@
+### IS_NOT_NULL 函数
+
+```sql
+is_not_null(expr)
+```
+#### 功能描述
+IS_NOT_NULL 函数用于检查给定的表达式（expr）是否不为 NULL。如果表达式非 NULL，函数返回 true，否则返回 false。该函数的作用与 SQL 语句中的 `IS NOT NULL` 条件相同。
+
+#### 参数说明
+- `expr`: 任意类型的表达式，用于检查其值是否为 NULL。
+
+#### 返回结果
+返回一个布尔值，当 expr 不为 NULL 时返回 true，否则返回 false。
+
+#### 使用示例
+
+1. 检查数字是否非 NULL
+```sql
+SELECT is_not_null(1);       -- 返回 true
+SELECT is_not_null(NULL);     -- 返回 false
+```
+
+2. 检查字符串是否非 NULL
+```sql
+SELECT is_not_null('hello');  -- 返回 true
+SELECT is_not_null('');       -- 返回 false
+```
+
+3. 检查日期是否非 NULL
+```sql
+SELECT is_not_null('2022-01-01');  -- 返回 true
+SELECT is_not_null(NULL);          -- 返回 false
+```
+
+4. 在查询中使用 IS_NOT_NULL 过滤非 NULL 记录
+```sql
+SELECT id, name, age
+FROM users
+WHERE is_not_null(age);            -- 只返回 age 字段非 null 的记录
+```

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/conditional_functions/is_null.md

@@ -0,0 +1,44 @@
+### IS_NULL 函数
+
+#### 功能描述
+IS_NULL 函数用于判断给定的表达式（expr）是否为 NULL。如果表达式为 NULL，则返回 true，否则返回 false。该函数与 SQL 中的 IS NULL 语句具有相同的效果。
+
+#### 语法
+```
+is_null(expr)
+```
+
+#### 参数说明
+- `expr`：任意类型的表达式。
+
+#### 返回结果
+返回一个布尔值，当表达式为 NULL 时返回 true，否则返回 false。
+
+#### 使用示例
+
+1. 判断一个数字是否为 NULL：
+   ```sql
+   > SELECT is_null(NULL);
+   true
+   ```
+2. 判断一个字符串是否为 NULL：
+   ```sql
+   > SELECT is_null('');
+   false
+   ```
+3. 判断一个日期是否为 NULL：
+   ```sql
+   > SELECT is_null(NULL);
+   true
+   ```
+4. 在查询中使用 IS_NULL 函数：
+   ```sql
+   > SELECT name, age, is_null(address) AS is_address_null FROM users;
+   ```
+   上述查询将返回用户表中的姓名、年龄以及地址是否为 NULL 的结果。
+
+5. 与其他条件结合使用：
+   ```sql
+   > SELECT * FROM products WHERE is_null(price);
+   ```
+   上述查询将返回价格为 NULL 的产品记录。

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/conditional_functions/is_true.md

@@ -0,0 +1,63 @@
+### IS_TRUE 函数
+
+```
+is_true(expr)
+```
+
+#### 功能描述
+
+`IS_TRUE` 函数用于判断表达式的值是否为 `true`。该函数支持布尔值和字符串类型，能够识别多种表示 `true` 的字符串格式。
+
+#### 参数说明
+
+* `expr`：`BOOLEAN` 或 `STRING` 类型，待判断的表达式。
+
+#### 返回类型
+
+* 返回 `BOOLEAN` 类型。
+* 如果表达式值为 `true` 或表示 `true` 的字符串，返回 `true`。
+* 如果表达式值为 `false` 或表示 `false` 的字符串，返回 `false`。
+* 如果表达式值为 `NULL`，返回 `false`。
+
+#### 注意事项
+
+* `IS_TRUE` 函数识别以下字符串为 `true`：'t', 'true', '1', 'yes'。
+* `IS_TRUE` 函数识别以下字符串为 `false`：'f', 'false', '0', 'no'。
+* 与直接使用 `expr` 的区别：`is_true(NULL)` 返回 `false`，而 `NULL` 在布尔上下文中会被特殊处理。
+* 字符串匹配不区分大小写。
+
+#### 使用示例
+
+1. 布尔值判断
+
+```sql
+SELECT is_true(true), is_true(false), is_true(NULL);
++---------------+----------------+----------------+
+| is_true(true) | is_true(false) | is_true(NULL)  |
++---------------+----------------+----------------+
+| true          | false          | false          |
++---------------+----------------+----------------+
+```
+
+2. 字符串判断（支持多种格式）
+
+```sql
+SELECT is_true('t'), is_true('f');
++--------------+--------------+
+| is_true('t') | is_true('f') |
++--------------+--------------+
+| true         | false        |
++--------------+--------------+
+```
+
+3. 在 WHERE 子句中使用
+
+```sql
+SELECT * FROM VALUES (true), (false), (NULL) AS t(flag)
+WHERE is_true(flag);
++------+
+| flag |
++------+
+| true |
++------+
+```

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/conditional_functions/multiif.md

@@ -0,0 +1,54 @@
+#### 简介
+
+`multiIf` 函数是一种条件逻辑函数，它允许您在查询中更紧凑地编写类似 `CASE` 语句的逻辑。该函数按照指定的顺序评估多个条件，并返回第一个为真的条件对应的值。如果所有条件都不满足，则返回最后一个 `else` 表达式的值。
+
+#### 语法
+
+```Plain
+multiIf(cond_1, then_1, cond_2, then_2, ..., else)
+```
+
+#### 参数
+
+* `cond_N`：要评估的第 N 个条件。
+* `then_N`：当第 N 个条件为真时返回的值。
+* `else`：如果所有条件都不满足时返回的值。
+
+#### 返回结果
+
+* 返回任何一个 `then_N` 表达式的值，如果所有条件都不满足，则返回 `else` 表达式的值。
+
+#### 使用示例
+
+```SQL
+
+SELECT    name,
+          score,
+          multiIf (
+          score >= 90,
+          'A',
+          score >= 80,
+          'B',
+          score >= 70,
+          'C',
+          score >= 60,
+          'D'        
+          ) AS grade
+FROM     
+VALUES    ('Alice', 92),('Bob', 85),('Charlie', 77),('David', 63),('Eve', 58) students (name, score);
++---------+-------+-------+
+|  name   | score | grade |
++---------+-------+-------+
+| Alice   | 92    | A     |
+| Bob     | 85    | B     |
+| Charlie | 77    | C     |
+| David   | 63    | D     |
+| Eve     | 58    |       |
++---------+-------+-------+
+```
+
+#### 注意事项
+
+* 如果 `multiIf` 函数中不包含 `else` 部分，当所有条件都不满足时，函数将返回 `NULL`。
+
+

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/conditional_functions/nvl.md

@@ -0,0 +1,39 @@
+### NVL 函数
+
+```
+nvl(expr1, expr2)
+```
+
+#### 功能描述
+NVL 函数用于处理 SQL 查询中的 NULL 值。当 expr1 的值为 NULL 时，NVL 函数返回 expr2 的值，否则返回 expr1 的值。这个函数可以确保返回的结果不包含 NULL 值，便于后续的数据处理和分析。
+
+#### 参数说明
+- expr1：任意类型的表达式，当其值为 NULL 时，将使用 expr2 的值作为替代。
+- expr2：与 expr1 类型相同的表达式，当 expr1 为 NULL 时，作为替代值返回。
+
+#### 返回结果
+返回结果的类型与 expr1 和 expr2 的类型相同。
+
+#### 使用示例
+
+1. 查询员工工资，如果某员工工资为 NULL，则显示为 "未知"：
+```sql
+SELECT name, nvl(salary, '未知') AS salary FROM employees;
+```
+
+2. 计算订单总金额，如果某个订单的金额为 NULL，则将其金额视为 0：
+```sql
+SELECT order_id, nvl(amount, 0) AS total_amount FROM orders;
+```
+
+3. 比较两个数值型字段，如果其中一个字段为 NULL，则返回另一个字段的值：
+```sql
+SELECT product_id, nvl(column1, column2) AS result FROM products;
+```
+
+4. 根据学生考试成绩判断是否及格，如果成绩为 NULL，则将其视为及格：
+```sql
+SELECT student_id, nvl(score, 60) AS adjusted_score FROM student_scores;
+```
+
+通过以上示例，您可以看到 NVL 函数在处理 SQL 查询中的 NULL 值时非常有用。它可以帮助您在数据分析和报表生成中避免因 NULL 值而产生的问题。

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/conditional_functions/raise_error.md

@@ -0,0 +1,52 @@
+### RAISE_ERROR 函数
+
+```
+raise_error(message)
+```
+
+#### 功能描述
+
+`RAISE_ERROR` 函数用于在查询执行过程中抛出一个运行时错误并中止查询。该函数接受一个错误消息字符串作为参数，当函数被执行时会抛出异常并显示指定的错误消息。通常与 `IF` 函数结合使用，用于在满足特定条件时终止查询执行。
+
+#### 参数说明
+
+* `message`：`STRING` 类型，错误消息内容。如果参数为 `NULL`，则显示 "null message"。
+
+#### 返回类型
+
+* 该函数不返回正常值。
+* 执行时会抛出异常并中止查询。
+* 错误消息中包含传入的 `message` 参数。
+
+#### 注意事项
+
+* 该函数会中止查询执行，应谨慎使用。
+* 在生产环境中使用时应确保只在必要的验证场景下触发。
+* 错误消息应清晰明确，便于问题排查。
+* `NULL` 参数会显示 "null message"，应避免传入 `NULL`。
+
+#### 使用示例
+
+1. 与 IF 结合使用：条件错误检查
+
+```sql
+SELECT IF(COUNT(*) > 0, raise_error('error_result'), 6666)
+FROM (SELECT 1 WHERE 1 = 0);
++---------------------------------------------------------+
+| IF(COUNT(*) > 0, raise_error('error_result'), 6666)     |
++---------------------------------------------------------+
+| 6666                                                    |
++---------------------------------------------------------+
+```
+
+2. 在 CASE WHEN 中使用
+
+```sql
+SELECT
+  CASE
+    WHEN status = 'active' THEN 'Active'
+    WHEN status = 'inactive' THEN 'Inactive'
+    ELSE raise_error('Unknown status: ' || status)
+  END as status_label
+FROM user_status;
+```

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/datetime_functions/add_days.md

@@ -0,0 +1,65 @@
+### ADD\_DAYS 函数
+
+#### 功能描述
+
+`ADD_DAYS` 函数用于在给定的日期 `startDate` 上增加 `numDays` 天，返回一个新的日期。如果计算结果超出了系统所支持的日期范围，则返回 `null`。
+
+#### 函数语法
+
+```
+add_days(startDate, numDays)
+```
+
+#### 参数说明
+
+* `startDate`: 日期类型，表示开始日期。
+* `numDays`: 整数类型，表示要增加的天数。
+
+#### 返回结果
+
+返回一个新的日期，日期类型。
+
+#### 使用示例
+
+1. 增加天数示例：
+   ```sql
+   SELECT add_days('2020-05-31', 10);
+   +----------------------------+
+   | add_days('2020-05-31', 10) |
+   +----------------------------+
+   | 2020-06-10                 |
+   +----------------------------+
+   ```
+2. 减少天数示例：
+   ```sql
+   SELECT add_days('2020-05-31', -3);
+   +----------------------------+
+   | add_days('2020-05-31', -3) |
+   +----------------------------+
+   | 2020-05-28                 |
+   +----------------------------+
+   ```
+3. 跨年日期计算示例：
+   ```sql
+   SELECT add_days('2020-12-31', 365);
+   +-----------------------------+
+   | add_days('2020-12-31', 365) |
+   +-----------------------------+
+   | 2021-12-31                  |
+   +-----------------------------+
+   ```
+4. 超出日期范围示例：
+   ```sql
+   SELECT add_days('0001-01-01', 100000);
+   +--------------------------------+
+   | add_days('0001-01-01', 100000) |
+   +--------------------------------+
+   | 0274-10-17                     |
+   +--------------------------------+
+   ```
+
+#### 注意事项
+
+* 确保 `startDate` 参数为有效的日期格式，否则会导致函数返回 `null`。
+* 当增加的天数导致结果超出系统支持的日期范围时，函数会返回 `null`。
+

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/datetime_functions/add_months.md

@@ -0,0 +1,38 @@
+### ADD_MONTHS 函数
+```sql
+ADD_MONTHS(startDate DATE, numMonths INT)
+```
+#### 功能描述
+`ADD_MONTHS` 函数用于在给定的日期 `startDate` 上增加指定数量的月份 `numMonths`。执行结果将返回一个新的日期。如果增加月份后得到的日期超出了目标月份的天数范围，函数会自动将日期调整为该月份的最后一天。若计算结果超出了系统所支持的日期范围，则会返回 `NULL`。
+
+#### 参数说明
+- `startDate`: 日期类型，表示要进行月份增加计算的起始日期。
+- `numMonths`: 整数类型，表示要增加的月份数量。可以为正数（表示未来日期），也可以为负数（表示过去日期）。
+
+#### 返回结果
+返回一个日期类型，代表经过月份增加后的日期。
+
+#### 使用示例
+1. 增加月份示例：
+```sql
+SELECT ADD_MONTHS('2020-05-31', 3);
+-- 结果为：2020-08-31
+```
+2. 减少月份示例：
+```sql
+SELECT ADD_MONTHS('2020-05-31', -3);
+-- 结果为：2020-02-29
+```
+3. 超出月份天数范围示例：
+```sql
+SELECT ADD_MONTHS('2020-04-30', 1);
+-- 结果为：2020-05-30
+```
+4. 超出系统日期范围示例：
+```sql
+SELECT ADD_MONTHS('9999-12-31', 1);
+-- 结果为：NULL
+```
+#### 注意事项
+- 确保 `startDate` 参数为有效的日期格式，否则会导致函数返回 `NULL`。
+- 当 `numMonths` 为较大或较小的整数时，请注意结果日期是否在系统支持的日期范围内。