@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/bulkloadv1-java-sdk.md

@@ -0,0 +1,178 @@
+# 使用 Python 批量上传数据（BulkLoadV1）
+>原有BulkLoadV1接口会停止维护,陆续下线请您尽快迁移到[BulkloadV2接口](<bulkloadv2-java-sdk.md>)，clickzetta-java版本需要3.0.21 或更高版本。BulkloadV2接口上线:全新V2接口发布,支持更高效的数据处理能力和更稳定的服务保障。V2新版本收益:
+i.性能提升30%:显著提升数据集成同步任务及自定义批量与寻入任务的效率。
+ii.流程优化:引入基于Table Volume的数据暂存和加载机制,增强任务的可审计性和数据追溯能力,让您的数据管理更加规范和安全。
+## MAVEN依赖
+您可以通过 Maven 依赖的方式引入 `clickzetta-java` SDK：
+
+```xml
+<dependency>
+  <groupId>com.clickzetta</groupId>
+  <artifactId>clickzetta-java</artifactId>
+  <version>${version}</version>
+</dependency>
+```
+
+直接点击maven库在库中搜索
+`clickzetta-java`可以获取到最新的更新版本记录
+
+* [下载地址一](https://central.sonatype.com/artifact/com.clickzetta/clickzetta-java/versions)
+* [下载地址二](https://mvnrepository.com/artifact/com.clickzetta/clickzetta-java)
+
+
+## 创建 BulkloadStream
+
+要通过 ClickZetta 客户端创建一个批量写入流，请参考以下示例代码：
+
+```java
+RowStream stream = client.newBulkloadStreamBuilder()
+        .schema(schema)
+        .table(TABLE_NAME)
+        .operate(RowStream.BulkLoadOperate.APPEND)
+        .build();
+```
+
+### Options
+
+在clickzetta-java版本3.0.18以后提供了options。options用于指定上传选项入指定分取
+
+```
+bulkloadStream=client.newBulkloadStreamBuilder().schema(schema).table(table)
+                .options(BulkLoadOptions.newBuilder().withPartitionSpecs(Optional.of("your_partition_spec")).build())
+
+                .operate(RowStream.BulkLoadOperate.APPEND)
+                .build();
+```
+
+* withPartitionSpecs 用于指定目标表的分区信息，控制数据写入的分区行为。
+
+  * 非分区表：忽略此参数或设置为
+  * 分区表：
+    * 静态分区写入，需要将所有数据写入指定的固定分区，无论源数据中分区列的实际值是什么，写入目标表时都会使用 `partition_spec` 指定的分区值，所有数据都会写入到同一个指定分区中。参数格式是'分区列1=值1,分区列2=值2'
+      - 动态分区写入，根据数据中分区列的实际值，自动写入到对应分区。忽略此参数，系统根据数据中分区列的值自动创建或写入相应分区
+
+### 操作类型
+
+在创建 Bulkload 时，可以通过 `operate` 方法指定以下操作类型：
+
+* `RowStream.BulkLoadOperate.APPEND`：追加模式，向表中添加数据。
+  ```
+  bulkloadStream=client.newBulkloadStreamBuilder().schema(schema).table(table)
+          .operate(RowStream.BulkLoadOperate.APPEND)
+          .build();
+  ```
+
+* `RowStream.BulkLoadOperate.OVERWRITE`：覆盖模式，删除表中现有数据后再写入新数据。
+  ```
+  bulkloadStream=client.newBulkloadStreamBuilder().schema(schema).table(table)
+          .operate(RowStream.BulkLoadOperate.OVERWRITE)
+          .build();
+  ```
+
+## 写入数据
+
+使用 Row 对象表示要写入的具体数据。通过调用 `row.setValue` 方法将数据封装到 Row 对象中。
+
+```java
+Row row = stream.createRow(0);
+row.setValue("id", t);
+row.setValue("name", String.valueOf(t));
+stream.apply(row, 0);
+```
+
+* `createRow` 方法创建 Row 对象时，需要传入一个整数作为分片 ID。这个 ID 可以配合多线程/进程技术，用多个互补相同的分片 ID 来写入数据，从而有效提升写入数据的速度。
+* `setValue` 方法的第一个参数为字段名，第二个参数为具体的数据。要求数据类型与表类型一致。
+* `apply` 方法用于写入数据，需要指定 Row 对象以及相应的分片 ID。
+
+### 写入复杂类型数据
+
+```java
+// 写入数组
+row.setValue("col1", Arrays.asList("first", "b", "c"));
+
+// 写入映射
+final HashMap<Integer, String> map = new HashMap<Integer, String>();
+map.put(t, "first" + t);
+row.setValue("col2", map);
+
+// 写入结构体
+Map<String, Object> struct = new HashMap<>();
+struct.put("first", "first-" + i);
+struct.put("second", i);
+row.setValue("col3", struct);
+```
+
+## 提交数据
+
+批量写入的数据只有在提交之后才可见。因此，提交过程非常重要。
+
+```java
+bulkloadStream.close();
+```
+
+* 通过 `bulkloadStream.getState()` 获取 BulkloadStream 的状态。
+* 如果提交失败，可以通过 `bulkloadStream.getErrorMessage()` 获取错误信息。
+
+## 使用示例
+
+以下是一个使用 Bulkload 写入复杂类型数据的示例：
+
+```java
+// 建表 create table complex_type(col1 array<string>,col2 map<int,string>, col3 struct<x:int,y:int>);
+import com.clickzetta.client.ClickZettaClient;
+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;
+
+public class BulkloadStreamDemo {
+    public static void main(String[] args) throws Exception{
+        if (args.length != 5) {
+            System.out.println("input arguments: jdbcUrl, username, password");
+            System.exit(1);
+        }
+        String jdbcUrl = args[0];
+        String username = args[1];
+        String password = args[2];
+        String schema = args[3];
+        String table = args[4];
+
+        ClickZettaClient client = ClickZettaClient.newBuilder().url(jdbcUrl).username(username).password(password).build();
+
+
+        BulkloadStream bulkloadStream = client.newBulkloadStreamBuilder()
+                .schema(schema)
+                .table(table)
+                .operate(RowStream.BulkLoadOperate.APPEND)
+                .build();
+
+        for (int t = 0; t < 100; t++) {
+            Row row = bulkloadStream.createRow(0);
+            row.setValue("col1", Arrays.asList("first", "b", "c"));
+            final HashMap<Integer, String> map = new HashMap<Integer, String>();
+            map.put(t,"first"+t);
+            row.setValue("col2", map);
+            Map<String, Object> struct = new HashMap<>();
+            struct.put("x", t);
+            struct.put("y", t+1);
+            row.setValue("col3", struct);
+            bulkloadStream.apply(row, 0);
+        }
+        // 必须调用 stream close 接口，触发提交动作
+        bulkloadStream.close();
+
+        // 轮训提交状态，等待提交结束
+        while(bulkloadStream.getState() == StreamState.RUNNING) {
+            Thread.sleep(1000);
+        }
+        if (bulkloadStream.getState() == StreamState.FAILED) {
+            throw new RuntimeException(bulkloadStream.getErrorMessage());
+        }
+        client.close();
+    }
+}
+```
+
+* Lakehouse url可以在Lakehouse Studio管理-》工作空间中看到jdbc连接串以查看![](../.topwrite/assets/image_1739177196184.png)
+
+

package/bin/skills/lakehouse-doc/references/bulkloadv1-python-sdk.md

@@ -0,0 +1,169 @@
+# 使用 Python 批量上传数据（BulkLoadV1）
+
+
+
+Clickzetta Lakehouse 通过 `clickzetta-connector` 包提供了使用 Python 语言进行批量数据上传（Bulkload）的 API。该 API 使得数据可以直接从客户端发送到存储系统，传输过程不消耗计算资源，数据在显式 commit 后可见（commit 过程会消耗少量计算资源）。适用于高吞吐、对数据新鲜度（data freshness）要求相对宽松的场景。
+
+通过 Bulkload 相关 API，可以实现单线程数据上传。
+
+安装
+
+如果安装过旧版本的 SDK，先卸载避免冲突：
+
+```shell
+pip uninstall clickzetta-connector clickzetta-connector-python clickzetta-sqlalchemy clickzetta-ingestion-python clickzetta-ingestion-python-v2 -y
+```
+
+> 卸载前请记录好旧版本的包，以防需要回退。查看已安装包版本命令：
+
+```shell
+pip show clickzetta-connector clickzetta-sqlalchemy clickzetta-ingestion-python clickzetta-ingestion-python-v2 clickzetta-connector-python
+```
+
+安装最新版本（要求 Python >=3.7）：
+
+```bash
+pip install clickzetta-connector -U -i https://pypi.org/simple/
+```
+
+
+## 批量导入原理
+
+批量上传的 SDK 提供了一种高效的数据导入机制，适用于 Clickzetta Lakehouse。以下是其工作原理的简化描述和流程图：
+
+1. **数据上传**：通过SDK，您的数据首先被上传到对象存储服务。这一步骤的性能受到本地网络速度和并发连接数的影响。
+2. **触发导入**：数据上传完成后，当您调用`bulkloadStream.commit()`方法时，SDK会自动触发一个SQL命令，将数据从对象存储导入到Lakehouse的表中。不建议您在一个任务中频繁调用`bulkloadStream.commit()`，该方法最终只能调用一次。
+3. **计算资源**：上传数据建议选择[通用型计算集群](../create_cluster.md)（GENERAL PURPOSE VIRTUAL CLUSTER）通用型计算资源，它更适合运行批量作业和加载数据作业。数据从对象存储到 Lakehouse 表的导入速度取决于您配置的计算资源的大小。
+4. **分片上传优化**：处理大于1GB的压缩数据时，建议在`createRow`方法中为每个并发线程或进程分配唯一的分片ID。这种做法能够充分发挥多线程或多进程的并行处理优势，显著提升数据导入效率。最佳实践是根据并发的数量来确定分片 ID 的数量，确保每个并发对应一个独立的分片 ID。如果多个并发被分配了相同的分片 ID，最终写入的数据可能会发生覆盖，导致先前写入的数据丢失。为确保所有分片的数据都被正确导入表中，请在所有并发操作完成后，调用`bulkloadStream.commit()`方法来提交整个导入任务。
+
+以下是批量导入原理的流程图：
+
+```
+[SDK上传数据] ──> [对象存储] ──> [调用bulkloadStream.close()]
+                                ↓
+                         [触发SQL命令] ──> [Lakehouse表]
+```
+
+## 单线程写入
+
+假设上传数据的目标表为 `public.bulkload_test`，DDL 如下：
+
+```sql
+CREATE TABLE public.bulkload_test (
+    i BIGINT,
+    s STRING,
+    d DOUBLE
+);
+```
+
+单线程模式的完整样例代码：
+
+```python
+from clickzetta import connect
+
+conn = connect(
+    username='your_username',
+    password='your_password',
+    service='<region\_id>.api.clickzetta.com',
+    instance='your_instance',
+    workspace='your_workspace',
+    schema='public',
+    vcluster='default'
+)
+
+bulkload_stream = conn.create_bulkload_stream(schema='public', table='bulkload_test')
+
+writer = bulkload_stream.open_writer(0)
+for index in range(1000000):
+    row = writer.create_row()
+    row.set_value('i', index)
+    row.set_value('s', 'Hello')
+    row.set_value('d', 123.456)
+    writer.write(row)
+writer.close()
+
+bulkload_stream.commit()
+```
+
+## API 分步详解
+
+1. 创建 `connection` 对象，根据您的实际情况替换参数即可：
+   ```python
+   conn = connect(
+       username='your_username',
+       password='your_password',
+       service='<region\_id>.api.clickzetta.com',
+       instance='your_instance',
+       workspace='your_workspace',
+       schema='public',
+       vcluster='default'
+   )
+   ```
+
+| **参数**    | **是否必填** | **描述**                                                                                                                          |
+| --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| 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 名                                                                                                                      |
+
+2. 创建 `BulkLoad Stream` 对象，指定上传的目标表、上传方式等：
+   **必选参数**
+   * `table`：表名称
+   **可选参数**
+   * `schema`：如未指定，则使用 `connection` 对象中指定的 `schema`
+    * `operation`
+        * `BulkLoadOperation.APPEND`：增量模式（写入的数据都作为新数据，不对已有数据有任何影响）
+        * `BulkLoadOperation.OVERWRITE`：覆盖模式（清空已有表数据，将新数据写入表中）
+
+* `partition_spec`：用于指定目标表的分区信息，控制数据写入的分区行为。
+    * 非分区表：忽略此参数或设置为空。
+    * 分区表：
+        * 静态分区写入：需要将所有数据写入指定的固定分区。无论源数据中分区列的实际值是什么，写入目标表时都会使用 `partition_spec` 指定的分区值，所有数据都会写入到同一个指定分区中。参数格式为 '分区列1=值1,分区列2=值2'。
+        * 动态分区写入：根据数据中分区列的实际值，自动写入到对应分区。忽略此参数，系统根据数据中分区列的值自动创建或写入相应分区。
+
+  ```python
+
+  from clickzetta.bulkload.bulkload_enums import BulkLoadOperation
+
+  # APPEND 模式构建，默认 operation 即为 APPEND
+  bulkload_stream = conn.create_bulkload_stream(schema='public', table='bulkload_append_test')
+
+
+
+  # OVERWRITE 模式构建
+  bulkload_stream = conn.create_bulkload_stream(
+      schema='public',
+      table='bulkload_overwrite_test',
+      partition_spec='pt=2023-07-01',
+      operation=BulkLoadOperation.OVERWRITE
+  )
+  ```
+
+3. 创建 `writer` 并写入数据：
+   每个 `bulkload stream` 可以创建多个 `writer`，不同的 `writer` 需要用不同的 id 标识。使用多个 `writer` 可以实现在一次 commit 中多线程并发写入的场景。
+   ```python
+   # 利用 `open_writer` 方法创建 `writer`，参数为 `writer` id。单机模式下，只有一个 `writer` id 即可，直接传入 0.
+   writer = bulkload_stream.open_writer(0)
+   ```
+4. 写入数据：
+   ```python
+   # 每一行数据都需要用 create_row() 方法创建 Row 对象，然后用 set_value() 方法写入具体数据。
+   # set_value() 第一个参数为列名，第二个参数为值
+   row = writer.create_row()
+   row.set_value('i', 1)
+   row.set_value('s', 'January')
+   row.set_value('d', 123.456)
+   writer.write(row)
+   ```
+   通过 writer 写入的数据将直接在存储系统中形成相应的 parquet 文件。writer 将根据写入的数据量自动进行文件切割。当 writer 写入数据结束后，需要显式调用 writer.close() 来保证数据完整性。
+   ```python
+   writer.close()
+   ```
+5. 提交 stream。commit 前需要确保各 writer 均已完成写入并关闭。commit 成功后数据在表中可见。
+   ```python
+   bulkload_stream.commit()
+   ```

package/bin/skills/lakehouse-doc/references/byos_general.md

@@ -0,0 +1,165 @@
+# 私有存储（BYOS）
+> 【预览发布】本功能当前处于受邀预览发布阶段。如果需要使用，请联系我们的技术支持同学协助处理。
+## 一、功能概述
+
+私有存储BYOS（Bring Your Own Storage）功能允许您使用自己的对象存储服务作为ClickZetta Lakehouse的数据存储位置。通过此功能，您可以：
+
+* 在Web界面完成私有存储配置，无需复杂的技术操作；
+* 将工作空间数据存储在您自己云平台账号管理的对象存储中；
+* 自主管理存储成本和存储策略。
+
+## 二、适用场景
+
+BYOS功能适合以下场景：
+
+1. **数据合规要求**：需要将数据存储在自有云账号的对象存储内，以满足合规要求；
+2. **数据主权**：需要完全掌控数据的存储位置和访问权限；
+3. **混合部署**：部分工作空间使用托管存储，部分合规要求高的工作空间使用自有存储。
+
+## 三、前置准备
+
+### 3.1 创建存储桶（Bucket）
+
+在配置BYOS前，您需要先创建符合要求的存储桶：
+
+#### 必须满足的条件：
+
+| 配置项      | 要求                         | 说明                     |
+| -------- | -------------------------- | ---------------------- |
+| **所属区域** | 与Lakehouse实例同一云厂商、同一Region | 避免跨区域传输费用              |
+| **存储类型** | 标准存储                       | 不要使用低频或归档存储，避免产生额外访问费用 |
+| **读写权限** | 私有（私有读写）                   | 确保数据安全                 |
+| **独占使用** | 专用于Lakehouse               | 不可与其他业务系统共用，避免数据冲突     |
+
+#### 存储桶（bucket）建议配置：
+
+| 配置项        | 建议值  | 说明                                             |
+| ---------- | ---- | ---------------------------------------------- |
+| **存储冗余**   | 按需选择 | 本地冗余存储可满足基本需求；高可用要求可选同城冗余。                     |
+| **版本控制**   | 关闭   | Lakehouse已自行管理数据版本，开启可能产生额外费用。                 |
+| **服务端加密**  | 关闭   | Lakehouse会根据工作空间配置，对部分数据单独开启加密。全局开启加密可能影响读写性能。 |
+| **生命周期规则** | 不配置  | Lakehouse自行管理文件生命周期。                           |
+
+### 3.2 创建访问策略
+
+您需要为ClickZetta Lakehouse子账号授权访问您的存储桶。具体的授权策略详见——
+
+## 四、配置步骤
+
+### 步骤1：进入私有存储管理
+
+:-: ![](/.topwrite/assets/image_1760181980735.png =759)
+
+1. 登录ClickZetta Lakehouse控制台
+2. 进入【管理】→【更多】→【私有存储】页面
+3. 点击【+新建】按钮
+
+### 步骤2：填写存储信息
+
+![](/.topwrite/assets/image_1760182222984.png)
+
+在弹出的配置窗口中填写：
+
+1）名称【必填】：以字母（AZ、az）或下划线（“\_”）开头，长度为3\~28个字符。须在您的服务实例内唯一。保存后不可更改。
+
+2）主账号【必填】：输入您在云平台中的账号ID，以便调用云平台接口时使用您授权的角色和Bucket。可在登录云平台账号后找到并复制。
+
+      阿里云：
+
+:-: ![](/.topwrite/assets/image_1760182500707.png =253)
+
+    腾讯云：
+
+:-: ![](/.topwrite/assets/image_1760182704445.png =250)
+
+3）Bucket名称【必填】：输入您希望使用的Bucket名称，或者Bucket名称+路径。Bucket名称+路径的写法示例为：
+
+```
+bucket_name/subpath
+```
+
+4）描述【非必填】：对私有存储的描述，可帮助使用者了解该私有存储的业务用途，避免误操作。
+
+完成上述信息的填写后，点击“确定”按钮，即完成私有存储的创建。
+
+一个Lakehouse服务实例下可以创建多个私有存储。
+
+### 步骤3：校验配置
+
+创建完成后，私有存储的默认连通状态为“失败”，需要点击私有存储右侧的“测试联通”按钮，测试私有存储的连通性。Lakehouse测试连通性时将进行的操作是：使用Lakehouse在云平台的账号调用同云平台同region的HeadBucket/GetBucketInfo等相似功能的接口，确认：
+
+* 存储桶（Bucket）是否存在；
+* 所在地域是否正确；
+* 访问权限是否配置正确。
+
+校验通过后，列表中该私有存储的连接状态变为“成功”。
+
+### 步骤5：关联工作空间
+
+在创建新的工作空间时，可使用已有的私有存储作为该工作空间的存储位置。
+
+1）在新建工作空间弹窗中，点击并展开【高级设置】；
+
+:-: ![](/.topwrite/assets/image_1760183458961.png =516)
+
+2）打开私有存储开关，选择已有的私有存储位置。一个私有存储位置可以关联多个工作空间。多个工作空间的数据会在该存储桶（bucket）下的子路径中区分开，不会互相影响。
+
+:-: ![](/.topwrite/assets/image_1760183572318.png =516)
+
+3）点击“确定”完成工作空间创建。
+
+## 五、重要限制
+
+### 5.1 功能限制
+
+* 工作空间关联存储后**不可更改**；
+* 已关联工作空间的私有存储位置**不可删除**，须先删除工作空间后才可删除。
+
+### 5.2 区域限制
+
+* 仅支持同一云厂商、同一Region的存储桶；
+* AWS环境需确保在同一可用区，避免跨区流量费用。
+
+### 5.3 责任边界
+
+* 使用私有存储时，私有存储指向存储桶（bucket）的可用性和可靠性由您自行负责；
+* 非经由ClickZetta操作造成的数据问题需由您自行承担。
+
+### 5.4 费用说明
+
+使用BYOS后：
+
+* ClickZetta不再收取私有存储中的存储容量费用，仍继续收取其他托管存储位置中的存储费用。
+* 您需直接向云厂商支付：
+  * 存储容量费用
+  * API访问费用
+  * 公网流量费用（如有）
+* 日志和临时文件将占用您的存储空间
+
+### 5.5 性能注意
+
+* 存储性能直接影响Lakehouse运行效率
+* 需确保存储服务的QPS和带宽满足需求
+* 避免与其他业务争抢存储资源
+
+^
+
+## 六、常见问题
+
+**Q1: 可以将现有工作空间迁移到BYOS吗**？ 
+
+A: 不可以。工作空间的存储位置一旦确定就不能更改。
+
+^
+
+**Q2: 一个存储桶可以被多个工作空间使用吗**？
+
+A: 可以。一个BYOS配置可以关联多个工作空间，但建议根据实际需求合理规划。
+
+^
+
+**Q3: 使用BYOS后，ClickZetta还会产生哪些存储**？ 
+
+A: 查询缓存、临时文件等会存储在您的存储桶中，这部分会占用一定容量。
+
+^

package/bin/skills/lakehouse-doc/references/byos_tencentcloud_configration.md

@@ -0,0 +1,138 @@
+# 策略阿里云私有存储配置
+
+本指南将帮助您在腾讯云对象存储服务（COS）上配置BYOS（私有存储），使ClickZetta Lakehouse能够使用您的OSS存储桶作为数据存储位置。
+
+## 前提条件
+
+* 拥有腾讯云账号并开通COS服务
+* 了解您的ClickZetta Lakehouse实例所在的云平台和地域（Region）
+* 拥有COS存储桶的管理权限
+
+## 步骤一：准备COS存储桶
+
+### 创建新存储桶（推荐）
+
+如果您选择创建新的存储桶专用于ClickZetta Lakehouse：
+
+1. **登录腾讯云COS控制台**
+
+   访问：<https://console.cloud.tencent.com/cos/bucket>
+
+2. **点击"创建Bucket**"
+
+![](/.topwrite/assets/ef4ec49e-2d3e-459b-b649-da670fe4a345.jpeg)
+
+**配置Bucket基本信息**
+
+| 配置项       | 设置值                           | 说明                                            |
+| --------- | ----------------------------- | --------------------------------------------- |
+| **所属地域**  | 与Lakehouse实例相同                | ⚠️ **关键要求**：必须选择与ClickZetta Lakehouse实例相同的地域。 |
+| **名称**    | 自定义（如：`my-company-lakehouse`） | 全局唯一，建议包含用途标识。                                |
+| **访问权限**  | 私有读写                          | 确保数据安全。                                       |
+| **多AZ特性** | 关闭                            | 可根据数据可用行、可靠性需求选择开启。开启将增加云厂商收取的存储费用。           |
+| **版本控制**  | 关闭                            | 避免产生额外费用。                                     |
+| **服务端加密** | 不加密                           | Lakehouse会自行管理加密，全局加密可能影响性能。                  |
+
+其他配置均可选择不开启。
+
+### 使用已有存储桶
+
+如果您选择使用已有的存储桶：
+
+#### 验证地域配置
+
+存储桶必须与ClickZetta Lakehouse实例在同一地域（Region）。例如：
+
+\- Lakehouse实例在：腾讯云-上海
+
+\- COS Bucket必须在：中国-上海
+
+您的服务实例所在“云服务商和地域”信息可在服务实例首页查询到：
+
+:-: ![](/.topwrite/assets/image_1760270239517.png =747)
+
+#### 选择存储路径
+
+您可以选择以下方式之一：
+
+**方式一：使用整个Bucket（推荐**）
+
+适用场景：Bucket专用于Lakehouse。
+
+**方式二：使用Bucket下的特定目录**
+
+适用场景：需要在同一Bucket中隔离不同用途的数据。
+
+***
+
+**数据安全警告**：
+
+1\. 请确保所选路径不与其他业务系统共用；
+
+2\. ClickZetta Lakehouse会对该路径下的文件进行读、写、删除操作；
+
+3\. 共用路径可能导致：  &#x20;
+
+* 数据被意外删除或覆盖
+* 影响其他业务系统的正常运行
+* 数据一致性问题
+
+建议：为Lakehouse创建独立的Bucket或使用独立的目录。
+
+###
+
+### 记录必要信息
+
+请记录以下信息，后续配置时需要使用：
+
+* **Bucket名称**
+* **Bucket所在地域**
+* **您的腾讯云主账号ID**
+
+查看主账号ID的方法：
+
+1. 登录腾讯云控制台
+2. 点击右上角头像
+3. 在"账号信息"中查看"账号ID"
+
+## 步骤二：配置Bucket访问策略
+
+**1. 进入Bucket管理页面**
+
+* 在COS控制台找到您的Bucket，点击Bucket名称进入详情页
+
+**2. 进入权限管理页面**
+
+:-: ![](/.topwrite/assets/39c3600e-2652-4475-a7fa-f2f40bac51e3.jpeg =772)
+
+* 点击左侧菜单"权限管理" 。
+* 在“Policy权限设置”栏点击"添加策略"。
+
+**3. 配置授权策略**
+
+选择"自定义授权"，填写以下信息：
+
+| **配置项**   | **设置值**                                                                        |
+| --------- | ------------------------------------------------------------------------------ |
+| **被授权用户** | 指定用户                                                                           |
+| **资源范围**  | bucket专用于ClickZetta时选择：整个存储桶&#xA;ClickZetta使用指定目录时选择：指定目录                      |
+| **请选择模板** | 自定义策略                                                                          |
+| **效力**    | 允许                                                                             |
+| **用户**    | 选择“主账号”，并填写Clickzetta Lakehouse在腾讯云的主账号：100029595716                           |
+| **资源**    | bucket专用于ClickZetta时选择：整个存储桶&#xA;ClickZetta使用指定目录时选择：指定资源路径，并填写路径。注意在子目录后加/\*。 |
+| **操作**    | 选择“所有操作”。                                                                      |
+| **条件**    | 不添加任何条件。                                                                       |
+
+### :-: ![](/.topwrite/assets/image_1760273495375.png =647)
+
+### :-: ![](/.topwrite/assets/image_1760273408668.png =653)
+
+^
+
+**为什么需要所有操作权限**？
+
+ClickZetta Lakehouse需要该路径下的所有操作权限来确保能正常进行数据的增删和读写功能。
+
+^
+
+完成上述配置后，即可将您的私有存储路径和云平台主账号ID用于私有存储的新建中。

package/bin/skills/lakehouse-doc/references/cache-command.md

@@ -0,0 +1,39 @@
+## 功能介绍
+
+`CACHE TABLE` 命令允许用户通过 SQL 语句在 AP VC 启动阶段或在执行 Adhoc 查询时，将冷数据提前加载到 VCluster 中，从而提高查询速度。目前，此功能仅适用于 ANALYTICAL VCLUSTER。
+
+## 语法
+
+```
+CACHE TABLE table_name;
+```
+
+## 参数说明
+
+- `table_name`: 指定需要缓存的表名。
+
+## 使用示例
+
+1. 将指定表临时缓存到 VCluster 中：
+
+   ```
+   CACHE TABLE tpc100g.lineitem, nation;
+   ```
+
+2. 将多个表临时缓存到 VCluster 中：
+
+   ```
+   CACHE TABLE tpc100g.lineitem, tpc100g.nation, tpc100g.region;
+   ```
+
+3. 查看当前缓存状态：
+
+   ```
+   SHOW CACHED STATUS;
+   ```
+
+## 注意事项
+
+- 确保在执行 `CACHE TABLE` 命令时，已正确指定表名。
+
+