@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/vector_functions/l2_distance.md

@@ -0,0 +1,53 @@
+## L2\_DISTANCE
+
+```SQL
+ L2_DISTANCE(vector1, vector2);
+```
+
+### 功能描述
+
+计算欧几里得空间中两点（向量的值即坐标）之间的距离（[欧几里得距离](https://en.wikipedia.org/wiki/Euclidean_distance)）。
+
+### 参数说明
+
+* vector1:第一个向量，支持的类型array\<decimal>、array\<double>、array\<float>
+* vector2:第一个向量，支持的类型array\<decimal>、array\<double>、array\<float>
+
+### 返回结果
+
+返回一个 double 类型的结果。
+
+### 案例
+
+* 计算array\<decimal>类型的两个向量之间的距离
+
+```SQL
+SELECT L2_distance(array(1bd, 2bd), array(2bd, 3bd)) as l2dis;
++--------------------+
+|       l2dis        |
++--------------------+
+| 1.4142135623730951 |
++--------------------+
+```
+
+* 计算array\<double>类型的两个向量之间的距离
+
+```SQL
+SELECT L2_distance(array(1d, 2d), array(2d, 3d)) as l2dis;
++--------------------+
+|       l2dis        |
++--------------------+
+| 1.4142135623730951 |
++--------------------+
+```
+
+* 计算array\<float>类型的两个向量之间的距离
+
+```SQL
+SELECT L2_distance(array(1f, 2f), array(2f, 3f)) as l2dis;
++--------------------+
+|       l2dis        |
++--------------------+
+| 1.4142135623730951 |
++--------------------+
+```

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/vector_functions/l2_norm.md

@@ -0,0 +1,52 @@
+## L2\_NORM
+
+```SQL
+ L2_NORM(vector1);
+```
+
+### 功能描述
+
+L2范数（L2 Norm），也称为欧几里得范数（Euclidean Norm），是一个向量的属性，表示向量各元素平方和的平方根。L2范数提供了一种衡量向量大小的方法，并且在机器学习和数据分析中非常重要。它常用于正则化（regularization）过程中，以防止模型过拟合，通过惩罚大的权重值来促进模型的泛化能力。
+
+### 参数说明
+
+* vector1:第一个向量，支持的类型array\<decimal>、array\<double>、array\<float>
+
+### 返回结果
+
+返回一个 double 类型的结果。
+
+### 案例
+
+* 计算array\<decimal>类型的向量绝对值的总和。
+
+```SQL
+ SELECT l2_norm(array(1bd, 2bd)) as l2norm;
++------------------+
+|      l2norm      |
++------------------+
+| 2.23606797749979 |
++------------------+
+```
+
+* 计算array\<double>类型的向量绝对值的总和。
+
+```SQL
+ SELECT l2_norm(array(1d, 2d)) as l2norm;
++------------------+
+|      l2norm      |
++------------------+
+| 2.23606797749979 |
++------------------+
+```
+
+* 计算array\<float>类型的向量绝对值的总和。
+
+```SQL
+ SELECT l2_norm(array(1f, 2f)) as l2norm;
++------------------+
+|      l2norm      |
++------------------+
+| 2.23606797749979 |
++------------------+
+```

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/vector_functions/l2_normalize.md

@@ -0,0 +1,54 @@
+## L2\_NORMALIZE
+
+```SQL
+ L2_DISTANCE(vector1);
+```
+
+### 功能描述
+
+它通常用于数据预处理和机器学习模型中，以确保向量在进行比较或计算时具有统一的标准。L2归一化通过除以其L2范数（即向量元素平方和的平方根）来调整向量的长度，使得归一化后的向量的L2范数为。
+
+### 参数说明
+
+* vector1:第一个向量，支持的类型array\<decimal>、array\<double>、array\<float>
+
+### 返回结果
+
+返回一个array\<double>类型的结果
+
+### 案例
+
+* 计算array\<decimal>类型进行归一化
+
+```SQL
+ SELECT l2_normalize(array(3bd, 4bd));
+
+
++---------------------------------+
+| l2_normalize(`array`(3BD, 4BD)) |
++---------------------------------+
+| [0.6,0.8]                       |
++---------------------------------+
+```
+
+* 计算array\<double>类型进行归一化
+
+```SQL
+ SELECT l2_normalize(array(3d, 4d));
++-------------------------------+
+| l2_normalize(`array`(3d, 4d)) |
++-------------------------------+
+| [0.6,0.8]                     |
++-------------------------------+
+```
+
+* 计算array\<float>类型进行归一化
+
+```SQL
+ SELECT l2_normalize(array(3f, 4f));
++-------------------------------+
+| l2_normalize(`array`(3f, 4f)) |
++-------------------------------+
+| [0.6,0.8]                     |
++-------------------------------+
+```

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/vector_functions/print_vector_bits.md

@@ -0,0 +1,56 @@
+# PRINT\_VECTOR\_BITS
+
+sql
+
+```sql
+PRINT_VECTOR_BITS(vector);
+```
+
+## 功能描述
+
+将二值化的向量转换成可读的字符串表示，显示向量中每个字节的二进制位模式。这个函数主要用于调试和可视化二值化向量的内容，帮助理解BINARY\_QUANTIZE函数的输出结果。
+
+## 参数说明
+
+* `vector`: 二值化向量，类型为 `vector`\<tinyint>
+
+## 返回结果
+
+返回一个string类型的结果，以二进制位字符串的形式显示向量内容。
+
+## 案例
+
+* 显示二值化向量的位表示
+
+```sql
+SELECT PRINT_VECTOR_BITS(VECTOR(101y)) as bit_string;
++------------+
+| bit_string |
++------------+
+| 01100101   |
++------------+
+```
+
+* 显示多字节二值化向量的位表示
+
+```sql
+SELECT PRINT_VECTOR_BITS(VECTOR(15y, 24y)) as bit_string;
++------------------+
+|    bit_string    |
++------------------+
+| 0000111100011000 |
++------------------+
+```
+
+* 结合BINARY\_QUANTIZE使用
+
+```sql
+SELECT PRINT_VECTOR_BITS(BINARY_QUANTIZE(VECTOR(1.0f, -1.0f, 1.0f, -1.0f, 1.0f, -1.0f, 1.0f, -1.0f))) as bit_pattern;
++-------------+
+| bit_pattern |
++-------------+
+| 10101010    |
++-------------+
+```
+
+

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/vector_functions/vector.md

@@ -0,0 +1,70 @@
+###  VECTOR
+``` sql
+vector(value1, value2, ...)
+```
+
+#### 功能
+创建一个向量类型的值。向量是一种特殊的数组类型，专门用于向量计算和相似度搜索。
+
+#### 参数
+* value1, value2, ...: 数值类型的值，可以是 tinyint, smallint, int, bigint, float, double 或 decimal
+
+#### 返回结果
+* vector 类型，返回包含所有参数值的向量
+* 向量的元素类型根据输入参数自动推断
+* 向量的维度等于参数个数
+
+#### 举例
+```sql
+> SELECT vector(1, 2, 3);
+[1,2,3]
+
+> SELECT typeof(vector(1Y, 2Y, 3Y));
+vector(tinyint,3)
+
+> SELECT typeof(vector(1, 2, 3));
+vector(int,3)
+
+> SELECT typeof(vector(1.0F, 2.0F, 3.0F));
+vector(float,3)
+
+> SELECT typeof(vector(1.0, 2.0, 3.0));
+vector(float,3)
+
+> SELECT size(vector(1, 2, 3));
+3
+```
+
+#### 举例
+```sql
+-- 创建不同类型的向量
+> SELECT vector(1Y, 2Y, 3Y);
+[1,2,3]
+
+> SELECT vector(1.0, 2.0, 3.0, 4.0);
+[1,2,3,4]
+
+-- 向量可以参与比较
+> SELECT vector(1, 2, 3) == vector(1, 2, 3);
+true
+
+> SELECT vector(1, 2, 3) == vector(2, 3, 4);
+false
+
+-- 向量可以作为数组使用
+> SELECT array_distinct(vector(1, 2, 1));
+[1,2]
+
+-- 向量可以排序
+> SELECT v FROM VALUES (vector(2, 3, 4)), (vector(1, 2, 3)) AS t(v) ORDER BY v;
+[1,2,3]
+[2,3,4]
+```
+
+#### 说明
+* vector 类型是 array 类型的特殊形式，专门优化用于向量计算
+* 支持的元素类型：tinyint (i8), smallint (i16), int (i32), bigint (i64), float, double
+* 向量可以与 array 类型互相转换和混合使用
+* 向量支持相等比较、排序等基本操作
+* 向量常用于向量相似度搜索、机器学习和推荐系统
+* 可以使用 `size()` 函数获取向量的维度

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/vector_functions/vector_add_scalar.md

@@ -0,0 +1,57 @@
+# VECTOR\_ADD\_SCALAR
+
+sql
+
+```sql
+VECTOR_ADD_SCALAR(vec, scalar);
+```
+
+## 功能描述
+
+对向量中的每个元素都加上指定的标量值。这是一个向量与标量的广播加法运算，将标量值添加到向量的每个分量上。
+
+## 参数说明
+
+* `vec`: 输入向量，支持的类型包括 `vector\<float>`、`vector\<double>` 等数值向量类型。
+* `scalar`: 要加到每个元素上的标量值，其类型必须为 `integer`。
+
+## 返回结果
+
+返回一个与输入向量相同类型的向量，其中每个元素都是原向量对应元素加上标量值的结果。
+
+## 示例
+
+* 对浮点向量的每个元素加上整数标量值
+
+```sql
+SELECT VECTOR_ADD_SCALAR(VECTOR(1.0f, 2.0f, 3.0f), 5) as result_vec;
++------------+
+| result_vec |
++------------+
+| [6,7,8]    |
++------------+
+```
+
+* 对向量的每个元素加上负整数标量
+
+```sql
+SELECT VECTOR_ADD_SCALAR(VECTOR(10.0f, 20.0f, 30.0f), -5) as result_vec;
++------------+
+| result_vec |
++------------+
+| [5,15,25]  |
++------------+
+```
+
+* 向量元素加上零（返回原向量）
+
+```sql
+SELECT VECTOR_ADD_SCALAR(VECTOR(1.5f, 2.5f, 3.5f), 0) as result_vec;
++---------------+
+|  result_vec   |
++---------------+
+| [1.5,2.5,3.5] |
++---------------+
+```
+
+

package/bin/skills/lakehouse-doc/references/sql_functions/table_functions/explode.md

@@ -0,0 +1,71 @@
+### EXPLODE 函数
+
+#### 功能描述
+
+`EXPLODE` 函数用于将数组或映射类型的表达式展开成多行。对于数组类型的输入，元素会被逐个展开成独立的行；对于映射类型的输入，键和值会被分别展开成多行。该函数可以直接使用，也可以与 `LATERAL VIEW` 搭配使用，以实现更复杂的数据处理。
+
+#### 参数说明
+
+* `expr`：输入的数组（`array<T>`）或映射（`map<K, V>`）表达式。
+
+#### 返回结果
+
+* 对于数组类型的输入，返回的结果中每个元素的类型为 `T`。
+* 对于映射类型的输入，返回的结果中包含两个列，分别表示键（`key`）和值（`value`），它们的类型分别为 `K` 和 `V`。
+
+#### 使用示例
+
+1. 将数组类型的表达式展开成多行：
+
+```sql
+SELECT explode(array(1, 2, 3));
++-----+
+| col |
++-----+
+| 1   |
+| 2   |
+| 3   |
++-----+
+```
+
+2. 将映射类型的表达式展开成多行：
+
+```sql
+SELECT explode(map("a", 1, "b", 2, "c", 3));
++-----+-------+
+| key | value |
++-----+-------+
+| a   | 1     |
+| b   | 2     |
+| c   | 3     |
++-----+-------+
+```
+
+3. 结合 LATERAL VIEW 使用，将数组类型的表达式展开成多行，并与原始数据关联：
+
+```sql
+SELECT vt.word, lv.ex
+FROM VALUES ('hello') AS vt(word) LATERAL VIEW explode(array(5, 6)) lv AS ex;
++-------+----+
+| word  | ex |
++-------+----+
+| hello | 5  |
+| hello | 6  |
++-------+----+
+```
+
+4. 结合 LATERAL VIEW 使用，将映射类型的表达式展开成多行，并与原始数据关联：
+
+```sql
+SELECT vt.word, lv.key, lv.value
+FROM VALUES ('hello') AS vt(word) LATERAL VIEW explode(map("a", 1, "b", 2, "c", 3)) lv AS key, value;
++-------+-----+-------+
+| word  | key | value |
++-------+-----+-------+
+| hello | a   | 1     |
+| hello | b   | 2     |
+| hello | c   | 3     |
++-------+-----+-------+
+```
+
+通过以上示例，您可以看到 `EXPLODE` 函数在处理数组和映射类型数据时的灵活性和实用性。在实际应用中，您可以根据需要对输入数据进行展开操作，以便进行更深入的数据分析和处理。

package/bin/skills/lakehouse-doc/references/sql_functions/table_functions/inline.md

@@ -0,0 +1,48 @@
+### 函数：INLINE
+
+```sql
+INLINE(expr)
+```
+
+#### 功能描述
+
+`INLINE` 函数用于将数组中的结构体元素展开成多行数据。输入参数 `expr` 为 `array<struct<T1, T2, ... Tn>>` 类型,展开后的每一列对应结构体元素中的一个字段。如果未指定列名,展开后的列名将与结构体字段名相同。`INLINE` 函数可以直接使用,也可以与 `LATERAL VIEW` 搭配使用以实现更复杂的数据处理。
+
+#### 参数说明
+
+* `expr` : 输入的数组表达式,类型为 `array<struct<T1, T2, ... Tn>>`
+
+#### 返回结果
+
+* 返回类型：根据输入参数 `expr` 进行类型推导,得到 `(T1, T2, ... Tn)` 类型的数据。
+
+#### 使用示例
+
+示例 1：简单的 INLINE 展开
+
+```sql
+SELECT INLINE(array(struct(1, 'x'), struct(2, 'y')));
++------+------+
+| col1 | col2 |
++------+------+
+| 1    | x    |
+| 2    | y    |
++------+------+
+```
+
+示例 2：与 LATERAL VIEW 搭配使用
+
+```sql
+SELECT word, s1, s2 FROM VALUES ('hello') AS vt(word) LATERAL VIEW INLINE(array(struct('a', 0), struct('b', 1))) lv AS s1, s2;
++-------+----+----+
+| word  | s1 | s2 |
++-------+----+----+
+| hello | a  | 0  |
+| hello | b  | 1  |
++-------+----+----+
+```
+
+#### 注意事项
+
+* 使用 `INLINE` 函数时,请确保输入的数组元素类型为结构体类型。
+* 在与 `LATERAL VIEW` 搭配使用时,注意为展开后的数据指定别名,以便后续操作使用。

package/bin/skills/lakehouse-doc/references/sql_functions/table_functions/json_tuple.md

@@ -0,0 +1,44 @@
+### JSON_TUPLE 函数
+
+#### 功能描述
+
+`JSON_TUPLE` 函数用于解析 `JSON` 字符串中的键值对,并将指定的键对应的值提取出来。该函数接受一个 `JSON` 字符串作为输入，并根据提供的键列表（`c1`、`c2`、...、`cN`）提取相应的值。如果 `JSON` 字符串解析失败，函数将返回全列为 `NULL` 的结果；如果某个键不存在于 `JSON` 对象中，对应的列将被填充为 `NULL`。需要注意的是，`JSON_TUPLE` 函数只能解析 `JSON` 对象的顶层键。
+
+该函数可以直接使用，或者与 `LATERAL VIEW` 子句结合使用，以便在更复杂的查询中提取 `JSON` 数据。
+
+#### 参数说明
+
+* `str` (string): 需要解析的 `JSON` 字符串，该字符串应为一个 `JSON` 对象。
+* `c1`, `c2`, ... `cN` (string): 需要提取的 `JSON` 对象中的键。
+
+#### 返回类型
+
+* 返回一个包含提取值的字符串数组，数量与提供的键列表长度相同。
+
+#### 使用示例
+
+**示例 1：基本用法**
+
+```sql
+SELECT json_tuple('{"x" : "1", "y" : 2}', 'x', 'z');
++------+------+
+| col0 | col1 |
++------+------+
+| 1    |      |
++------+------+
+```
+
+上述查询尝试提取键 `x` 和 `z` 的值。由于 `z` 键不存在，返回结果中 `z` 对应的值为空。
+
+**示例 2：与 LATERAL VIEW 结合使用**
+
+```sql
+SELECT a, b, c FROM VALUES ('{"a" : 1.0, "b" : 2}') AS t(word) LATERAL VIEW json_tuple(word, 'a', 'b', 'c') lv AS a, b, c;
++-----+---+---+
+|  a  | b | c |
++-----+---+---+
+| 1.0 | 2 |   |
++-----+---+---+
+```
+
+在这个例子中，我们首先创建了一个包含 `JSON` 字符串的表，然后使用 `LATERAL VIEW` 和 `json_tuple` 函数提取 `a`、`b` 和 `c` 键的值。由于 `c` 键不存在，其对应的值为空。

package/bin/skills/lakehouse-doc/references/sql_functions/table_functions/load_history.md

@@ -0,0 +1,17 @@
+#### load\_history函数
+
+**功能描述**： load\_history函数用于查看表的COPY作业导入文件历史，保留期为7天。同时，Pipe在执行时会根据load\_history避免重复导入已有的文件，确保数据的唯一性。
+
+**函数语法**：
+
+```SQL
+load_history('schema_name.table_name')
+```
+
+* **schema\_name.table\_name**：指定要查看导入历史的表名。
+
+**使用案例**：
+
+```SQL
+SELECT * FROM load_history('myschema.mytable');
+```

package/bin/skills/lakehouse-doc/references/sql_functions/table_functions/posexplode.md

@@ -0,0 +1,89 @@
+### POSEXPLODE 函数
+
+#### 概述
+
+`posexplode` 函数用于将输入的数组或映射类型的表达式 `expr` 展开成多行数据,并为每行添加位置列,以指明元素在原始数组或映射中的相对位置。该函数可以直接使用,也可以与 `LATERAL VIEW` 配合使用,以便在更复杂的查询中实现数据展开。
+
+#### 功能
+
+1. 对于数组类型的输入,`posexplode` 会将数组中的每个元素展开成一行,并添加名为 `pos` 和 `col` 的列,分别表示元素的位置和值。
+2. 对于映射类型的输入,`posexplode` 会将映射中的每个键值对展开成一行,并添加名为 `pos`、`key` 和 `value` 的列,分别表示元素的位置、键和值。
+
+#### 参数
+
+* `expr`: 输入的数组 `array<T>` 或映射 `map<K, V>` 类型。
+
+#### 返回结果
+
+* 对于数组类型的输入,返回类型为 `int, T`。
+* 对于映射类型的输入,返回类型为 `int, K, V`。
+
+#### 使用示例
+
+1. 展开数组类型的输入：
+
+   ```sql
+   SELECT posexplode(array(1, 2, 3));
+   +-----+-----+
+   | pos | col |
+   +-----+-----+
+   | 0   | 1   |
+   | 1   | 2   |
+   | 2   | 3   |
+   +-----+-----+
+   ```
+
+2. 展开映射类型的输入：
+
+   ```sql
+   SELECT posexplode(map("a", 1, "b", 2, "c", 3));
+   +-----+-----+-------+
+   | pos | key | value |
+   +-----+-----+-------+
+   | 0   | a   | 1     |
+   | 1   | b   | 2     |
+   | 2   | c   | 3     |
+   +-----+-----+-------+
+   ```
+
+3. 结合 `LATERAL VIEW` 使用：
+
+   ```sql
+   SELECT word, pos, ex
+   FROM VALUES ('hello') AS vt(word)
+   LATERAL VIEW posexplode(array(5, 6)) lv AS pos, ex;
+   +-------+-----+----+
+   | word  | pos | ex |
+   +-------+-----+----+
+   | hello | 0   | 5  |
+   | hello | 1   | 6  |
+   +-------+-----+----+
+   ```
+
+4. 展开数组并筛选特定元素：
+
+   ```sql
+   SELECT pos, col
+   FROM posexplode(array(1, 2, 3, 4)) AS t(pos, col)
+   WHERE col % 2 = 0;
+   +-----+-----+
+   | pos | col |
+   +-----+-----+
+   | 1   | 2   |
+   | 3   | 4   |
+   +-----+-----+
+   ```
+
+5. 展开映射并计算值的总和：
+
+   ```sql
+   SELECT SUM(value) AS total_sum
+   FROM posexplode(map("a", 1, "b", 2, "c", 3)) AS t(pos, key, value);
+   +-----------+
+   | total_sum |
+   +-----------+
+   | 6         |
+   +-----------+
+   ```
+
+通过以上示例,您可以更好地理解 `posexplode` 函数的用法和功能。在实际应用中,您可以根据需要对数组或映射类型的数据进行展开和处理。