@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/create-kafka-external.md

@@ -0,0 +1,300 @@
+# 创建DELTA和HUDI外部表
+
+## 功能
+
+外部表功能允许Lakehouse查询和分析存储在对象存储等外部存储系统中的数据。用户可以直接操作外部数据，而无需将数据导入Lakehouse内部存储，这提供了数据处理的灵活性和便利性。
+
+**外部表的其他命令**：
+
+* **删除外部表**：通过使用`DROP TABLE`语法，删除外部表。
+* **查看外部表详情**：使用`DESC TABLE`语法，您可以快速查看外部表的结构和详细信息。
+* **修改外部表**：修改外部表，`ALTER TABLE`
+* **查看外部表建表语句**：`SHOW CREATE TABLE`语句
+* **参考案例**: 具体如何操作外部表，可以参考[Delta Lake](delta-lake.md)的外部表使用指南。
+
+## 支持的范围
+
+* 支持阿里云对象存储oss、支持腾讯云对象存储cos、支持Aws对象存储S3
+
+## **语法**
+
+```SQL
+CREATE EXTERNAL TABLE [ IF NOT EXISTS ] table_name
+[(
+  column_definition [, column_definition, ...]
+)]
+[PARTITIONED BY (col_name col_type [, col_name col_type, ...] )]
+USING DELTA|HUDI
+CONNECTION connection_name
+LOCATION 'file_path'
+[COMMENT 'table_comment']
+```
+
+## **参数说明**
+
+**必选参数**:
+
+* `CREATE EXTERNAL TABLE`: 声明创建一个外部表。
+
+* `table_name`: 外部表的名称。
+
+* `column_definition`: 列定义，指定列的名称和数据类型。要求必须和delta、hudi中的类型和名称保持一致。参考Lakehouse支持的[数据类型](data-type.md)。可选，Lakehouse支持自动推断列的名称和数据类型
+
+* `USING DELTA|HUDI`: 指定文件格式目前支持Delta Lake和Hudi格式
+
+* `CONNECTION connection_name`: 连接外部数据源的认证信息，`connection_name`是Lakehouse中定义的连接对象名称。用于认证连接信息，连接对象存储。具体创建文档参考[对象存储连接(STORAGE CONNECTION)](Datalake_StorageConnection.md)
+  * 创建oss connection
+  ```
+  CREATE STORAGE CONNECTION my_conn 
+    TYPE COS
+    ACCESS_KEY = '<access_key>'
+    SECRET_KEY = '<secret_key>'
+    REGION = 'ap-shanghai'
+    APP_ID = '1310000503';
+  ```
+  * 创建cos connection
+  ```
+  CREATE STORAGE CONNECTION my_conn 
+    TYPE COS
+    ACCESS_KEY = '<access_key>'
+    SECRET_KEY = '<secret_key>'
+    REGION = 'ap-shanghai'
+    APP_ID = '1310000503';
+  ```
+  * 创建s3 connection
+  ```
+  CREATE STORAGE CONNECTION aws_bj_conn
+      TYPE S3
+      ACCESS_KEY = 'AKIAQNBSBP6EIJE33***'
+      SECRET_KEY = '7kfheDrmq***************************'
+      ENDPOINT = 's3.cn-north-1.amazonaws.com.cn'
+      REGION = 'cn-north-1';
+  ```
+
+* `LOCATION 'file_path'`: 使用 `LOCATION 'file_path'` 指令可指定待读取的数据文件路径，支持多种云存储格式。对于 Delta Lake 表，外部表将扫描该位置中的事务日志文件（如 `_delta_log/00000000000000000000.json` 或 `_delta_log/00000000000000000010.checkpoint.parquet`），以确定最新的 Parquet 文件。
+  * file\_path 是一个区分大小写的字符串，代表云存储中文件的位置或前缀（即文件夹），用于限定要加载的文件集。腾讯云对象存储 (COS): cos\://bucketname/path、阿里云对象存储 (OSS): oss//bucketname/path、AWS S3 对象存储: s3://bucketname/path
+
+  * file\_path中指定的路径必须仅包含单个 Delta Lake 或 Hudi 表的数据文件和元数据。即，每个存储位置只能对应一个目录。
+
+  * file\_path读取数据时会使用connection中的权限和认证信息。需要授权GetObject、ListObjects、PutObject、DeleteObject权限
+
+  * 每次读取时都会重新解析 Delta Lake 事务日志，确保获取最新的元数据。因此，不会缓存元数据。
+
+**可选参数**:
+
+* `IF NOT EXISTS`: 如果外部表不存在，则创建它；如果已存在，则不执行任何操作。
+* `PARTITIONED BY (col_name col_type [, col_name col_type, ...])`: 指定分区列及其数据类型，用于数据分区。如果DELTA和HUID是分区表则必须指定
+* `COMMENT 'table_comment'`: 为外部表提供描述性注释。
+
+## 用法说明
+
+* 外部表无法访问归档类型的文件，这些数据需要先还原才能检索
+* 外部表不支持TIME TRAVEL.
+* 删除外部表时只会删除外部表的定义，不会删除对象存储中的文件
+
+## **示例**
+
+1.oss上创建delta外部表
+步骤一：需要创建oss connection。具体文档参考[腾讯云存储连接创建](cos_storage_connection.md)
+步骤二：创建外部表，指定外部表的位置
+
+```SQL
+--创建connection
+CREATE STORAGE CONNECTION if not exists oss_delta
+    TYPE oss
+    ENDPOINT = 'oss-cn-beijing.aliyuncs.com'
+    access_id = 'xxx'
+    access_key = 'xxxx'
+    comments = 'delta';
+
+--创建外部表,使用上面的连接信息
+CREATE EXTERNAL TABLE IF NOT EXISTS sales_data
+USING DELTA
+CONNECTION oss_delta
+LOCATION 'oss://my-bucket/data/sales'
+COMMENT 'External table for sales data stored in OSS';
+```
+
+2.cos上创建delta外部表
+步骤一：需要创建cos connection。具体文档参考[阿里云存储连接创建](aliyun_storage_connection.md)
+步骤二：创建外部表，指定外部表的位置
+
+```SQL
+--创建connection
+CREATE STORAGE CONNECTION my_conn
+  TYPE COS
+  ACCESS_KEY = '<access_key>'
+  SECRET_KEY = '<secret_key>'
+  REGION = 'ap-shanghai'
+  APP_ID = '1310000503';
+
+--创建外部表,使用上面的连接信息
+CREATE EXTERNAL TABLE IF NOT EXISTS sales_data
+USING DELTA
+CONNECTION oss_delta
+LOCATION 'cos://cz-volume-sh-1311343935/sales';
+```
+
+3.s3上创建delta外部表
+步骤一：需要创建cos connection。具体文档参考[亚马逊云存储连接创建](aws_storage_connection.md)
+步骤二：创建外部表，指定外部表的位置
+
+```
+--创建connection
+CREATE STORAGE CONNECTION aws_bj_conn
+    TYPE S3
+    ACCESS_KEY = 'AKIAQNBSBP6EIJE33***'
+    SECRET_KEY = '7kfheDrmq***************************'
+    ENDPOINT = 's3.cn-north-1.amazonaws.com.cn'
+    REGION = 'cn-north-1';
+
+
+--创建外部表,使用上面的连接信息
+CREATE EXTERNAL TABLE IF NOT EXISTS sales_data
+(
+  order_id INT,
+  product_id STRING,
+  sale_amount DOUBLE
+)
+PARTITIONED BY (dt STRING)
+USING DELTA
+CONNECTION aws_bj_conn
+LOCATION 's3://cz-udf-user/sales'
+COMMENT 'External table for sales data stored in OSS';
+
+```
+
+
+
+# 创建Kafka外部表
+
+首先，需要创建一个存储连接，用于连接到 Kafka 服务器，连接前需要保证您的Kafka和Lakehouse网络打通，网络打通方式可以参考[私网连接](private_link.md)。本文介绍创建Kafka存储连接和Kafka外部表。
+
+**外部表的其他命令**：
+
+* **删除外部表**：通过使用`DROP TABLE`语法，删除外部表。
+* **查看外部表详情**：使用`DESC TABLE`语法，您可以快速查看外部表的结构和详细信息。
+* **修改外部表**：修改外部表，`ALTER TABLE`
+* **查看外部表建表语句**：`SHOW CREATE TABLE`语句
+* **参考案例**: 具体如何操作外部表，可以参考[Delta Lake](delta-lake.md)的外部表使用指南。
+
+## 创建Kafka存储连接
+
+### 语法
+
+```SQL
+CREATE STORAGE CONNECTION connection_name
+    TYPE kafka
+    BOOTSTRAP_SERVERS = ['server1:port1', 'server2:port2', ...]
+    SECURITY_PROTOCOL = 'PLAINTEXT';
+```
+
+### 参数说明
+
+* **connection\_name**: 连接的名称，用于后续引用。
+* **TYPE**: 连接类型，此处为 `kafka`。
+* **BOOTSTRAP\_SERVERS**: Kafka 集群的地址列表，格式为 `['host1:port1', 'host2:port2', ...]`。
+* **SECURITY\_PROTOCOL**: 安全协议，目前只支持 `PLAINTEXT`。不支持**SSL**或者**SASL\_SSL**
+
+### 示例
+
+```SQL
+CREATE STORAGE CONNECTION test_kafka_conn
+    TYPE kafka
+    BOOTSTRAP_SERVERS = ['47.99.48.62:9092']
+    SECURITY_PROTOCOL = 'PLAINTEXT';
+```
+
+## 创建Kafka外部表
+
+在创建了存储连接之后，可以定义外部表来读取 Kafka 中的数据。
+
+### 语法
+
+```SQL
+CREATE EXTERNAL TABLE IF NOT EXISTS external_table_name (
+ `topic` string,
+ `partition` int,
+ `offset` bigint,
+ `timestamp` timestamp_ltz,
+ `timestamp_type` string,
+`headers` map<string, string>,
+ `key` binary, `value` binary)
+USING kafka
+CONNECTION connection_name;
+OPTIONS (
+    'group_id' = 'consumer_group',
+    'topics' = 'topic_name',
+    'starting_offset' = 'earliest',  -- 可选，默认值 earliest
+    'ending_offset' = 'latest',      -- 可选，默认值 latest
+    'cz.kafka.seek.timeout.ms' = '2000', -- Kafka 默认值
+    'cz.kafka.request.retry.times' = '1', -- Kafka 默认值
+    'cz.kafka.request.retry.intervalMs' = '2000' -- Kafka 默认值
+) 
+```
+
+### 参数说明
+
+* **external\_table\_name**: 外部表的名称。
+* **字段说明**
+
+| 字段              | 含义                                                                              | 类型                   |
+| --------------- | ------------------------------------------------------------------------------- | -------------------- |
+| topic           | Kafka主题名称                                                                       | STRING               |
+| partition       | 数据分区ID                                                                          | INT                  |
+| offset          | Kafka分区中的偏移量                                                                    | BIGINT               |
+| timestamp       | Kafka消息时间戳                                                                      | TIMESTAMP\_LTZ       |
+| timestamp\_type | Kafka消息时间戳类型                                                                    | STRING               |
+| headers         | Kafka消息头                                                                        | MAP\<STRING, BINARY> |
+| key             | 消息键的列名，类型为 `binary`。您可以通过类型转化方式如`cast(key_column as string)`将binary类型转化为可读的字符串  | BINARY               |
+| value           | ，消息体的列名，类型为 `binary`。您可以通过类型转化方式如`cast(key_column as string)`将binary类型转化为可读的字符串 | BINARY               |
+
+* **USING kafka**: 指定使用 Kafka 作为数据源。
+* **OPTIONS**:
+  * **group\_id**: Kafka 消费者组 ID。
+  * **topics**: Kafka 主题名称。
+  * **starting\_offset**: 起始偏移量，默认值是earliest，可以是 `earliest` 或 `latest`。
+  * **ending\_offset**: 结束偏移量，默认值是`latest`，可以是 `earliest` 或 `latest`。
+  * **cz.kafka.seek.timeout.ms**: Kafka 寻址超时时间（毫秒）。
+  * **cz.kafka.request.retry.times**: Kafka 请求重试次数。
+  * **cz.kafka.request.retry.intervalMs**: Kafka 请求重试间隔时间（毫秒）。
+    * kafka_parameters: 需要传入到Kafka的参数，以kafka.开头，直接使用kafka的参数即可,可以在Kafka中找到这种选项。,格式如'kafka.security.protocol'='PLAINTEXT', 'kafka.auto.offset.reset'='latest')取值参考，[kafka文档](https://kafka.apache.org/documentation/#consumerconfigs)
+* **CONNECTION**: 指定之前创建的存储连接名称。
+
+## 使用具体案例
+
+```
+CREATE storage connection test_kafka_conn 
+TYPE kafka 
+bootstrap_servers = [
+'1.1.1.1:9092,1.1.1.1:9092,1.1.1.1:9092'
+];
+
+CREATE    EXTERNAL TABLE IF NOT EXISTS test_kafka_table (
+          `topic` string,
+          `partition` int,
+          `offset` bigint,
+          `timestamp` timestamp_ltz,
+          `timestamp_type` string,
+          `headers` map < string,string >,
+          `key` binary,
+          `value` binary
+          ) USING kafka OPTIONS (
+          'topics' = 'topic_test_kafka_pipe_loading',
+          'group_id' = 'group_test_kafka_pipe_loading'
+          ) connection test_kafka_conn;
+
+--查询数据
+SELECT    cast(key AS string),
+          cast(value AS string)
+FROM      test_kafka_table
+LIMIT     10;
+
+--转成json提取其中多 某个字段
+SELECT    cast(key AS string),
+          parse_json (cast(value AS string)) ['id'] AS id,
+          parse_json (cast(value AS string)) ['name'] AS name
+FROM      test_kafka_table
+LIMIT     10;
+```
+

package/bin/skills/lakehouse-doc/references/create-schema-from-share.md

@@ -0,0 +1,45 @@
+# CREATE SCHEMA FROM SHARE
+
+## 功能
+
+`CREATE SCHEMA FROM SHARE` 语句用于使用被分享数据。该语句以 schema 为单位提取指定 share 对象中包含的数据对象，以便在数仓中对这些数据进行查询或处理。
+
+## 语法
+
+```SQL
+CREATE SCHEMA <new_schema_name> FROM SHARE SHARE <instance_name>.<share_name>.<schema_name> ;
+```
+
+## 参数说明
+
+**new_schema_name**: 基于 share 中的数据创建在本地数仓中的 schema 名称；注意该 schema 不可与工作空间中其他 schema 重名，且该 schema 创建后为只读 schema，不可在其中创建其他数据对象。
+
+**instance_name.share_name**: 被提取的 share 名称。因不同服务实例可能共享同名的 share 对象，所以需要在 share 名称前加上 instance 名称以准确标识一个唯一的 share 对象。该信息可以通过具备实例管理员（instance\_admin）或工作空间管理员（workspace\_admin）角色的用户，执行`show shares；` 语句来获取。
+
+![](.topwrite/assets/image_1741002148136.png)
+
+**schema_name**: 指需要被提取的数据。提取数据是以 schema 为单位的，语句执行后 new_schema_name 中所包含的数据对象（table、view 等）与 share 中 schema_name 下所包含的数据对象一致。所以这里需要填入要提取的 share 中的 schema_name。
+
+该信息可以通过具备实例管理员（instance\_admin）或工作空间管理员（workspace\_admin）角色的用户，执行`desc share <instace_name>.<share_name>；` 语句来获取。一个share对象中可能包含多个schema，使用需要提取的schema的名称。
+
+![](.topwrite/assets/image_1741175128516.png)
+
+^
+^
+
+## 示例
+
+从服务实例 y237xm2x 分享来的 share_demo，提取其中 sample_schema 中的数据至当前工作空间中的 schema：data_from_share_demo 中。
+
+```SQL
+CREATE schema data_from_share_demo from share y237xm2x.share_demo.sample_schema;
+```
+
+^
+
+## 相关语句
+
+* [SHOW SHARES](show-shares.md)
+* [DESC SHARE](desc-share.md)
+
+^

package/bin/skills/lakehouse-doc/references/create-share.md

@@ -0,0 +1,46 @@
+# CREATE SHARE
+
+## 功能
+
+`CREATE SHARE` 语句用于创建一个 SHARE 对象，以便进行数据管理和使用。创建的 SHARE 对象，其类型（kind 属性）为 OUTBOUND。
+
+## 语法
+
+```SQL
+CREATE SHARE <share_name> ;
+```
+
+## 参数说明
+
+* **share_name**: 指定要创建的 SHARE 名称。SHARE 名称的规则如下：
+
+  * 支持字母、下划线和数字，不允许特殊字符和空格；
+  * 仅支持字母和下划线开头，字母自动转为小写；
+  * 长度为 1-255 字节；
+  * 在同一个 account 下，share_name 必须是唯一的。
+
+## 示例
+
+**创建 SHARE**
+
+```SQL
+CREATE SHARE share_demo;
+```
+
+## 注意事项
+
+* 在创建 SHARE 时，请确保 share_name 符合命名规则，否则将无法成功创建。
+* 创建 SHARE 后，您可以使用 `SHOW SHARES` 语句查看当前 account 下的所有 SHARE。
+
+```
+SHOW SHARES WHERE KIND = 'OUTBOUND';
+```
+
+* 您可以使用 `DROP SHARE` 语句删除不再需要的 SHARE。
+
+## 相关语句
+
+* [SHOW SHARES](show-shares.md)
+* [DROP SHARE](drop-share.md)
+
+^

package/bin/skills/lakehouse-doc/references/create-sql-function.md

@@ -0,0 +1,120 @@
+# CREATE SQL FUNCTION
+
+## 概述
+
+`CREATE FUNCTION` 语句用于在 Lakehouse 中创建 SQL 标量函数或表函数。这些函数可以接受一组参数，并返回标量值或一组行。本文将详细介绍其语法、参数、使用示例。
+
+## 语法
+
+```sql
+CREATE [OR REPLACE] FUNCTION [IF NOT EXISTS]
+    function_name ( [ function_parameter [, ...] ] )
+     [ RETURNS data_type | RETURNS TABLE(column_spec)]
+   AS|RETURN { expression | query };
+
+function_parameter
+    parameter_name data_type ;
+
+column_spec
+    column_name data_type ;
+```
+
+## 参数说明
+
+* `OR REPLACE`
+  * 如果指定此参数，将替换具有相同名称和签名（参数数量和类型）的现有函数。
+  * 不能与 `IF NOT EXISTS` 同时使用。
+* `IF NOT EXISTS`:如果指定，仅在函数不存在时才会创建。
+* `function_name`:函数的名称，可以使用schema名称限定。
+* `function_parameter`
+  * `parameter_name`：参数名称必须在函数中唯一。
+  * `data_type`：支持的任何数据类型。
+* `RETURNS data_type`
+  * 标量函数的返回数据类型。如果未提供数据类型，将从函数体派生。
+* `RETURNS TABLE`：定义返回表结构，需指定列名和数据类型
+* `AS|RETURN {expression | query}`
+  * 函数的主体。对于标量函数，可以是表达式或查询；对于表函数，只能是查询。
+
+
+## 示例
+
+* 创建和使用 SQL 标量函数
+
+```sql
+-- 创建一个函数,指定返回值
+CREATE FUNCTION public.area(x DOUBLE, y DOUBLE) 
+RETURNS DOUBLE
+RETURN x * y;
+-- 在查询中使用函数
+SELECT public.area(3, 4);
+-- 输出：12.0
+
+-- 创建一个函数,使用AS指定处理逻辑
+CREATE FUNCTION public.area2(x DOUBLE, y DOUBLE)
+RETURNS double
+AS x * y;
+SELECT public.area2(3, 4);
+
+```
+
+* 指定返回类型
+
+```
+CREATE  FUNCTION public.hello()
+RETURNS STRING
+AS  'Hello World!';
+SELECT public.hello();
+```
+
+* 在expression使用内置函数
+
+```sql
+CREATE FUNCTION public.roll_dice(num_dice INT  ,
+                          num_sides INT   )
+RETURNS INT
+COMMENT 'Roll a number of n-sided dice'
+RETURN (rand() * num_sides)::INT + 1;
+SELECT public.roll_dice(3, 10);
+```
+
+* 返回一个返回表类型
+
+```
+CREATE TABLE employee (
+    id INT,
+    name STRING,
+    deptno INT
+);
+INSERT INTO employee (id, name, deptno)
+VALUES
+    (1, 'Alice', 10),
+    (2, 'Bob', 10),
+    (3, 'Charlie', 20),
+    (4, 'David', 10),
+    (5, 'Eve', 20);
+CREATE OR REPLACE FUNCTION ga1_1.getemps(deptno INT)
+    RETURNS TABLE (name STRING)
+    RETURN SELECT name FROM employee e WHERE e.deptno = deptno;
+SELECT * FROM ga1_1.getemps(10);
+```
+
+## 注意事项
+
+* 使用函数时必须指定创建时函数所在的Schema否则会错函数找不到。
+  您可以通过设置参数来cz.sql.remote.udf.lookup.policy避免报错。该参数是。动态切换 UDF 与内置函数的解析优先级。默认行为，使用UDF时必须带SCHEMA前缀，如下案例
+  ```
+  --创建函数
+  CREATE FUNCTION public.lower()
+  RETURNS STRING
+  AS 'Hello World!';
+  --使用函数，必须写SCHMA否则会报错函数找不到
+  SELECT public.lower();
+  -- 策略1：优先调用内置函数,可以不用写SCHMA。如果和内置函数同名优先使用内置函数
+  SET cz.sql.remote.udf.lookup.policy = builtin_first;
+  SELECT lower();
+  -- 策略2：优先调用UDF（适配MC/Spark作业场景）。如果和内置函数同名优先使用udf
+  SET cz.sql.remote.udf.lookup.policy = udf_first;
+  SELECT lower();
+  ```
+
+