@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/use-java-sdk-releatime-uploaddata.md

@@ -0,0 +1,168 @@
+# 使用 Java SDK 读取 Kafka 数据并实时上传
+
+本文档详细介绍了如何利用 Java SDK 将数据实时写入 Lakehouse，适用于需要实时数据流处理的业务场景，特别适合熟悉 Java 的开发人员。本案例以 Kafka 为数据源，展示如何读取 Kafka 数据并通过 Lakehouse 的 RealtimeStream 接口进行写入。如果您对读取 Kafka 数据没有特殊要求，推荐使用 Lakehouse Studio 数据集成。Lakehouse Studio 数据集成提供了可视化监控，提高了数据管理的透明度。
+
+# 参考文档
+
+[Java SDK实时上传数据](java_reference/realtime-upload.md)
+
+## 应用场景
+
+* 适用于需要实时处理数据流的业务场景。
+* 适合熟悉Java并需要自定义逻辑处理的开发人员。
+
+## 使用限制
+
+* 实时写入的数据可以秒级查询。
+* 表结构变更时，需停止实时写入任务，并在变更后约 90 分钟重新启动。
+* table stream、materialized view 和 dynamic table 只能显示已经提交的数据。实时任务写入的数据需要等待约 1 分钟才能确认，因此 table stream 也需要等待约 1 分钟才能看到。
+
+# 使用案例
+
+本案例使用 Kafka 的 Java 客户端读取数据，并调用 Lakehouse 的 RealtimeStream 接口进行写入。
+
+## 环境准备
+
+* 拥有 Kafka 集群（本次演示使用的是本地搭建的 Kafka），并创建 Topic `lakehouse-stream`。
+
+  * ```SQL
+    bin/kafka-topics.sh --create --topic lakehouse-stream --bootstrap-server localhost:9092
+    ```
+
+* 数据格式为 JSON，使用 Kafka 命令行生产数据：
+
+  * ```SQL
+    {"id": 1, "name": "张三", "email": "zhangsan@example.com", "isActive": true}
+    --kafka生产者命令行
+    bin/kafka-console-producer.sh --topic lakehouse-stream --bootstrap-server localhost:9092
+    ```
+
+* 在 Lakehouse 上创建表
+
+  * ```SQL
+    create table realtime_stream(id int,event json);
+    ```
+
+## 使用Java代码开发
+
+### Maven依赖
+
+在项目的 `pom.xml` 文件中添加以下依赖。Lakehouse Maven 最新依赖可以在 [maven库](https://central.sonatype.com/artifact/com.clickzetta/clickzetta-java) 中找到。
+
+```SQL
+<dependency>
+    <groupId>com.clickzetta</groupId>
+    <artifactId>clickzetta-java</artifactId>
+    <version>1.3.1</version>
+</dependency>
+<!-- https://mvnrepository.com/artifact/org.apache.kafka/kafka-clients -->
+<dependency>
+    <groupId>org.apache.kafka</groupId>
+    <artifactId>kafka-clients</artifactId>
+    <version>3.2.0</version>
+</dependency>
+```
+
+### 编写Java代码
+
+1. **定义 Kafka 连接类**：创建一个 `KafkaReader` 类，配置 Kafka 消费者。
+2. **消费 Kafka 并写入 Lakehouse**：创建 `Kafka2Lakehouse` 类，实现从 Kafka 读取数据并通过 RealtimeStream 写入 Lakehouse 的逻辑。
+
+定义一个 Kafka 连接类，Kafka 的 Java 客户端配置可以参考 [Kafka官网](https://docs.confluent.io/kafka-clients/java/current/overview.html)。
+
+```SQL
+import org.apache.kafka.clients.consumer.ConsumerConfig;
+import org.apache.kafka.clients.consumer.KafkaConsumer;
+import java.util.Collections;
+import java.util.Properties;
+// 创建一个消费者类
+public class KafkaReader {
+    // 定义一个kafka消费者对象
+    private KafkaConsumer<String, String> consumer;
+    // 定义一个构造方法，初始化消费者的配置
+    public KafkaReader() {
+        // 创建一个Properties对象，用于存储消费者的配置信息
+        Properties props = new Properties();
+        // 指定连接的kafka集群的地址
+        props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
+        // 指定消费者所属的消费者组
+        props.put(ConsumerConfig.GROUP_ID_CONFIG, "test-group");
+        // 指定消费者的key和value的反序列化器
+        props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, "org.apache.kafka.common.serialization.StringDeserializer");
+        props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, "org.apache.kafka.common.serialization.StringDeserializer");
+        // 指定消费者的自动位移提交策略
+        props.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, "true");
+        // 指定消费者的自动位移提交间隔
+        props.put(ConsumerConfig.AUTO_COMMIT_INTERVAL_MS_CONFIG, "1000");
+        // 使用配置信息创建一个kafka消费者对象
+        consumer = new KafkaConsumer<>(props);
+    }
+    // 定义一个方法，用于从指定的主题中读取数据
+    public KafkaConsumer<String, String> readFromTopic(String topic) {
+        consumer.subscribe(Collections.singleton(topic));
+        return consumer;
+    }
+}
+```
+
+消费 Kafka 数据并写入到 Lakehouse 中
+
+```SQL
+
+import com.clickzetta.client.ClickZettaClient;
+import com.clickzetta.client.RealtimeStream;
+import com.clickzetta.client.RowStream;
+import com.clickzetta.platform.client.api.Options;
+import com.clickzetta.platform.client.api.Row;
+import com.clickzetta.platform.client.api.Stream;
+import org.apache.kafka.clients.consumer.ConsumerRecord;
+import org.apache.kafka.clients.consumer.ConsumerRecords;
+import org.apache.kafka.clients.consumer.KafkaConsumer;
+
+import java.text.MessageFormat;
+import java.time.Duration;
+
+public class Kafka2Lakehouse {
+    private static ClickZettaClient client;
+    private static final String password = "";
+    private static final String table = "realtime_stream";
+    private static final String workspace = "";
+    private static final String schema = "public";
+    private static final String user = "";
+    private static final String vc = "default";
+    static RealtimeStream realtimeStream;
+    static KafkaReader kafkaReader;
+    //读取Topic并写入到Lakehouse中
+    public static void main(String[] args) throws Exception {
+        initialize();
+        kafkaReader = new KafkaReader();
+        final KafkaConsumer<String, String> consumer = kafkaReader.readFromTopic("lakehouse-stream");
+        // 开始消费消息
+        while (true) {
+            int i = 1;
+            try {
+                ConsumerRecords<String, String> records = consumer.poll(Duration.ofSeconds(1));
+                for (ConsumerRecord<String, String> record : records) {
+                    Row row = realtimeStream.createRow(Stream.Operator.INSERT);
+                    i++;
+                    row.setValue("id", i);
+                    row.setValue("event", record.value());
+
+                    realtimeStream.apply(row);
+                }
+            } catch (Exception e) {
+                throw new RuntimeException(e);
+            }
+        }
+    }
+    //初始化Lakehouse客户端和realtimeStream
+    private static void initialize() throws Exception {
+        String url = MessageFormat.format("jdbc:clickzetta://demo_instance.cn-shanghai-alicloud.api.clickzetta.com/{0}?" + "schema={1}&username={2}&password={3}&vcluster={4}", workspace, schema, user, password, vc);
+        Options options = Options.builder().withMutationBufferLinesNum(10).build();
+        client = ClickZettaClient.newBuilder().url(url).build();
+        realtimeStream = client.newRealtimeStreamBuilder().operate(RowStream.RealTimeOperate.APPEND_ONLY).options(options).schema(schema).table(table).build();
+    }
+}
+```
+
+^

package/bin/skills/lakehouse-doc/references/use-java-sdk-upload-dta-local.md

@@ -0,0 +1,140 @@
+# 使用Java SDK批量上传数据
+
+本文档主要介绍如何使用 Java SDK 的 BulkloadStream 批量将数据加载到 Lakehouse 中。它适合一次性大量数据导入，支持自定义数据源，提供了数据导入的灵活性。本次案例以读取本地文件为例。如果您的数据源在对象存储或 Lakehouse Studio 数据集成支持的范围内，推荐使用 COPY 命令或数据集成功能。
+
+# 参考文档
+
+[Java SDK批量上传数据](java_reference/bulkload-upload.md)
+
+## 应用场景
+
+* 适用于需要批量上传大量数据的业务场景。
+* 适合熟悉Java并需要自定义数据导入逻辑的开发人员。
+
+## 使用限制
+
+* BulkloadStream不支持主键（pk）表的写入。
+* 不适用于时间间隔小于五分钟的频繁数据上传场景。
+
+# 使用案例
+
+本案例以读取本地 CSV 文件为例，使用的数据集是 [巴西电子商务](https://www.kaggle.com/datasets/olistbr/brazilian-ecommerce?select=olist_order_items_dataset.csv) 公共数据集中的 olist_order_items_dataset 数据。若数据源位于对象存储或 Lakehouse Studio 数据集成功能支持的范围，推荐使用 COPY 命令或数据集成功能。
+
+## 前置条件
+
+* 创建表
+  * ```SQL
+    create    table bulk_order_items (
+              order_id STRING,
+              order_item_id INT,
+              product_id STRING,
+              seller_id STRING,
+              shipping_limit_date STRING,
+              price DOUBLE,
+              freight_value DOUBLE
+              );
+    ```
+
+* 对目标表具有INSERT权限。
+
+## 使用Java代码开发
+
+### Maven依赖
+
+在项目的 `pom.xml` 文件中添加 Lakehouse 的 Maven 依赖。Lakehouse Maven 依赖的最新版本可以在 [maven库](https://central.sonatype.com/artifact/com.clickzetta/clickzetta-java) 中找到。
+
+```SQL
+<dependency>
+    <groupId>com.clickzetta</groupId>
+    <artifactId>clickzetta-java</artifactId>
+    <version>1.3.1</version>
+</dependency>
+```
+
+### 编写Java代码
+
+1.  **初始化 Lakehouse 客户端和 BulkloadStream**：创建 `BulkloadFile` 类，初始化 Lakehouse 连接和 BulkloadStream 对象。
+2.  **读取本地 CSV 文件并写入 Lakehouse**：使用 Java IO 流读取本地 CSV 文件，并将数据逐行写入 Lakehouse。
+
+```SQL
+
+import com.clickzetta.client.BulkloadStream;
+import com.clickzetta.client.ClickZettaClient;
+import com.clickzetta.client.RowStream;
+import com.clickzetta.client.StreamState;
+import com.clickzetta.platform.client.api.Row;
+
+import java.io.BufferedReader;
+import java.io.File;
+import java.io.FileReader;
+import java.text.MessageFormat;
+
+public class BulkloadFile {
+    private static ClickZettaClient client;
+    private static final String password = "";
+    private static final String table = "bulk_order_items";
+    private static final String workspace = "";
+    private static final String schema = "public";
+    private static final String vc = "default";
+    private static final String user = "";
+    static BulkloadStream bulkloadStream;
+    public static void main(String[] args) throws Exception {
+        initialize();
+        File csvFile = new File("olist_order_items_dataset.csv");
+        BufferedReader reader = new BufferedReader(new FileReader(csvFile));
+        // Skip the header row
+        reader.readLine(); // Skip the first line (header)
+        // Insert data into the database
+        String line;
+
+        while ((line = reader.readLine()) != null) {
+            String[] values = line.split(",");
+            //类型转化保持和服务端类型一致
+            String orderId = values[0];
+            int orderItemId = Integer.parseInt(values[1]); // Convert order_item_id to int
+            String productId = values[2];
+            String sellerId = values[3];
+            String shippingLimitDate = values[4];
+            double price = Double.parseDouble(values[5]);
+            double freightValue = Double.parseDouble(values[6]);
+            Row row = bulkloadStream.createRow();
+            // Set parameter values
+            row.setValue(0, orderId);
+            row.setValue(1, orderItemId);
+            row.setValue(2, productId);
+            row.setValue(3, sellerId);
+            row.setValue(4, shippingLimitDate);
+            row.setValue(5, price);
+            row.setValue(6, freightValue);
+         //必须调用该方法，否则无法将数据发送到服务端
+            bulkloadStream.apply(row);
+        }
+        // Close resources
+        reader.close();
+        bulkloadStream.close();
+        waitForBulkloadCompletion();
+        client.close();
+        System.out.println("Data inserted successfully!");
+    }
+    private static void initialize() throws Exception {
+        String url = MessageFormat.format("jdbc:clickzetta://demo_instance.cn-shanghai-alicloud.api.clickzetta.com/{0}?" +
+                        "schema={1}&username={2}&password={3}&virtualcluster={4}&",
+                workspace, schema, user, password, vc);
+        client = ClickZettaClient.newBuilder().url(url).build();
+        bulkloadStream = client.newBulkloadStreamBuilder().schema(schema).table(table)
+                .operate(RowStream.BulkLoadOperate.APPEND)
+                .build();
+    }
+    private static void waitForBulkloadCompletion() throws InterruptedException {
+        while (bulkloadStream.getState() == StreamState.RUNNING) {
+            Thread.sleep(1000);
+        }
+        if (bulkloadStream.getState() == StreamState.FAILED) {
+            throw new ArithmeticException(bulkloadStream.getErrorMessage());
+        }
+    }
+
+}
+```
+
+^

package/bin/skills/lakehouse-doc/references/use-mysql-client.md

@@ -0,0 +1,189 @@
+# 简介
+
+> 【预览发布】本功能当前处于公开预览发布阶段。
+
+| 云服务商 | 地域  | 兼容MySQL协议版本       |
+| ---- | --- | ----------------- |
+| 阿里云  | 新加坡 | MySQL5.x和MySQL8.x |
+|      | 上海  | MySQL5.x和MySQL8.x |
+| 腾讯云  | 上海  | MySQL8.x          |
+|      | 北京  | MySQL8.x          |
+|      | 广州  | MySQL8.x          |
+| 亚马逊  | 北京  | MySQL8.x          |
+|      | 新加坡 | MySQL8.x          |
+
+Lakehouse 支持 MySQL 客户端与服务端的通讯协议，因此可以使用 MySQL 驱动连接 Lakehouse。然而，Lakehouse 并未实现 MySQL 的语法和数据类型。通过 MySQL 客户端连接 Lakehouse 时，执行的 SQL 语句应使用 Lakehouse 语法，而非 MySQL 语法。例如，`mysqldump` 命令在 Lakehouse 中不可用。
+
+为了适配一些 BI 报表，Lakehouse 实现了一些 MySQL 常用函数，如 `str_to_date` 和 `date_format`。目前，Lakehouse 支持的协议如下：
+MySQL8.x版本客户端连接服务端时默认使用的是caching\_sha2\_password认证方式，有关 MySQL 认证方式的更多信息请参考[官方文档](https://dev.mysql.com/doc/refman/8.0/en/authentication-plugins.html)。连接方式如下，例如连接上海阿里云：
+
+```
+jdbc:mysql://cn-shanghai-alicloud-mysql.api.clickzetta.com/public
+--添加端口,可选
+jdbc:mysql://cn-shanghai-alicloud-mysql.api.clickzetta.com:3306/public
+--使用ssl可选
+jdbc:mysql://cn-shanghai-alicloud-mysql.api.clickzetta.com/public?useSSL=true
+```
+
+MySQL5.x版本客户端连接服务端时默认使用的是mysql\_native\_password认证方式，有关 MySQL 认证方式的更多信息请参考[官方文档](https://dev.mysql.com/doc/refman/8.0/en/authentication-plugins.html)，连接Lakehouse是无需开启SSL，连接方式如下，例如连接上海阿里云：。
+
+* 目前需要重置密码，即使是新建的账号也需要重置密码。这是因为 MySQL 5.x 版本使用的是 `mysql_native_password` 密钥，而 Lakehouse 需要保存 MySQL 的加密算法。目前，只有在修改密码时，Lakehouse 才会保存 MySQL 密钥的加密算法。您可以在修改密码时保持和之前一样，这样可以避免影响其他任务的连接。
+
+```
+jdbc:mysql://cn-shanghai-alicloud-mysql.api.clickzetta.com/public?useSSL=false
+--添加端口,可选
+jdbc:mysql://cn-shanghai-alicloud-mysql.api.clickzetta.com:3306/public?useSSL=false
+```
+
+端口：3306（可选）
+
+# 使用场景
+
+* 无法使用Lakehouse驱动场景，比如某些报表场景不支持自定义jdbc驱动或者不支持Lakehoue原生jdbc驱动。如果可以，请尽可能使用 Lakehouse 原生驱动。
+
+# 使用限制
+
+* 目前无法完全兼容MySQL函数和语法，某些报表使用的一些 MySQL 专有语法和函数在发送到 Lakehouse 时会报错（请联系 Lakehouse 支持）。
+* 数据类型限制
+  * 在使用 Lakehouse MySQL 协议时，若 SQL 语句中包含 MySQL 特有的类型（如 mediumint、numeric、bit、time、year、datetime、varbinary、text、blob、enum、set、空间数据类型），系统会报错。例如，“create table mysql\_table(col numeric)” 的建表语句，或 “select cast(xxxx as text)” 这类语句，只要 SQL 中含有上述类型，都会触发报错。为避免此问题，可使用 Lakehouse 的类型替换 MySQL 的数据类型。
+* 语法限制
+  * 不支持MySQL特有语法如MySQL dump命令、Load等命令。
+* 函数限制
+  * Lakehouse 实现了一些 MySQL 常用函数。如果您有需要请联系Lakehouse支持
+* 数据导入限制
+  * 不支持 MySQL 批量导入数据，例如 MySQL 的 LOAD 命令。
+  * 使用MySQL驱动不支持Lakehouse本地命令（[PUT](PUT.md)、[REMOVE](remove-volume.md)、[GET](GET.md)等命令），不支持使用MySQL驱动调用Lakehouse的批量上传和实时上传数据的Java SDK。
+* MySQL列出表结构时需要查询information schema，目前Lakehouse对于新建的表在information schema会存在15分钟延迟，所以新建的表无法立即看到
+
+# 连接方式
+
+## 1.设置计算集群
+
+由于 MySQL 协议中没有传入设置集群的方式，用户可以使用 SQL 命令为用户添加一个默认计算集群。这样在 MySQL 连接时就会使用该集群。需要注意的是，BI场景对分析性能往往有要求，建议为BI工具连接用户选择合适规格的分析型计算集群以提供最佳的查询性能。
+
+```sql
+ALTER USER user_name SET DEFAULT_VCLUSTER = default;
+
+-- 查看集群设置是否生效
+SHOW USERS;
+```
+
+## 2.设置用户名密码
+
+由于 MySQL 协议中没有 workspace 名称和 instance 名称，因此需要将 instance 名称和 workspace 名称拼接到用户名中。
+
+用户名格式要求如下：
+
+```
+登录的账号名称@instance_name.workspace_name
+```
+
+* **instance\_name 获取**：在 [工作空间](workspace-introduction.md)页面 中获取 JDBC 连接串。例如，在 `jdbc:clickzetta://jnsxwfyr.api.clickzetta.com/quick_start?virtualCluster=default` 中，`jnsxwfyr` 为 instance\_name。
+* **workspace\_name 获取**：工作空间的名称。
+
+示例：
+
+```
+user@jnsxwfyr.quick_start
+```
+
+## 3.设置连接地址：
+
+端口：3306
+
+| 云服务商 | 地域 | 连接地址                                               |
+| ---- | -- | -------------------------------------------------- |
+| 阿里云  | 上海 | cn-shanghai-alicloud-mysql.api.clickzetta.com      |
+| 腾讯云  | 上海 | ap-shanghai-tencentcloud-mysql.api.clickzetta.com  |
+|      | 北京 | ap-beijing-tencentcloud-mysql.api.clickzetta.com   |
+|      | 广州 | ap-guangzhou-tencentcloud-mysql.api.clickzetta.com |
+| 亚马逊  | 北京 | cn-north-1-aws-mysql.api.clickzetta.com            |
+
+## 4.其他参数：
+
+* useSSL=true：Lakehouse对于mysql 8.x版本客户端时使用caching\_sha2\_password，因此使用mysql 8.x版本驱动连接时必须设置useSSL=true。如果使用的是mysql5.x版本则useSSL=false即可
+* 数据库名称: Lakehouse的schema名称
+* 端口：3306（可选）
+
+# 一般BI报表配置参数
+
+**连接工具**
+
+建议mysql java 8.0驱动，运行SQL，但是某些报表可能初始化会发一些mysql特有的语法，如果遇到报错请联系Lakehouse技术支持。
+
+**设置vcluster**:
+需要给连接的用户指定默认vcluster，在Lakehouse中指定用户默认vcluster,这样在 MySQL 连接时就会使用该集群。需要注意的是，BI场景对分析性能往往有要求，建议为BI工具连接用户选择合适规格的分析型计算集群以提供最佳的查询性能。
+
+```SQL
+ALTER USER user_name SET DEFAULT_VCLUSTER= default_ap;
+--查看vcluster设置是否生效
+show users;
+```
+
+**驱动要求**：建议mysql8.0以上
+
+**连接地址（必须配置**）
+
+**用户名格式（必须配置**）
+
+* 格式：用户名@instance\_name.worksapace\_name，比如test\@jnsxwfyr.ql\_ws
+
+**数据库名称（必须配置**）
+
+* 格式：schema名称，如public
+
+**端口：3306。某些报表需要配置**
+
+**额外参数（必须配置**）：
+
+如果使用 8.x 驱动，某些报表可以直接在配置参数中输入下面字符串：
+
+* useSSL=true
+
+如果报表中不支持填写参数
+
+* 在报表界面，通常可以找到是否使用 SSL 的选项，需要勾选上。
+  如果使用的是 5.x 版本驱动，则不需要勾选。
+
+# 常见问题
+
+* 无法指定计算资源
+
+  * 需要给连接的用户指定默认vcluster，在Lakehouse中指定用户默认vcluster
+  * ```SQL
+    alter user UAT_TEST set DEFAULT_VCLUSTER= default;
+    --查看vcluster设置是否生效
+    show users;
+    ```
+
+# 问题排查
+
+通过lakehouse作业历史排查问题。如果mysql协议连通之后，mysql连接Lakehouse通常会发一些SQL，作业历史会记录发送的SQL，此时我们可以通过作业历史查看发送的SQL来看错误信息。通过筛选来快速定位，如下三个筛选条件
+
+* 计算集群：bi报表中指定的计算集群
+* 提交人：bi报表中连接的用户名比如是<<<test@jnsxwfyr.ql_ws>>>，则这里筛选为test
+* schema：bi报表中指定的schema名称
+* 通过点击右上角的刷新按钮，来监控 BI 报表发送的 SQL。
+
+![](.topwrite/assets/image_1722596643860.png)
+
+# 案例
+
+* 使用mysql client 连接
+
+mysql client连接Lakehouse：
+
+```
+-- 添加-A选项避免mysql连接时发送一些校验的SQL
+mysql -h cn-shanghai-alicloud-mysql.api.clickzetta.com -u user_name@instance_name.worksapace_name -D  public -p -A
+
+--使用mysql客户端连接报错信息为：ERROR 2059 (HY000): Authentication plugin 'mysql_clear_password' cannot be loaded: plugin not enabled时。可以添加参数使用以下命令来连接
+mysql -h cn-shanghai-alicloud-mysql.api.clickzetta.com -u user_name@instance_name.worksapace_name -Dpublic -p -A --enable-cleartext-plugin  --default-auth=mysql_native_password
+
+
+
+```
+
+* 使用[Power BI连接Lakehouse](PowerBI.md)
+
+^

package/bin/skills/lakehouse-doc/references/use-python-sdk-upload-data.md

@@ -0,0 +1,99 @@
+# 使用Python SDK批量上传数据
+
+本文档详细介绍了如何使用Python SDK中的BulkloadStream将数据批量加载到Lakehouse中。这种方法适合一次性大量数据的导入，支持自定义数据源，为数据导入提供了灵活性。本案例以读取本地CSV文件为例，如果数据源位于对象存储或Lakehouse Studio支持的数据集成范围内，推荐使用COPY命令或数据集成功能。
+
+# 参考文档
+
+[Python SDK上传数据](python_reference/bulkload-upload.md)
+
+## 应用场景
+
+* 适用于需要批量上传数据的业务场景。
+* 适合熟悉Python并需要自定义数据导入逻辑的开发人员。
+
+## 使用限制
+
+* BulkloadStream不支持主键（pk）表的写入。
+* 不适用于时间间隔小于五分钟的频繁数据上传场景。
+
+# 使用案例
+
+本案例使用[巴西电子商务](https://www.kaggle.com/datasets/olistbr/brazilian-ecommerce?select=olist_order_items_dataset.csv)公共数据集中的`olist_order_payments_dataset`数据集。
+
+## 前置条件
+
+* 创建目标表`bulk_order_payments`：
+
+```SQL
+
+CREATE TABLE bulk_order_payments (
+          order_id STRING,
+          payment_sequence INT,
+          payment_type STRING,
+          payment_installments INT,
+          payment_value DOUBLE
+          );
+```
+
+* 对目标表具有INSERT权限。
+
+| **参数**    | **是否必填** | **描述**                                                                                                                              |
+| --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| username  | Y        | 用户名                                                                                                                                 |
+| password  | Y        | 密码                                                                                                                                  |
+| service   | Y        | 连接lakehouse的地址, region\_id.api.clickzetta.com。可以在Lakehouse Studio管理-》工作空间中看到jdbc连接串![](../.topwrite/assets/image_1728887857029.png) |
+| instance  | Y        | 可以在Lakehouse Studio管理->工作空间中查看JDBC连接串以获取![](../.topwrite/assets/image_1729051500396.png)                                            |
+| workspace | Y        | 使用的工作空间                                                                                                                             |
+| vcluster  | Y        | 使用的vc                                                                                                                               |
+| schema    | Y        | 访问的schema名                                                                                                                          |
+
+## 使用Python代码开发
+
+使用pip安装Lakehouse依赖的Python包，Python版本要求3.6及以上：
+
+```SQL
+pip install clickzetta-connector
+```
+
+### 编写Python代码
+
+```SQL
+from clickzetta import connect
+import csv
+
+def get_lakehouse_connect():
+    conn = connect(
+        username='',
+        password='',
+        service='api.clickzetta.com',
+        instance='',
+        workspace='',
+        schema='public',
+        vcluster='default_ap')
+    return conn
+
+conn = get_lakehouse_connect()
+bulkload_stream = conn.create_bulkload_stream(schema='public', table='bulk_order_payments')
+writer = bulkload_stream.open_writer(0)
+
+with open('olist_order_payments_dataset.csv', 'r') as csvfile:
+    reader = csv.reader(csvfile)
+    # Skip header row
+    next(reader)
+    # 上传数据
+    for record in reader:
+        # 使用bulkload创建row上传
+        bulkloadrow = writer.create_row()
+        bulkloadrow.set_value('order_id', record[0])
+        bulkloadrow.set_value('payment_sequence', int(record[1]))
+        bulkloadrow.set_value('payment_type', record[2])
+        bulkloadrow.set_value('payment_installments', int(record[3]))
+        bulkloadrow.set_value('payment_value', float(record[4]))
+        # 必须调用，否则无法发送到服务端数据
+        writer.write(bulkloadrow)
+writer.close()
+# 提交数据导入完成
+bulkload_stream.commit()
+```
+
+^

package/bin/skills/lakehouse-doc/references/use-schema.md

@@ -0,0 +1,49 @@
+
+# USE 语句
+
+指定用于当前会话的 SCHEMA 和计算资源。
+
+
+## 语法
+
+```SQL
+-- 切换 schema
+USE [SCHEMA] schema_name;
+-- 切换计算资源
+USE VCLUSTER vc_name;
+```
+
+## 参数说明
+
+1. `SCHEMA`：这是一个可选关键字，可以在语句中省略。
+2. `schema_name`：指定要切换的 schema 名称。
+
+## 使用示例
+
+1. 切换到名为 `ods_schema` 的 schema：
+
+   ```SQL
+   USE ods_schema;
+   -- 查询当前的 SCHEMA
+   SELECT CURRENT_SCHEMA();
+   ```
+
+2. 假设当前工作空间中存在名为 `sample_vc` 的计算集群，您可以使用以下命令切换到该计算集群：
+
+   ```SQL
+   USE VCLUSTER sample_vc;
+   -- 查询当前的计算资源
+   SELECT CURRENT_VCLUSTER();
+   ```
+
+3. 如果您想要切换到名为 `high_performance_vc` 的计算集群，您可以执行以下命令：
+
+   ```SQL
+   USE VCLUSTER high_performance_vc;
+   ```
+
+## 使用注意事项
+
+- 在使用客户端工具（如 [客户端 SQLLine](<connect-with-cli.md>)、[DBeaver](<eco_integration/dbeaver-lakehouse.md>) 等）连接时，相关操作会在整个会话期间生效。
+- 如果您使用 Lakehouse Studio 界面，建议优先通过页面来切换 schema 和计算集群。如果直接使用命令切换，其效果仅临时生效，且需要和要执行的 SQL 语句一起选中执行方可生效。
+![](.topwrite/assets/image_1741317824124.png)

package/bin/skills/lakehouse-doc/references/use-vcluster.md

@@ -0,0 +1,38 @@
+
+# USE 语句
+
+指定用于当前会话的计算资源。
+
+
+## 语法
+
+```SQL
+--切换计算资源
+USE VCLUSTER vc_name;
+```
+
+## 参数说明
+
+1. `VCLUSTER`：必填关键字。
+2. `vc_name`：指定要切换的计算资源的名称。
+
+## 使用示例
+
+1. 假设当前工作空间中存在名为sample_vc的计算集群，您可以使用以下命令切换到该计算集群：
+
+   ```SQL
+   USE VCLUSTER sample_vc;
+    --查询当前的计算资源
+    SELECT CURRENT_VCLUSTER();
+   ```
+
+2. 如果您想要切换到名为high_performance_vc的计算集群，您可以执行以下命令：
+
+   ```SQL
+   USE VCLUSTER high_performance_vc;
+   ```
+
+
+## 注意事项
+- 在使用客户端工具（如[客户端SQLLine](<connect-with-cli.md>)、[DBeaver](<eco_integration/dbeaver-lakehouse.md>)等）连接时，相关操作会在整个会话期间生效。而如果您使用 Lakehouse Studio 界面，建议优先通过页面来切换 Schema 和计算集群。需要说明的是，若直接使用相关命令，其效果仅临时生效，且需要和要执行的 SQL 语句一起选中执行方可生效。
+![](.topwrite/assets/image_1741317824124.png)