@clickzetta/cz-cli-darwin-x64 0.3.76 → 0.3.78

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

@@ -1,300 +0,0 @@
-# 创建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

@@ -1,45 +0,0 @@
-# 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

@@ -1,46 +0,0 @@
-# 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

@@ -1,120 +0,0 @@
-# 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();
-  ```
-
-