@clickzetta/cz-cli-darwin-x64 0.3.1

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

@@ -0,0 +1,104 @@
+# 云器Insight：可视化数据分析平台
+
+> 【预览发布】本功能当前处于受邀预览发布阶段。如果需要使用，请联系我们的技术支持同学协助处理。
+
+## 1. 云器Insight产品概述
+
+云器Insight是一款功能强大的可视化数据分析工具，专为数据集成和数据开发后的数据分析和可视化展示而设计。通过使用Insight，用户可以轻松创建数据报表和分析看板，从而更加直观地理解数据，支持业务决策。以下是Insight的主要使用场景：
+
+* **创建日常数据报表**：快速搭建日常业务所需的数据报表，减少传统数据门户搭建的复杂性，让数据开发者专注于底层数据开发，而业务分析师则可以基于数据集构建各类业务分析报表。
+* **自助分析**：业务人员可以直接使用数据开发者准备好的数据集，通过简单的拖拉拽操作进行自助分析，提高数据分析的效率，避免因排期问题导致无法及时查看数据。
+
+## 2. 用户操作指南
+
+在使用云器Insight前，请确保您已拥有云器账户。以下是详细的操作步骤：
+
+### 2.1 云器用户管理
+
+* **登录系统管理台**：使用您的云器账号登录系统管理台。
+* **进入Insight**：在管理台上找到并点击Insight，进入产品内部。
+
+### 2.2 云器Insight平台操作
+
+#### 2.2.1 创建数据连接
+
+* **新建数据链接**：在数据连接页面，点击「新建数据链接」按钮。
+  ![](.topwrite/assets/image_1732698495607.png =604)
+
+* **选择数据源类型**：\* 选择Cloud下的云器Lakehouse数据源
+  ![](.topwrite/assets/image_1732698470951.png =606)
+
+* **填写JDBC信息**：输入必要的JDBC链接信息，如数据库URL、用户名和密码等。
+  ![](.topwrite/assets/image_1732698542969.png =514)
+
+* 名称：必填，作为数据连接的管理名称
+
+* service：不用填写。
+
+* username：必填，云器平台的用户名
+
+* 密码：必填，连接云器平台的密码
+
+* schema：非必填，云器账户下指定工作空间下的具体的schema。注意该数据库必须与JDBC串中的schema一致
+
+* 数据网关：无
+
+* URL：jdbc\:clickzetta://「instance_name.<region\_id>.api.clickzetta.com/「该账户下的工作空间」?schema=具体schema\&virtualCluster=「当前空间下的集群名称」
+
+* vcluster：可不填
+
+* instance：可不填
+
+* worspace：URL中的工作空间
+
+#### 2.2.2 创建数据集
+
+* **新建数据包**：在数据集市页面，点击「新建数据包」并选择「空白数据包」。
+* **新建数据集**：在数据包内点击「新建数据集」按钮。
+* **选择数据源**：选择刚才创建的数据源类型和具体的数据表。
+
+  ![](.topwrite/assets/066f996216/a3111473bfd4f6f8f2d75a69f4b05826a0841765.png =728)
+
+  ![](.topwrite/assets/066f996216/06fe9023d84c405e53fa72450406fa6acb512406.png =720)
+
+  ![](.topwrite/assets/066f996216/a6704632ba99a0b514ea39e18d612f9ff52c9c18.png =630)
+
+  ![](.topwrite/assets/066f996216/0c4db444079dcb819274c8653e196916c563bd3b.png =313)
+
+#### 2.2.3 创建BI报表
+
+* **新建分析应用**：在应用创作页面，点击「新建分析应用」。
+* **创建仪表盘**：点击「新建仪表盘」，进入仪表盘搭建页面。
+* **发布看板**：创建完成后，点击「发布」，将看板发布至应用集市。
+
+  ![](.topwrite/assets/066f996216/026bda059ee55d9f2051ee2d8d741e97f2dedad9.png)
+
+  ![](.topwrite/assets/066f996216/f6e1e90b6e5cf13e5850ff7697ce7542696881af.png)
+
+  ![](.topwrite/assets/066f996216/9a6fe91f1cba92fb62adb1bbe0adcf17a0b05342.png =190)
+
+#### 2.2.4 查看报表
+
+* **查看数据**：在应用集市页面，点击相应的报表查看数据。
+  ![](.topwrite/assets/066f996216/86219be367b3bb5667f7cf46875c1e7956337a14.png =361)
+
+## 3. 使用示例
+
+以下是一些使用Insight的具体示例：
+
+* **销售分析**：创建一个包含销售额、销售量和销售增长率的月度销售报表，用于分析各产品线的销售情况。
+* **客户行为分析**：构建一个展示客户访问量、停留时间和转化率的看板，以便分析不同营销活动的效果。
+* **库存管理**：搭建一个实时更新的库存报表，包括库存数量、库存周转率和安全库存水平，帮助管理人员及时了解库存状况。
+
+## 4. 常见问题解答（FAQ）
+
+1. 为什么我看不到数据集市、应用集市等功能？
+   如果您无法看到数据集市、应用集市等功能，请确认您的用户角色是否具备相应权限。如有需要，请联系系统管理员开通。
+
+2. 为什么我有数据分析权限但是创建不了数据集？
+   如果您有数据分析权限但无法创建数据集，请确保您已在数据包下进行操作。只有系统管理员有权限创建数据包。
+
+3. 如何添加Insight产品的使用用户？
+   如需添加Insight产品的使用用户，请在云器管理台上进行操作。请注意，数据同步可能会有延迟。
+
+^

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

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

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

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

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

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

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

@@ -0,0 +1,228 @@
+# (SaaS)² ：云器Lakehouse+Zilliz，Make Data Ready for BI and AI
+## 方案简介
+
+   * (SaaS)²：云器 Lakehouse 和 Zilliz 都提供了基于主流云服务的 SaaS 模式服务。通过 SaaS 服务的组合，最大程度从全托管和按量付费的 SaaS 模式中获益。
+
+   * Make Data Ready for BI and AI：云器 Lakehouse 的数据仓库专注于面向 BI 应用提供标量数据的存储、处理和分析；Zilliz 向量数据库专注于面向 AI 的增强数据分析。通过云器 Lakehouse 和 Zilliz 向量数据库的集成，提供完整的生产级别的 BI+AI 解决方案，解决 BI、AI 不对称的问题：
+
+     * BI 数据和 AI 数据新鲜度不对称：Zilliz Vector Data Pipeline 提供批量数据 Embedding 服务，与非批量相比，Embedding 时间缩短 10 倍以上，大幅提升 AI 数据的新鲜度。
+     * BI 数据和 AI 数据规模不对称：Zilliz 在百亿级向量数据级别时仍能提供稳定的快速响应和并发性，向量数据不再是一个补充性的“小众”数据，实现 BI 数据和 AI 数据在规模上的并驾齐驱。
+
+   * 业务升级：以最简单的方案将传统的数据分析升级到增强分析，实现 BI+AI 的融合。
+
+
+## 方案组成
+
+   ![](.topwrite/assets/image_1734076588760.png)
+
+   * 云器 Lakehouse 平台：提供数据湖和数据仓库的管理，包括数据管理、数据集成、任务开发、任务执行、工作流（workflow）编排、任务监控与运维等。
+   * 云器 Zettapark：通过 Python + DataFrame 的编程方式，实现 CSV 文件的加载。
+   * Zilliz 向量数据库：性能出色、性价比高的向量数据库。
+   * Zilliz Data Pipeline：对文本、图片、文件等数据进行向量化存储和检索，支持中英文 Embedding 模型、Rerank 模型，提供极致简化和开发者友好的向量处理方式。
+
+## 应用场景示例：通过语义检索增强文本搜索
+
+   * 标量检索：云器 Lakehouse 提供基于文本的 LIKE 模糊匹配、基于文本倒排索引的关键字搜索。
+   * 向量检索：Zilliz 提供基于向量数据的语义检索和 Rerank 模型的结果精排。
+
+将标量检索和向量检索结合，提高检索的性能与准确性，适用于产品搜索、产品推荐等场景。
+
+### 任务一：加载原始数据到云器Lakehouse
+
+云器 Lakehouse 提供多种加载 CSV 数据的方式，包括 Web 方式的离线数据同步、通过数据湖加载 CSV 等。本文采用云器 Zettapark 方式实现数据加载，Python 代码运行在云器 Lakehouse 的 Python 任务节点中。
+
+![](.topwrite/assets/image_1734329566767.png)
+
+代码如下：
+
+```Python
+# ********************************************************************#
+# author: qiliang
+# create time: 2024-09-14 10:10:26
+# ********************************************************************#
+from clickzetta.zettapark.session import Session
+hints = dict()
+hints['sdk.job.timeout'] = 3
+hints['query_tag'] = 'test_conn_hints_zettapark'
+connection_parameters = {
+  "username": "qiliang",
+  "password": "",
+  "service": "<region\_id>.api.clickzetta.com",
+  "instance": "",
+  "workspace": "ql_ws",
+  "schema": "wayfair_wans",
+  "vcluster": "default",
+  "sdk_job_timeout": 10,
+  "hints": hints,
+}
+session = Session.builder.configs(connection_parameters).create()
+import os
+import pandas as pd
+import warnings
+
+# 忽略 FutureWarning
+warnings.filterwarnings("ignore", category=FutureWarning)
+# 文件 URL 数组
+urls = [
+    'https://raw.githubusercontent.com/wayfair/WANDS/main/dataset/label.csv',
+    'https://raw.githubusercontent.com/wayfair/WANDS/main/dataset/product.csv',
+    'https://raw.githubusercontent.com/wayfair/WANDS/main/dataset/query.csv'
+]
+for url in urls:
+    # 提取文件名并去掉扩展名
+    table_name = os.path.basename(url).split('.')[0]
+    data = pd.read_csv(url, delimiter='\t')  # Specify the delimiter as tab
+    # Replace spaces in column names with underscores and convert to lowercase
+    data.columns = [col.replace(" ", "_").lower() for col in data.columns]
+    # Check if the table exists
+    try:
+        session.table(table_name)
+        table_exists = True
+    except Exception:
+        table_exists = False
+    # Create the table if it doesn't exist
+    if not table_exists:
+        column_definitions = ", ".join([f"{col} STRING" for col in data.columns])
+        session.sql(f"CREATE TABLE {table_name} ({column_definitions})")
+    df = session.create_dataframe(data)
+    df.write.save_as_table(table_name, mode="overwrite", table_type="transient")
+    print(f"Data from {filepath} written to table {table_name}")
+
+ # Drop tables starting with 'zettapark_temp_table_'
+try:
+    tables = session.sql("SHOW TABLES LIKE 'zettapark_temp_table_%'").collect()
+    
+    for table in tables:
+        table_name = table['table_name']
+        session.sql(f"DROP TABLE IF EXISTS {table_name}").collect()
+        print(f"temp Table {table_name} dropped")
+except Exception as e:
+    print(f"Error dropping temp tables: {e}")
+
+# Close the session
+session.close()   
+```
+
+然后在云器 Lakehouse 控制台检查结果：
+
+![](.topwrite/assets/image_1734329595733.png)
+
+![](.topwrite/assets/image_1734329604994.png)
+
+### 任务二：开发 SQL 任务，为 BI 准备数据
+
+![](.topwrite/assets/image_1734329614774.png)
+
+代码如下：
+
+```SQL
+--LAKEHOUSE SQL
+--********************************************************************--
+-- author: qiliang
+-- create time: 2024-09-12 15:17:34
+--********************************************************************--
+-- DROP TABLE if exists product_cleaned;
+CREATE TABLE if not exists product_cleaned(
+  `product_id` bigint,
+  `product_name` string,
+  `product_class` string,
+  `category_hierarchy` string,
+  `product_description` string,
+  `product_features` string,
+  `rating_count` double,
+  `average_rating` double,
+  `review_count` double,
+  `product_text` string,
+  `product_full_text` string,
+  `product_features_json` json,
+   index inverted_index_product_text (product_text) using inverted,
+   index inverted_index_product_full_text (product_full_text) using inverted,
+);
+INSERT OVERWRITE product_cleaned
+SELECT 
+       *,
+       COALESCE(product_description, product_name) as product_text,
+       CONCAT(
+        COALESCE(product_name, ''), ';',
+        COALESCE(product_description, ''), ';',
+        COALESCE(product_class, ''), ';',
+        COALESCE(category_hierarchy, ''), ';',
+        COALESCE(product_features, '')
+       ) as product_full_text,
+       JSON_PARSE(
+       to_json(
+           map_from_entries(
+               transform(
+                   split(product_features, '\\|'),
+                   entry -> struct(
+                       trim(split(entry, ':')[0]),
+                       trim(split(entry, ':')[1])
+                   )
+               )
+           )
+       ) AS product_features_json,
+FROM product);
+```
+
+### 任务三：创建 Zilliz Data Ingestion Pipeline
+
+Zilliz Cloud Pipelines 能够简化将非结构化数据转换为 Embedding 向量的流程，并对接 Zilliz Cloud 向量数据库存储向量数据，实现高效的向量索引和检索。开发人员在处理非结构化数据时，时常面临复杂的非结构化数据转换和检索问题，这会降低开发速度。Zilliz Cloud Pipelines 通过提供一体化解决方案来应对这一挑战，帮助开发人员轻松将非结构化数据转换为可搜索的向量，并确保在对接 Zilliz Cloud 向量数据库后能进行高质量的向量检索。
+
+![](.topwrite/assets/image_1734329641231.png)
+
+获取新创建的 Pipeline 的客户端代码，作为下一步代码的输入：
+
+![](.topwrite/assets/image_1734329668097.png)
+
+### 任务四：开发Python任务在工作流里调用Zilliz Data Ingestion Pipeline API，为AI增强分析准备数据，实现向量数据的ETL自动化。
+
+将云器 Lakehouse 中表名为 product 的文本信息发送到 Zilliz，对文本数据先进行 Embedding，然后进行向量化存储。
+
+![](.topwrite/assets/image_1734329678061.png)
+
+在云器 Lakehouse 中执行完上述代码后，到 Zilliz 控制台查看，验证向量化结果：
+
+![](.topwrite/assets/image_1734329685817.png)
+
+![](.topwrite/assets/image_1734329699172.png)
+
+### 任务五：通过云器Lakehouse工作流编排定义完整的数据流程
+
+分别给上述任务设置调度属性并提交，构建数据工作流：
+
+![](.topwrite/assets/image_1734329789735.png)
+
+### 任务六：创建 Zilliz Data Search Pipeline
+
+使用 Zilliz Data Search Pipeline 能够快速高效地将查询文本转换为 Embedding 向量，返回最相关的 top-K 个文档块（包括文本和元数据），从而有效地从搜索结果中获取数据洞察。
+
+![](.topwrite/assets/image_1734329806523.png)
+
+### 任务七：通过 Zilliz API 进行数据分析
+
+```SQL
+import http.client
+import json
+conn = http.client.HTTPSConnection("controller.api.gcp-us-west1.zillizcloud.com")
+headers = {
+    'Authorization': "Bearer ******",
+    'Accept': "application/json",
+    'Content-Type': "application/json"
+}
+search_without_rerank_payload = "{\"data\":{\"query_text\":\"black 5 drawer dresser by guilford\"},\"params\":{\"limit\":20,\"offset\":0,\"outputFields\":[],\"filter\":\"id >= 0\"}}"
+
+conn.request("POST", "/v1/pipelines/pipe-e46ae76b70773f85543c93/run", search_without_rerank_payload, headers)
+
+res = conn.getresponse()
+data = res.read()
+
+# Decode the response data
+decoded_data = data.decode("utf-8")
+
+# Parse the JSON data
+parsed_data = json.loads(decoded_data)
+
+# Pretty-print the JSON data
+pretty_json = json.dumps(parsed_data, ensure_ascii=False, indent=4)
+print(pretty_json)
+```

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

@@ -0,0 +1,244 @@
+# 安装与配置
+
+本指南将帮助您快速安装和配置 LangChain-ClickZetta 集成。
+
+## 📦 安装
+
+### 使用 pip 安装（推荐）
+
+```bash
+pip install langchain-clickzetta
+```
+
+### 开发安装
+
+如果您想从源码安装或参与开发：
+
+```bash
+git clone https://github.com/yunqiqiliang/langchain-clickzetta.git
+cd langchain-clickzetta/libs/clickzetta
+pip install -e ".[dev]"
+```
+
+## 🔧 依赖要求
+
+### Python 版本
+- Python 3.9 或更高版本
+
+### 核心依赖
+安装包时会自动安装以下依赖：
+
+```
+langchain-core>=0.1.0
+clickzetta-connector-python>=0.8.92
+clickzetta-zettapark-python>=0.1.3
+sqlalchemy>=2.0.0
+numpy>=1.20.0
+pydantic>=2.0.0
+typing-extensions>=4.0.0
+```
+
+### 可选依赖
+
+#### 中文AI优化（推荐）
+```bash
+pip install dashscope  # 阿里云灵积平台
+```
+
+#### 开发工具
+```bash
+pip install langchain-clickzetta[dev]
+```
+
+包含 pytest、ruff、black、mypy 等开发工具。
+
+## 🏗️ ClickZetta 环境配置
+
+### 获取 ClickZetta 访问权限
+
+1. **注册云器科技账号**
+   - 访问 [云器科技官网](https://www.yunqi.tech/)
+   - 注册并申请 ClickZetta 试用
+
+2. **获取连接信息**
+   您需要以下 7 个连接参数：
+   - `service` - 服务地址
+   - `instance` - 实例名称
+   - `workspace` - 工作空间
+   - `schema` - 模式名称
+   - `username` - 用户名
+   - `password` - 密码
+   - `vcluster` - 虚拟集群名称
+
+### 环境变量配置
+
+创建 `.env` 文件或设置环境变量：
+
+```bash
+# ClickZetta 连接配置
+export CLICKZETTA_SERVICE="your-service"
+export CLICKZETTA_INSTANCE="your-instance"
+export CLICKZETTA_WORKSPACE="your-workspace"
+export CLICKZETTA_SCHEMA="your-schema"
+export CLICKZETTA_USERNAME="your-username"
+export CLICKZETTA_PASSWORD="your-password"
+export CLICKZETTA_VCLUSTER="your-vcluster"
+
+# 可选：灵积DashScope配置（推荐用于中文AI）
+export DASHSCOPE_API_KEY="your-dashscope-api-key"
+```
+
+### 连接配置文件
+
+您也可以使用配置文件，创建 `~/.clickzetta/connections.json`：
+
+```json
+{
+  "default": {
+    "service": "your-service",
+    "instance": "your-instance",
+    "workspace": "your-workspace",
+    "schema": "your-schema",
+    "username": "your-username",
+    "password": "your-password",
+    "vcluster": "your-vcluster"
+  },
+  "uat": {
+    "service": "uat-service",
+    "instance": "uat-instance",
+    "workspace": "test",
+    "schema": "test_schema",
+    "username": "test-user",
+    "password": "test-password",
+    "vcluster": "test-cluster"
+  }
+}
+```
+
+## 🧪 验证安装
+
+### 基本导入测试
+
+```python
+# 测试基本导入
+try:
+    from langchain_clickzetta import ClickZettaEngine
+    print("✅ LangChain ClickZetta 导入成功")
+except ImportError as e:
+    print(f"❌ 导入失败: {e}")
+```
+
+### 连接测试
+
+```python
+from langchain_clickzetta import ClickZettaEngine
+
+# 创建引擎实例
+engine = ClickZettaEngine(
+    service="your-service",
+    instance="your-instance",
+    workspace="your-workspace",
+    schema="your-schema",
+    username="your-username",
+    password="your-password",
+    vcluster="your-vcluster"
+)
+
+# 测试连接
+try:
+    results, columns = engine.execute_query("SELECT 1 as test")
+    print("✅ ClickZetta 连接成功")
+    print(f"测试结果: {results}")
+except Exception as e:
+    print(f"❌ 连接失败: {e}")
+```
+
+### 完整功能测试
+
+```python
+from langchain_clickzetta import (
+    ClickZettaEngine,
+    ClickZettaVectorStore,
+    ClickZettaStore
+)
+from langchain_community.embeddings import DashScopeEmbeddings
+
+# 初始化组件
+engine = ClickZettaEngine(
+    # ... 你的连接参数
+)
+
+# 测试向量存储
+try:
+    embeddings = DashScopeEmbeddings(
+        dashscope_api_key="your-api-key",
+        model="text-embedding-v4"
+    )
+
+    vector_store = ClickZettaVectorStore(
+        engine=engine,
+        embedding=embeddings,
+        table_name="test_vectors"
+    )
+    print("✅ 向量存储初始化成功")
+except Exception as e:
+    print(f"⚠️  向量存储初始化失败: {e}")
+
+# 测试键值存储
+try:
+    store = ClickZettaStore(engine=engine, table_name="test_store")
+    print("✅ 键值存储初始化成功")
+except Exception as e:
+    print(f"❌ 键值存储初始化失败: {e}")
+```
+
+## ⚠️ 常见问题
+
+### 连接问题
+
+**问题**: `连接超时`
+```
+解决方案:
+1. 检查网络连接
+2. 确认ClickZetta服务地址正确
+3. 增加connection_timeout参数
+```
+
+**问题**: `认证失败`
+```
+解决方案:
+1. 确认用户名密码正确
+2. 检查用户权限
+3. 确认vcluster参数正确
+```
+
+### 依赖问题
+
+**问题**: `ModuleNotFoundError: No module named 'clickzetta'`
+```
+解决方案:
+pip install clickzetta-connector-python
+```
+
+**问题**: `版本冲突`
+```
+解决方案:
+pip install --upgrade langchain-clickzetta
+```
+
+### 权限问题
+
+**问题**: `权限不足，无法创建表`
+```
+解决方案:
+1. 联系管理员授予CREATE TABLE权限
+2. 使用现有表名
+3. 确认workspace和schema权限
+```
+
+## 💡 提示
+
+- 建议在生产环境使用连接池
+- 定期更新到最新版本
+- 使用环境变量管理敏感信息
+- 开启日志记录以便调试