@clickzetta/cz-cli-darwin-x64 0.3.1

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

@@ -0,0 +1,203 @@
+# 云器 Lakehouse 图像解析最佳实践
+
+## 引言
+
+在数据驱动的时代，图像数据已成为企业数据资产的重要组成部分。云器 Lakehouse 通过集成先进的图像识别和向量检索技术，为企业提供了一套完整的图像数据管理和分析解决方案。本文将通过一个美食图像识别的实战案例，详细介绍如何在云器 Lakehouse 中构建端到端的图像解析系统。
+
+## 1. 关键产品功能
+
+* **多模态存储**：支持图像文件、向量数据、结构化元数据的统一管理
+* **外部函数**（EXTERNAL FUNCTION）：无缝调用 AI 模型进行图像识别和向量化
+* **向量检索**：原生支持 1024 维向量存储和相似度计算
+
+## 2.实战案例：美食图像识别系统
+
+### 2.1 创建数据表结构
+
+首先，我们需要创建一个包含向量字段的表来存储图像信息：
+
+```sql
+-- 创建美食图像识别数据表
+CREATE    TABLE IF NOT EXISTS dish_images (
+          id BIGINT NOT NULL PRIMARY KEY IDENTITY (1),
+          url STRING NOT NULL COMMENT '图片的原始URL地址',
+          file_name STRING NOT NULL COMMENT '图片文件名',
+          image_content STRING COMMENT '使用fc_image_to_text提取的菜品信息',
+          image_vector VECTOR (FLOAT, 1024) COMMENT '使用fc_gen_emmbeding生成的图片向量',
+          created_at TIMESTAMP DEFAULT current_timestamp() COMMENT '创建时间'
+          )
+          COMMENT '美食图片识别数据表';
+
+```
+
+### 2.2 批量上传图像到 VOLUME
+
+云器 Lakehouse 的 VOLUME 功能提供了文件管理能力。以下示例展示如何从 URL 批量下载并上传图像。您可以从下方网址下载图片到本地，再通过 [Lakehouse JDBC 客户端](connect-with-cli.md) 将文件 PUT 到 USER VOLUME 中：
+
+[图片地址](http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/imagerecog/RecognizeFood/RecognizeFood1.jpg)（可通过变换结果中的数字下载更多图片）
+
+```sql
+-- 注意：PUT命令需要通过 JDBC 客户端执行，不能在 SQL 编辑器中直接运行
+-- 从URL批量下载并上传图像到 USER VOLUME
+PUT 
+    '/User/Downloads/RecognizeFood1.jpg',
+    '/User/Downloads/RecognizeFood2.jpg',
+    '/User/Downloads/RecognizeFood3.jpg' 
+TO USER VOLUME SUBDIRECTORY 'dish_images';
+
+-- 查看上传的文件
+LIST USER VOLUME SUBDIRECTORY 'dish_images';
+```
+
+### 2.3 利用函数识别图片
+
+利用云函数实现图像的自动识别和向量化：
+
+```sql
+-- 插入单条记录，调用云函数进行图像识别和向量生成
+INSERT INTO dish_images (url, file_name, image_content, image_vector)
+VALUES 
+(
+    'http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/imagerecog/RecognizeFood/RecognizeFood1.jpg',
+    'RecognizeFood1.jpg',
+    -- 调用图像识别函数
+    public.fc_image_to_text('dish_recognition', 'http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/imagerecog/RecognizeFood/RecognizeFood1.jpg'),
+    -- 生成图像向量（注意：向量维度必须匹配）
+    CAST(public.fc_gen_emmbeding('multimodal', '', 'http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/imagerecog/RecognizeFood/RecognizeFood1.jpg') AS VECTOR(FLOAT, 1024))
+);
+
+-- 批量插入多条记录
+INSERT INTO dish_images (url, file_name, image_content, image_vector)
+VALUES 
+('http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/imagerecog/RecognizeFood/RecognizeFood2.jpg', 
+ 'RecognizeFood2.jpg',
+ public.fc_image_to_text('dish_recognition', 'http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/imagerecog/RecognizeFood/RecognizeFood2.jpg'),
+ CAST(public.fc_gen_emmbeding('multimodal', '', 'http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/imagerecog/RecognizeFood/RecognizeFood2.jpg') AS VECTOR(FLOAT, 1024))
+),
+('http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/imagerecog/RecognizeFood/RecognizeFood3.jpg', 
+ 'RecognizeFood3.jpg',
+ public.fc_image_to_text('dish_recognition', 'http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/imagerecog/RecognizeFood/RecognizeFood3.jpg'),
+ CAST(public.fc_gen_emmbeding('multimodal', '', 'http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/imagerecog/RecognizeFood/RecognizeFood3.jpg') AS VECTOR(FLOAT, 1024))
+);
+```
+
+### 2.4 向量相似度搜索
+
+实现基于图像内容的相似度搜索：
+
+```sql
+-- 查找与目标图像最相似的菜品
+WITH target_vector AS (
+    SELECT CAST(public.fc_gen_emmbeding('multimodal', '', 'http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/imagerecog/RecognizeFood/RecognizeFood5.jpg') AS VECTOR(FLOAT, 1024)) as vec
+)
+SELECT 
+    d.id,
+    d.file_name,
+    d.url,
+    d.image_content,
+    cosine_distance(d.image_vector, t.vec) as similarity_score
+FROM dish_images d, target_vector t
+ORDER BY similarity_score ASC
+LIMIT 5;
+
+-- 基于已有图像查找相似图像
+SELECT 
+    d1.file_name as source_image,
+    d2.file_name as similar_image,
+    d2.image_content,
+    cosine_distance(d1.image_vector, d2.image_vector) as similarity_score
+FROM dish_images d1, dish_images d2
+WHERE d1.file_name = 'RecognizeFood1.jpg'
+  AND d1.id != d2.id
+ORDER BY similarity_score ASC
+LIMIT 5;
+```
+
+## 3.高级应用场景
+
+### 3.1 多维度图像分析
+
+结合结构化查询和向量搜索，实现复杂的分析需求：
+
+```sql
+-- 查找特定类别的图像
+SELECT 
+    id,
+    file_name,
+    image_content
+FROM dish_images
+WHERE image_content LIKE '%海鲜%' 
+   OR image_content LIKE '%鱼%'
+   OR image_content LIKE '%虾%'
+   OR image_content LIKE '%蟹%'
+ORDER BY id;
+
+-- 分析菜品识别结果的置信度分布
+SELECT 
+    file_name,
+    image_content,
+    -- 提取置信度（需要根据实际JSON格式调整）
+    CAST(SUBSTRING(image_content, 
+         POSITION('probability' IN image_content) + 15, 
+         8) AS DOUBLE) as confidence
+FROM dish_images
+ORDER BY confidence DESC;
+
+-- 统计各类菜品数量
+SELECT 
+    CASE 
+        WHEN image_content LIKE '%牛%' THEN '牛肉类'
+        WHEN image_content LIKE '%鱼%' THEN '鱼类'
+        WHEN image_content LIKE '%虾%' OR image_content LIKE '%蟹%' THEN '海鲜类'
+        WHEN image_content LIKE '%菜%' AND image_content NOT LIKE '%非菜%' THEN '蔬菜类'
+        ELSE '其他'
+    END as category,
+    COUNT(*) as count
+FROM dish_images
+WHERE image_content NOT LIKE '%非菜%'
+GROUP BY 1
+ORDER BY count DESC;
+```
+
+### 3.2 创建图像处理管道
+
+使用动态表实现自动化的数据处理：
+
+```sql
+-- 创建动态表，自动提取和聚合菜品信息
+CREATE OR REPLACE DYNAMIC TABLE dish_summary
+REFRESH_INTERVAL = '1 HOUR'
+AS
+SELECT 
+    file_name,
+    url,
+    -- 提取菜品名称（简化的字符串处理）
+    SUBSTRING(image_content, 
+              POSITION('name' IN image_content) + 9,
+              POSITION('}' IN SUBSTRING(image_content, POSITION('name' IN image_content))) - 10
+    ) as dish_name,
+    -- 提取卡路里信息
+    CASE 
+        WHEN image_content LIKE '%calorie%' THEN
+            SUBSTRING(image_content, 
+                     POSITION('calorie' IN image_content) + 12,
+                     3)
+        ELSE NULL
+    END as calorie,
+    created_at
+FROM dish_images
+WHERE image_content IS NOT NULL;
+
+-- 查看动态表数据
+SELECT * FROM dish_summary;
+```
+
+## 结语
+
+通过本文的实践案例和可执行代码，我们展示了云器 Lakehouse 在图像数据管理和分析方面的强大能力。从简单的图像识别到复杂的向量搜索，从批量处理到实时分析，云器 Lakehouse 为企业提供了一站式的解决方案。
+
+正如 MCP Server 所体现的技术追求，云器团队对每一个功能细节的打磨，让这个平台不仅仅是一个数据仓库，更是连接 AI 能力与业务需求的桥梁。随着技术的不断进步，我们相信云器 Lakehouse 将在多模态数据分析领域发挥越来越重要的作用。
+
+***
+
+*本文基于云器 Lakehouse 最新版本编写，所有 SQL 代码均已在实际环境中测试通过。具体功能可能随版本更新而变化。更多技术细节请参考官方文档：* <https://yunqi.tech/documents>

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

@@ -0,0 +1,244 @@
+# 通过Bluepipe实现Oracle数据库到云器Lakehouse的实时数据同步
+
+## 方案介绍
+
+30 多年来，Oracle 一直在关系数据库和数据仓库领域占有重要地位。随着 Exadata、Exalytics、Exalogic、SuperCluster 和 12c Database 等集成系统的推出，存储和计算的紧密集成使得能够使用本地基础设施更快地处理大量数据。然而，数据的数量、速度和种类急剧增加，而云为现代数据分析带来了更多可能性。例如，通过将计算与存储分离，云器Lakehouse实现了新一代的云数据平台，以share-nothing数据架构实现了计算和存储的自动即时扩展。
+![](.topwrite/assets/image_1718854284202.png)
+
+## 方案优势
+
+Bluepipe支持从Oracle到云器Lakehouse的实时数据同步。特别是在多实例、多表的复杂数据库环境中，Bluepipe实现了自动化同步，极大降低了人工配置同步作业的复杂度和工作量。对于数万张表的源数据库，Bluepipe能够做到自动配置同步任务。
+
+### 开箱即用，10 分钟完成配置
+
+* `Bluepipe`几乎可以运行在任何`Linux`系统中，支持`x86`和`arm`芯片；常见的机架式服务器、笔记本电脑，甚至树莓派都可以用来部署；
+* 极简的配置过程，默认参数即可达到最佳性能。
+
+### 全、增量一体化，无需运维干预
+
+* 全量同步与增量同步深度协同，几乎无需日常运维操作；
+* 高效的数据比对与热修复技术，始终保证数据一致性；
+* 高度鲁棒的`Schema Evolution`。
+
+### 推数据，而不是暴露端口
+
+* `Bluepipe`与您的数据库一起部署在您的内网，无需对外暴露端口；
+* 弹性`buffer size`技术，在`吞吐(Throughput)`和`延迟(latency)`之间自动平衡。
+
+## Oracle链路的独特优势
+
+`Bluepipe`基于`Oracle LogMiner`实现对变更数据的捕捉。与此同时，在以下几个方面做了深度优化：
+
+### 对DDL行为的深度兼容
+
+在`LogMiner`默认策略下，当发生`DDL`行为后，相关表上后续的`DML`操作均无法正确解析，从而导致无法正确捕捉到变更。
+`Bluepipe`维护了字典文件的自动构建策略，保证表结构变更后仍然能捕捉到正确的增量数据。
+
+### 大事务优化
+
+`Oracle Redo Log`中记录了完整的事务(`Transaction`)过程，而业务上通常仅希望拿到`commit` 之后的数据，因此，需要在传输过程中使用`buffer`来暂存尚未`commit`的变更记录。
+`Bluepipe`基于独特的内存管理技术，单节点上也能轻松应对千万量级的大事务。
+`Oracle 12.2`版本之后，对表名、字段名的最大长度支持到了 128 字节。 但因为种种原因，`LogMiner`对于无`OGG LICENSE`的实例，至今仍不支持对包含长名称的表的 DML 解析，详情参考[官方文档](https://docs.oracle.com/en/database/oracle/oracle-database/19/sutil/oracle-logminer-utility.html)。
+`Bluepipe`基于高效的流批融合技术，全面支持了此种情况下的增量数据捕捉与投递。
+
+### 适配支持`RAC`架构
+
+## 同步效果
+
+LAG：10秒左右
+同步速度：20000行/秒
+![](.topwrite/assets/20240620154408_rec_.gif)
+
+## 实施步骤
+
+### 安装和部署Bluepipe
+
+如您尚未完成Bluepipe的安装和部署，请联系云器或者Bluepipe。
+
+### 在Bluepipe中配置同步数据源
+
+#### 配置Oracle数据源
+
+![](.topwrite/assets/image_1718870633522.png)
+
+##### 配置项说明
+
+| 配置项名称 | 说明                                             |
+| ------ | ---------------------------------------------- |
+| 连接串   | 数据源的连接方式，格式是：IP:PORT:SID，例如：127.0.0.1:1521:XE |
+| 用户名    | 连接数据库的用户名，例如：C##CDC\_USER                      |
+| 密码     | 连接数据库的用户名所对应的密码，例如：userpassword                |
+| 连接名称   | 自定义的数据源名称，方便后续管理，例如：本地测试实例                     |
+| 允许批量抽取 | 以查询方式读取数据表，支持行级别过滤，默认开启                        |
+| 允许流式抽取 | 以CDC的方式实时捕捉数据库变更，默认开启                          |
+| 允许数据写入 | 可以作为目标端数据源，默认开启                                |
+
+##### 基本功能
+
+| 功能     | 说明                                              |
+| ------ | ----------------------------------------------- |
+| 结构迁移   | 如目标不存在所选表，则自动根据源端元数据，结合映射生成对端创建语句并执行创建          |
+| 全量数据迁移 | 逻辑迁移，通过顺序扫描表数据，将数据分批写入到对端数据库                    |
+| 增量实时同步 | 支持 **INSERT**, **UPDATE**, **DELETE** 常见 DML 同步 |
+
+#### 配置云器Lakehouse作为目标端
+
+![](.topwrite/assets/image_1718870882049.png)
+
+##### 配置项说明
+
+| 配置项名称  | 说明                                                                                                          |
+| ------ | ----------------------------------------------------------------------------------------------------------- |
+| 连接串    | 数据源的连接方式，格式是：{instance}.{domain}/{workspace}，例如：abcdef.cn-shanghai-alicloud.api.clickzetta.com/quick\_start |
+| 虚拟集群   | 设置运行的虚拟集群，默认值为default                                                                                       |
+| 用户名    | 连接数据库的用户名，例如：username                                                                                       |
+| 密码     | 连接数据库的用户名所对应的密码，例如：userpassword                                                                             |
+| 连接名称   | 自定义的数据源名称，方便后续管理，例如：本地测试实例                                                                                  |
+| 允许批量抽取 | 以查询方式读取数据表，支持行级别过滤，暂不支持抽取                                                                                   |
+| 允许流式抽取 | 以CDC的方式实时捕捉数据库变更，暂不支持抽取                                                                                     |
+| 允许数据写入 | 可以作为目标端数据源，默认开启                                                                                             |
+
+### 在Oracle数据库创建表
+
+```
+CREATE TABLE metabase.people_with_pk (
+    id INTEGER PRIMARY KEY,
+    age INTEGER,
+    name VARCHAR(32),
+    create_date DATE DEFAULT GETDATE()
+);
+
+CREATE TABLE metabase.employees (
+    employee_id INTEGER  PRIMARY KEY,
+    first_name VARCHAR(50),
+    last_name VARCHAR(50),
+    hire_date DATE,
+    salary INTEGER,
+    department_id INTEGER,
+    email VARCHAR(100),
+    phone_number VARCHAR(20),
+    address VARCHAR(200),
+    job_title VARCHAR(100),
+    manager_id INTEGER,
+    commission_pct DECIMAL,
+    birth_date DATE,
+    marital_status VARCHAR(10),
+    nationality VARCHAR(50),
+    create_date DATE DEFAULT GETDATE()
+);
+CREATE TABLE  metabase.departments (
+    department_id INTEGER  PRIMARY KEY,
+    department_name VARCHAR(100),
+    location VARCHAR(200),
+    manager_id INTEGER,
+    created_date DATE,
+    description VARCHAR(500),
+    budget INTEGER,
+    status VARCHAR(20),
+    contact_person VARCHAR(100),
+    phone_number VARCHAR(20),
+    email VARCHAR(100),
+    website VARCHAR(200),
+    start_date DATE,
+    end_date DATE,
+    num_employees INTEGER,
+    create_date DATE DEFAULT GETDATE()
+);
+```
+
+### 在Bluepipe新建同步作业
+
+请注意：
+
+1. 在选择来源时，目标表名 `{namespace}/{table}` 中的 `{namespace}`，可以用你期望的schema名字来替代，比如 `bluepipe_oracle_staging`。
+2. 在设计环节，增量复制选择“使用CDC技术实时复制”。
+   新建同步作业成功后的效果如下图：
+   ![](.topwrite/assets/image_1718871018707.png)
+   新建作业会自动启动并开始全量数据同步，之后开始持续的增量数据实时同步。
+
+### 数据生成
+
+通过运行如下Python代码，向Oracle源表employees中实时插入数据：
+
+```
+import oracledb
+import random
+import time,datetime
+db_user = "SYSTEM"
+db_password = ""
+db_host = "
+db_port = "1521"
+db_service_name = "XE"
+# 连接到 Oracle 数据库，并获取游标
+connection = oracledb.connect(f"{db_user}/{db_password}@{db_host}:{db_port}/{db_service_name}")
+cursor = connection.cursor()
+# 要插入的总数量
+total_records = 1000000
+batch_size = 1000 # 每批次插入的记录数
+inserted_rows = 0
+start_time = time.time()
+for batch_start in range(1, total_records + 1, batch_size):
+batch_end = min(batch_start + batch_size - 1, total_records)
+hire_date = random.randint(1, 200)
+# 构建插入语句
+insert_sql = f"""
+INSERT INTO metabase.employees (
+employee_id, first_name, last_name, hire_date, salary, department_id,
+email, phone_number, address, job_title, manager_id, commission_pct,
+birth\_date, marital_status, nationality
+)
+SELECT
+LEVEL,
+'名字' || LEVEL,
+'姓氏' || LEVEL,
+SYSDATE - {hire_date},
+5000 + LEVEL * 1000,
+MOD(LEVEL, 5) + 1,
+'employee' || LEVEL || '@example.com',
+'123-456-' || LPAD(LEVEL, 3, '0'),
+'地址' || LEVEL,
+CASE MOD(LEVEL, 3)
+WHEN 0 THEN '经理'
+WHEN 1 THEN '分析师'
+WHEN 2 THEN '职员'
+END,
+CASE WHEN LEVEL > 1 THEN TRUNC((LEVEL - 1) / 5) END,
+0.1 * LEVEL,
+SYSDATE - (LEVEL * 100),
+CASE MOD(LEVEL, 2)
+WHEN 0 THEN '单身'
+WHEN 1 THEN '已婚'
+END,
+CASE MOD(LEVEL, 4)
+WHEN 0 THEN '中国'
+WHEN 1 THEN '美国'
+WHEN 2 THEN '英国'
+WHEN 3 THEN '澳大利亚'
+END
+FROM DUAL
+CONNECT BY LEVEL <= {batch_size}
+"""
+# 执行插入
+cursor.execute(insert_sql)
+connection.commit()
+inserted_rows = inserted_rows + batch_size
+end_time = time.time()
+total_time = end_time - start_time
+average_insert_speed = inserted_rows / total_time
+print(f"Total rows inserted: {inserted_rows}")
+print(f"Average insert speed: {average_insert_speed:.2f} rows/second")
+time.sleep(0.5)
+end_time = time.time()
+total_time = end_time - start_time
+average_insert_speed = inserted_rows / total_time
+print(f"Total rows inserted: {inserted\_rows}")
+print(f"Average insert speed: {average\_insert\_speed:.2f} rows/second")
+# 关闭游标和连接
+cursor.close()
+connection.close()
+```
+
+### 通过Metabase观察源端数据和目的端数据
+
+![](.topwrite/assets/image_1718872014999.png)
+请参考：[Metabase的安装部署](metabase.md)

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

@@ -0,0 +1,38 @@
+# CHAR
+`CHAR` 是一种固定长度的字符类型，其最大长度为 255。当字符长度不足指定的最大长度时，系统不会自动使用空格填充至最大长度。在进行字符串比较时，尾随空格并不会被考虑在内。
+
+## 语法
+```
+CHAR(N)
+```
+其中，`N` 表示字符类型 `CHAR` 的最大长度，范围为 1 到 255。
+
+
+
+## 示例
+1. 创建一个固定长度为 5 的 `CHAR` 类型：
+```
+CREATE TABLE char_t(col CHAR(5));
+```
+
+2. 插入一个长度不足的字符串：
+```
+SELECT CHAR(10) 'abcd';
+```
+结果将返回一个长度为 10 的字符串，例如：`'abcd'`
+
+3. 插入一个长度超过指定长度的字符串：
+```
+SELECT cast( 'abcdef' as char(3))
+```
+结果将返回一个长度为 3 的字符串，例如：`'abc'`（仅取前 3 个字符）
+
+4. CHAR 在比较时，忽略尾随空格：
+```
+SELECT cast('abc' as char(5)) = cast('abc' as char(10));
+```
+结果将返回 `true`，因为尾随空格在比较时会被忽略。
+
+## 注意事项
+- 在进行字符串比较时，应考虑到 `CHAR` 类型的尾随空格会被忽略的特性。
+- 根据实际需求，合理选择 `CHAR` 类型与 `VARCHAR` 类型。如果数据长度固定或变化范围较小，可使用 `CHAR` 类型以提高性能；反之，如果数据长度变化较大，建议使用 `VARCHAR` 类型以节省存储空间。

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

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