@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/config-datasource.md

@@ -0,0 +1,79 @@
+# 数据源管理
+
+## 简介
+
+本文档旨在指导用户如何配置和管理数据源，以便在 Lakehouse 产品中实现高效的数据同步任务。通过本文档，您将了解如何添加不同类型的数据源，并通过 SSH Tunnel 连接 VPC 内的数据源。
+
+## 操作步骤
+
+1. **登录与访问数据源管理页面**
+
+   首先，登录Lakehouse产品控制台。在控制台首页，选择“管理”模块，点击进入“数据源”页面。您将看到一个数据源列表，显示了当前已配置的所有数据源。
+   ![](.topwrite/assets/image_1728992949517.png =640)
+
+2. **新建数据源**
+
+   在数据源列表页面，点击右上角的“新建数据源”按钮。此时，您需要选择数据源类型。Lakehouse 支持多种数据源类型，包括但不限于 MySQL、Oracle、SQL Server 等。
+
+   ![](.topwrite/assets/image_1736253182858.png =640)
+
+3. **填写数据源定义并进行连通性测试**
+
+   根据您选择的数据源类型，填写相应的连接信息。例如，对于 MySQL 数据源，您需要提供数据库地址、端口、用户名、密码等信息。填写完毕后，点击“测试连接”按钮，以确保所填写的信息正确无误。
+
+   ![](.topwrite/assets/image_1728993014881.png =640)
+
+## 通过SSH Tunnel连接VPC内数据源
+
+### 前置条件
+
+1. **VPC内数据源访问限制**
+
+   确保您的 VPC 内数据源（如阿里云 RDS for MySQL 数据库）仅提供内网访问。这意味着数据源不对外公开，从而提高了数据安全性。
+
+2. **SSH Tunnel服务器准备**
+
+   准备一台位于 VPC 内的 ECS 服务器，该服务器应具备公网访问能力，并支持 SSH 登录。此外，确保数据同步服务可以通过公网访问到这台 ECS 服务器。
+
+3. **VPC内网络访问配置**
+
+   确保 VPC 内的 ECS 服务器可以通过内网 IP 或域名访问 VPC 内的数据源。这将便于在建立 SSH Tunnel 时，数据同步服务能够顺利连接到数据源。
+
+### 配置数据源连接参数
+
+在新建数据源页面中，启用“通过 SSH Tunnel 连接”选项。根据页面提示，填写以下信息：
+
+* **SSH Tunnel服务器公网地址**：输入 VPC 内 ECS 服务器的公网 IP 地址或域名。
+* **SSH端口**：输入 ECS 服务器上 SSH 服务的端口号（默认为 22）。
+* **SSH用户名**：输入用于SSH登录的用户名。
+* **SSH密码**：输入对应的SSH登录密码。
+
+![](.topwrite/assets/image_1690124173674.png =640)
+
+完成以上配置后，点击“测试连接”按钮。如果连接成功，您将看到一个绿色的勾号提示。这意味着数据同步服务在任务启动时，可以通过 SSH Tunnel 与 VPC 内的数据源建立网络连接。
+
+## 使用示例
+
+### 示例1：连接阿里云RDS for MySQL数据库
+
+1. 在数据源类型选择页面，选择“MySQL”作为数据源类型。
+2. 在数据源定义页面，填写以下信息：
+   * 主机名/地址：填写阿里云 RDS for MySQL 的内网 IP 地址。
+   * 端口：填写MySQL数据库的端口号（默认为3306）。
+   * 用户名：填写数据库的访问用户名。
+   * 密码：填写对应的用户密码。
+3. 启用“通过 SSH Tunnel 连接”选项，并填写 VPC 内 ECS 服务器的相关信息。
+4. 点击“测试连接”，确认连接成功后，点击“保存”按钮完成数据源配置。
+
+### 示例2：连接Oracle数据库
+
+1. 在数据源类型选择页面，选择“Oracle”作为数据源类型。
+2. 在数据源定义页面，填写以下信息：
+   * 主机名：填写 Oracle 数据库的内网 IP 地址。
+   * 端口：填写Oracle数据库的端口号（默认为1521）。
+   * 用户名：填写数据库的访问用户名。
+   * 密码：填写对应的用户密码。
+3. 启用“通过 SSH Tunnel 连接”选项，并填写 VPC 内 ECS 服务器的相关信息。
+4. 点击“测试连接”，确认连接成功后，点击“保存”按钮完成数据源配置。
+
+^

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

@@ -0,0 +1,254 @@
+# Dify中配置云器Lakehouse Volume作为文件存储服务
+
+## 📋 概述
+
+云器Lakehouse Volume存储为[Dify](https://dify.ai/)提供企业级的文件存储后端，支持三种Volume类型：
+
+* **Table Volume** - 知识库文件管理（暂不推荐）
+* **User Volume** - 知识库文件存储（推荐）
+* **External Volume** - 企业数据湖集成
+
+## 🚀 快速开始
+
+### 环境要求
+
+* 云器Lakehouse实例
+* Dify 1.7.2+
+
+### 基础配置
+
+在Dify `.env` 文件中配置：
+
+```bash
+# 使用ClickZetta Volume作为存储后端
+STORAGE_TYPE=clickzetta-volume
+
+# ClickZetta连接配置
+CLICKZETTA_VOLUME_USERNAME=your_username
+CLICKZETTA_VOLUME_PASSWORD=your_password
+CLICKZETTA_VOLUME_INSTANCE=your_instance
+CLICKZETTA_VOLUME_SERVICE=region_id.api.clickzetta.com
+CLICKZETTA_VOLUME_WORKSPACE=your_workspace
+CLICKZETTA_VOLUME_VCLUSTER=default_ap
+CLICKZETTA_VOLUME_SCHEMA=dify
+
+# Volume类型配置
+CLICKZETTA_VOLUME_TYPE=table  # table|user|external
+CLICKZETTA_VOLUME_TABLE_PREFIX=dataset_
+CLICKZETTA_VOLUME_DIFY_PREFIX=dify_km    # 目录前缀，与其他应用隔离
+CLICKZETTA_VOLUME_NAME=  # 仅External Volume需要
+```
+
+## 📂 Volume类型详细配置
+
+### Volume类型选择
+
+云器Lakehouse Volume支持三种类型，每种适用于不同场景：
+
+| 类型           | 适用场景   | 配置复杂度 | 权限控制        |
+| -------------- | ---------- | ---------- | --------------- |
+| **user**       | 知识库管理  | 简单       | 用户级          |
+| **table**      | 企业级多租户 | 中等       | 表级+用户级     |
+| **external**   | 数据湖集成  | 复杂       | Volume级+存储级 |
+
+> 💡 **选择建议**：
+>
+> * 个人使用或小团队 → 选择 `user`
+> * 企业级环境需要权限控制 → 选择 `table`
+> * 需要数据湖集成 → 选择 `external`
+
+### 1. Table Volume配置
+
+```bash
+# Table Volume配置
+CLICKZETTA_VOLUME_TYPE=table
+CLICKZETTA_VOLUME_TABLE_PREFIX=dataset_
+
+# 知识库文件组织结构
+# dataset_{dataset_id}/
+# ├── raw/           # 原始上传文档
+# ├── processed/     # 处理后文件  
+# ├── metadata/      # 元数据文件
+# └── exports/       # 导出文件
+```
+
+**特点**：
+
+* ✅ 权限继承表权限，安全性高
+* ✅ 与知识库数据关联紧密
+* ✅ 支持多租户隔离
+* ✅ 自动表名映射
+
+**使用场景**：
+
+* 知识库文档存储
+* 向量数据库关联文件
+* 多租户文件隔离
+
+### 2. User Volume配置（推荐用于知识库）
+
+```bash
+# User Volume配置
+CLICKZETTA_VOLUME_TYPE=user
+CLICKZETTA_VOLUME_DIFY_PREFIX=dify_km    # 目录前缀，默认 dify_km
+
+# 用户文件组织结构（自动添加前缀）
+# dify_km/
+# ├── upload_files/  # 用户上传文件
+# ├── tools/         # 工具文件
+# ├── website_files/ # 网站文件
+# ├── temp/          # 临时文件
+# └── cache/         # 缓存文件
+```
+
+**特点**：
+
+* ✅ 用户级别隔离
+* ✅ 自动目录前缀，与其他应用隔离
+* ✅ 默认全部权限
+* ✅ 简单配置
+* ✅ 适合个人文件
+
+**使用场景**：
+
+* 用户个人文件存储
+* 临时文件处理
+* 用户配置文件
+* 小团队文件共享
+
+### 3. External Volume配置
+
+```bash
+# External Volume配置
+CLICKZETTA_VOLUME_TYPE=external
+CLICKZETTA_VOLUME_NAME=your_external_volume_name
+
+# 需要预先创建Storage Connection和External Volume
+# CREATE STORAGE CONNECTION s3_conn TYPE S3 ...
+# CREATE EXTERNAL VOLUME enterprise_data LOCATION 's3://bucket/' ...
+```
+
+**特点**：
+
+* ✅ 企业数据湖集成
+* ✅ 支持S3/OSS/COS
+* ✅ 大容量存储
+* ✅ 跨平台访问
+
+**使用场景**：
+
+* 企业数据湖集成
+* 大文件存储
+* 跨云平台数据共享
+
+**权限管理**：External Volume 需要特殊的权限配置，因为它们连接到外部存储系统。权限管理包括：
+
+* **CREATE权限**：创建External Volume需要管理员权限
+* **USAGE权限**：使用External Volume需要明确的USAGE权限
+* **文件操作权限**：通过底层存储系统（S3/OSS等）的访问策略控制
+
+```sql
+-- 创建External Volume示例
+CREATE STORAGE CONNECTION s3_conn TYPE S3 
+PROPERTIES (
+    'access_key_id'='your_access_key',
+    'secret_access_key'='your_secret_key',
+    'region'='us-west-2'
+);
+
+CREATE EXTERNAL VOLUME enterprise_data 
+LOCATION 's3://your-bucket/dify-data/' 
+STORAGE_CONNECTION=s3_conn;
+
+-- 授予权限示例
+GRANT USAGE ON EXTERNAL VOLUME enterprise_data TO dify_user;
+GRANT CREATE ON EXTERNAL VOLUME enterprise_data TO dify_admin;
+```
+
+**权限检查流程**：
+
+1. 验证用户对External Volume的USAGE权限
+2. 检查文件路径是否在允许的Volume范围内
+3. 通过底层存储连接验证访问权限
+4. 根据操作类型（读/写）进行最终权限确认
+
+## 🚨 故障排查
+
+### 常见问题
+
+#### 1. 连接失败
+
+```bash
+Error: user:username login to clickzetta failed
+```
+
+**解决方案**：
+
+* 检查用户名密码
+* 确认实例和服务地址
+* 验证网络连接
+
+#### 2. 权限不足
+
+**Table Volume权限错误**：
+
+```bash
+Error: Permission denied for operation 'save' on table volume
+```
+
+**解决方案**：
+
+* 检查表权限：`SHOW GRANTS ON TABLE dataset_xxx`
+* 授予相应权限：`GRANT INSERT,UPDATE,DELETE ON TABLE dataset_xxx TO user`
+* 清空权限缓存
+
+**User Volume权限错误**：
+
+```bash
+Error: Permission denied for user volume access
+```
+
+**解决方案**：
+
+* 检查Schema权限：`SHOW GRANTS ON SCHEMA dify TO current_user`
+* 授予Schema权限：`GRANT USAGE,CREATE ON SCHEMA dify TO user`
+* 验证Workspace权限
+
+**External Volume权限错误**：
+
+```bash
+Error: Permission denied for external volume 'enterprise_data'
+```
+
+**解决方案**：
+
+* 检查External Volume权限：`SHOW GRANTS ON EXTERNAL VOLUME enterprise_data`
+* 授予USAGE权限：`GRANT USAGE ON EXTERNAL VOLUME enterprise_data TO user`
+* 验证底层存储连接权限
+
+#### 3. Volume不存在
+
+```bash
+Error: volume not found - quick_start.dify.dataset_xxx
+```
+
+**解决方案**：
+
+* 确认volume存在：`SHOW VOLUMES`
+* 检查表名前缀配置
+* 验证schema和workspace配置
+
+#### 4. 文件操作失败
+
+```bash
+Error: File not found or access denied
+```
+
+**解决方案**：
+
+* 检查文件路径格式
+* 验证权限设置
+* 确认Volume类型配置
+
+**更新日期**：2025-09-03
+**适用版本**：Dify 1.7.2+

package/bin/skills/lakehouse-doc/references/connect-with-cli.md

@@ -0,0 +1,155 @@
+# Clickzetta Lakehouse 命令行客户端使用指南
+
+本文旨在帮助您了解如何安装、配置和使用 Clickzetta Lakehouse 命令行客户端。通过本指南，您将能够顺利连接到 Clickzetta Lakehouse 服务实例，并执行各种 SQL 命令。
+
+## 前提条件
+
+在开始使用客户端之前，请确保满足以下条件：
+
+1. 您的设备已安装 Java 8 或更高版本。
+2. 您已在 Clickzetta 官网注册账户，并创建了 Lakehouse 服务实例。
+3. 您已创建用于连接访问的工作空间。
+4. 使用客户端的用户身份已被添加至工作空间，并被授权访问。
+
+## 安装客户端
+
+Clickzetta Lakehouse 的命令行客户端基于开源 SQL Line 项目进行二次开发。请按照以下步骤安装并配置客户端：
+
+1. 从公网下载或通过Clickzetta工作人员获取客户端安装包[sqlline\_cz.tar.gz](https://autolake-dev-beijing.oss-cn-beijing.aliyuncs.com/clickzetta-tool/release/sqlline_cz.tar.gz)。
+2. 解压安装包文件，您将获得客户端工具的可执行文件和配置文件。
+
+```
+% tar -zxvf sqlline_cz.tar.gz
+x sqlline_cz/
+x sqlline_cz/example.properties
+x sqlline_cz/log4j.properties
+x sqlline_cz/setup.sh
+x sqlline_cz/sqlline
+x sqlline_cz/sqlline-2.13.0-SNAPSHOT-jar-with-dependencies.jar
+```
+
+## 初始化连接环境
+
+1. 进入工作目录：
+
+```
+cd sqlline_cz
+```
+
+2. 初始化连接环境：
+   主要作用是下载最新的 JDBC 驱动包并放到 `sqlline_cz` 目录下。您也可以通过下方链接下载最新的 JDBC 驱动包，并放到 `sqlline_cz` 目录下。
+
+* [下载地址一](https://mvnrepository.com/artifact/com.clickzetta/clickzetta-java)
+* [下载地址二](https://central.sonatype.com/artifact/com.clickzetta/clickzetta-java/versions)
+
+```
+sh setup.sh
+```
+
+## 配置客户端连接
+
+### 方式1：命令行指定连接参数
+
+通过命令行指定连接参数的方式如下：
+
+```
+sh sqlline -d com.clickzetta.client.jdbc.ClickZettaDriver -u "<JDBC URL>" -n <user_name> -p <password>
+```
+
+JDBC URL 格式：
+
+```
+jdbc:clickzetta://<instance_name>.<region_id>.api.clickzetta.com/<workspace_name>?schema=<默认schema名称>&virtualCluster=<计算集群名称>
+```
+
+参数说明：
+
+* `<JDBC URL>`：当前服务实例的 JDBC 连接串，详细格式详见 [JDBC驱动](JDBC-Driver.md)。
+* `<user_name>`：目标工作空间中的空间成员的用户名。
+* `<password>`：目标工作空间中的空间成员的密码。
+* `schema`：指定要连接的 schema，必须填写。
+* `virtualCluster`：使用的计算资源，必须填写。
+
+示例：
+
+```
+sh sqlline -d com.clickzetta.client.jdbc.ClickZettaDriver -u "jdbc:clickzetta://<lakehouse_instance_name>.cn-shanghai-alicloud.api.clickzetta.com/<workspace_name>?schema=<target_schema_name>&vcluster=<your_virtualcluster_name>" -n <user_name> -p <your_password>
+```
+
+### 方式2：命令行指定配置文件
+
+命令行工具提供了配置文件模板。您可以修改该配置文件，然后在命令行中指定该文件以实现服务连接。样例配置文件格式如下：
+
+```
+url=jdbc:clickzetta://<Lakehouse_instance_name>.<region_id>.api.clickzetta.com/<workspace_name>?schema=<schma_name>&virtualCluster=<vcluster_name>
+driver=com.clickzetta.client.jdbc.ClickZettaDriver
+user=<your_user_name>
+password=<your_password>
+```
+
+根据您的服务信息修改模板配置文件并保存后，通过命令参数指定配置文件的方式进行服务连接。
+
+```
+$ sh sqlline properties <配置文件名>
+```
+
+示例：
+
+```
+$ sh sqlline properties test.properties
+sqlline version 1.13.0-SNAPSHOT
+0: jdbc:clickzetta://xxxx.region_id.api.clickzetta.com>show tables;
+```
+
+Clickzetta Lakehouse 命令行工具可一次创建多个不同的服务连接配置文件。在使用过程中，可借助 `!properties` 命令快速切换不同配置文件对应的服务连接。以下以将配置文件从 test.properties 切换为 test.properties.1 为例：
+
+```
+sqlline> !properties test.properties
+Transaction isolation level TRANSACTION_REPEATABLE_READ is not supported. Default (TRANSACTION_READ_COMMITTED) will be used instead.
+0: jdbc:clickzetta://xxxx.region_id.api.clickzetta.com> !properties test.properties.1
+Transaction isolation level TRANSACTION_REPEATABLE_READ is not supported. Default (TRANSACTION_READ_COMMITTED) will be used instead.
+1: jdbc:clickzetta://yyyyy.region_id.api.clickzetta.com> !go 0
+0: jdbc:clickzetta://xxxx.region_id.api.clickzetta.com>
+```
+
+## 运行SQL命令
+
+连接成功后，您可以在命令行客户端执行 Lakehouse SQL 命令。以下是一些SQL命令示例：
+
+切换要使用的 vcluster 和 schema
+
+```
+use vcluster default;
+use schema nyc_taxi_data;
+```
+
+查看当前 schema 中有哪些表
+
+```
+show tables;
+```
+
+![](.topwrite/assets/image_1699879449976.png)
+查询数据
+
+```
+select  * from fhv_trips_staging limit 10;
+```
+
+![](.topwrite/assets/image_1699879794959.png)
+
+## 退出客户端
+
+```
+!quit
+```
+
+## 备注
+
+通过在当前环境中设置以下环境变量，可以打开 debug 模式并输出日志文件，方便问题排查。
+
+```
+export SQLLINE_DEBUG_ENABLE=TRUE
+```
+
+^

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

@@ -0,0 +1 @@
+^

package/bin/skills/lakehouse-doc/references/connection-guide.md

@@ -0,0 +1,61 @@
+# CONNECTION
+
+在Lakehouse中，CONNECTION对象扮演着至关重要的角色。它负责存储第三方服务的身份认证信息和访问管理凭据，从而实现在数据处理过程中保护敏感信息的目的。通过使用CONNECTION，用户无需将身份认证信息以明文形式暴露，从而确保数据的安全性。此外，CONNECTION还支持STS（Security Token Service）认证方式，允许跨账号授权访问Lakehouse以外的服务，进一步提高了数据访问的灵活性和安全性。
+
+## CONNECTION的类型
+
+根据其用途和连接的外部服务类型，CONNECTION对象主要分为以下三种类型：
+
+1. **API Connection**：这种类型的CONNECTION主要用于存储和保护第三方应用服务的身份认证信息。通过API Connection，Lakehouse可以安全地通过API调用来与这些服务进行交互。目前，API Connection支持的外部服务包括阿里云的函数计算FC和腾讯云的云函数服务。API Connection通常与External Function结合使用，以便在Lakehouse中远程调用这些服务。
+2. **Storage Connection**：Storage Connection主要用于存储第三方存储服务的身份认证信息，使得Lakehouse能够安全地访问和管理这些存储服务中的数据。目前支持的外部存储服务包括阿里云的对象存储OSS、腾讯云COS和AWS S3。
+3. **Catalog Connection**：在数据湖架构中，Catalog Connection 是一种关键组件，用于将数据湖与外部的元数据存储（例如 Hive Metastore）关联起来。通过创建 Catalog Connection，用户可以实现元数据的统一管理和访问，从而直接读取存储在外部系统中的数据。Lakehouse目前只支持连接Hive。
+
+## 创建和管理CONNECTION
+
+为了使用CONNECTION，用户需要了解如何创建、列出、查看详情以及删除CONNECTION。以下是这些操作的基本语法和使用示例：
+
+* **创建CONNECTION**：用户可以通过特定的创建语法来定义一个新的CONNECTION对象，其中需要指定CONNECTION的类型、名称以及相关的认证信息和参数。
+  例如，创建一个API Connection的语法如下：
+
+  ```sql
+  CREATE API CONNECTION conn_aliyun_java 
+    type cloud_function
+    provider = 'xxx'
+    region = 'xxx'
+    role_arn = 'acs:ram::13843xxxxxxxxxxxxx:role/czudfrole'
+    namespace = 'xxx'
+    code_bucket = 'xxx';
+  ```
+
+  创建一个Storage Connection的语法如下：
+
+  ```SQL
+  CREATE STORAGE CONNECTION [IF NOT EXISTS] connection_name 
+    TYPE COS
+    REGION = 'xxx'
+    APP_ID = 'xxx'
+    ACCESS_KEY='******'
+    SECRET_KEY='******';
+  ```
+
+  具体的语法和步骤可以参考[创建CONNECTION](CREATECONNECTION.md)文档。
+
+* **列出所有的CONNECTION**：用户可以使用列出语法来查看当前Lakehouse工作空间中所有的CONNECTION对象。例如，查看当前CONNECTION的命令如下：
+  ```sql
+  SHOW CONNECTIONS;
+  ```
+  这有助于用户管理和选择已有的CONNECTION进行操作。相关的命令和选项可以在[列出所有的CONNECTION](SHOWCONNECTIONS.md)文档中找到。
+
+* **查看CONNECTION详情**：为了更好地理解和管理CONNECTION，用户可能需要查看特定CONNECTION的详细信息。这包括认证信息、配置参数等。例如，查看一个API Connection详情的语法如下：
+  ```sql
+  DESCRIBE CONNECTION my_api_conn;
+  ```
+  查看详情的语法和方法在[查看CONNECTION详情](DESCCONNECTION.md)文档中有详细说明。
+
+* **删除CONNECTION**：当某个CONNECTION不再需要时，用户可以通过删除语法来移除它。例如，删除一个CONNECTION的命令如下：
+  ```sql
+  DROP CONNECTION my_api_conn;
+  ```
+  这有助于保持工作空间的整洁，并防止不必要的安全风险。具体的删除步骤和注意事项在[删除CONNECTION](DROPCONNECTION.md)文档中有所描述。
+
+^