@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/UNDROP-TABLE.md

@@ -0,0 +1,163 @@
+# UNDROP TABLE 语句
+
+使用 UNDROP TABLE 语句可以恢复被删除的表、动态表和物化视图。是否可以恢复被删除的对象取决于数据的[保留周期](TIMETRAVEL.md)。
+
+**数据保留周期**
+
+对象能否被恢复取决于数据的保留周期。当前预览版本的数据保留周期默认为 7 天，未来将调整为 1 天。您可以通过执行 [ALTER 命令](alter.md) 来调整保留周期。请注意，修改保留周期可能会增加存储成本。
+
+**支持的对象类型**：
+
+* 表（TABLE）
+* 动态表（DYNAMIC TABLE）
+* 物化视图（MATERIALIZED VIEW）
+
+## 语法
+
+```sql
+UNDROP TABLE tablename;
+```
+
+## 参数说明
+
+* **tablename**：指定被删除的表的名称。支持恢复动态表、内部表、物化视图。
+
+## 示例
+
+### 示例 1：删除表后立即恢复
+
+```sql
+-- 创建表
+CREATE TABLE mytable(id int, name string);
+INSERT INTO mytable VALUES(1, 'aaa');
+-- 删除表
+DROP TABLE mytable;
+-- 查看表删除记录，可以看到删除时间
+SHOW TABLES HISTORY;
++---------------+------------+-------------------------+----------+------+-------+---------+----------------+-------------------------+
+| schema_name  | table_name | create_time            | creator  | rows | bytes | comment | retention_time | delete_time             |
++---------------+------------+-------------------------+----------+------+-------+---------+----------------+-------------------------+
+| undrop_schema | mytable    | 2023-06-06 12:22:57.642 | UAT_TEST | 1    | 1348  |         | 1              | 2023-07-18 17:49:26.374 |
++---------------+------------+-------------------------+----------+------+-------+---------+----------------+-------------------------+
+-- 恢复表
+UNDROP TABLE mytable;
+```
+
+### 示例 2：删除表后创建同名表再恢复
+
+```sql
+-- 创建表
+CREATE TABLE mytable(id int, name string);
+INSERT INTO mytable VALUES(1, 'aaa');
+-- 删除表
+DROP TABLE mytable;
+-- 查看表删除记录
+SHOW TABLES HISTORY;
+-- 重复建表
+CREATE TABLE mytable(col1 int, col2 string);
+-- 查看表删除记录，未删除的表delete_time是null
+SHOW TABLES HISTORY;
++---------------+------------+-------------------------+----------+------+-------+---------+----------------+-------------------------+
+| schema_name  | table_name | create_time            | creator  | rows | bytes | comment | retention_time | delete_time             |
++---------------+------------+-------------------------+----------+------+-------+---------+----------------+-------------------------+
+| undrop_schema | mytable    | 2023-07-18 17:51:25.978 | UAT_TEST | 0    | 0     |         | 1              |                          |
+| undrop_schema | mytable    | 2023-06-06 12:22:57.642 | UAT_TEST | 1    | 1348  |         | 1              | 2023-07-18 17:49:26.374 |
++---------------+------------+-------------------------+----------+------+-------+---------+----------------+-------------------------+
+-- 重命名未删除的表
+ALTER TABLE mytable RENAME TO mytable_back;
+-- 恢复表
+UNDROP TABLE mytable;
+```
+
+### 示例 3：恢复动态表
+
+```sql
+-- 创建一个基表
+DROP TABLE IF EXISTS dy_base_a;
+CREATE TABLE dy_base_a (i int, j int);
+INSERT INTO dy_base_a VALUES
+(1, 10),
+(2, 20),
+(3, 30),
+(4, 40);
+-- 使用dynamic table进行加工
+DROP DYNAMIC TABLE IF EXISTS change_table;
+CREATE DYNAMIC TABLE change_table
+(i, j)
+AS SELECT * FROM dy_base_a;
+-- 刷新dynamic table
+REFRESH DYNAMIC TABLE change_table;
+-- 查询数据
+SELECT * FROM change_table;
++---+----+
+| i | j  |
++---+----+
+| 1 | 10 |
+| 2 | 20 |
+| 3 | 30 |
+| 4 | 40 |
++---+----+
+DROP DYNAMIC TABLE IF EXISTS change_table;
+UNDROP TABLE change_table;
+SELECT * FROM change_table;
+```
+
+### 示例 4：恢复物化视图
+
+```SQL
+DROP TABLE IF EXISTS mv_base_a;
+DROP MATERIALIZED VIEW IF EXISTS mv1;
+
+-- 创建一个基表
+CREATE TABLE mv_base_a (i int, j int);
+
+INSERT INTO mv_base_a
+VALUES (1, 10),
+       (2, 20),
+       (3, 30),
+       (4, 40);
+
+-- 创建物化视图
+CREATE MATERIALIZED VIEW mv1 (i, j) AS
+SELECT *
+FROM mv_base_a;
+
+-- 刷新物化视图
+REFRESH MATERIALIZED VIEW mv1;
+
+-- 查询数据
+SELECT * FROM mv1;
++---+----+
+| i | j  |
++---+----+
+| 1 | 10 |
+| 2 | 20 |
+| 3 | 30 |
+| 4 | 40 |
++---+----+
+DROP MATERIALIZED VIEW mv1;
+SHOW TABLES HISTORY WHERE table_name = 'mv1';
++-------------+------------+-------------------------+----------+------+-------+---------+----------------+-------------------------+
+| schema_name | table_name |       create_time       | creator  | rows | bytes | comment | retention_time |       delete_time       |
++-------------+------------+-------------------------+----------+------+-------+---------+----------------+-------------------------+
+| public      | mv1        | 2024-12-18 16:57:35.916 | UAT_TEST | 4    | 2467  |         | 1              | 2024-12-18 16:57:58.427 |
++-------------+------------+-------------------------+----------+------+-------+---------+----------------+-------------------------+
+UNDROP TABLE mv1;
+
+SELECT * FROM mv1;
++---+----+
+| i | j  |
++---+----+
+| 1 | 10 |
+| 2 | 20 |
+| 3 | 30 |
+| 4 | 40 |
++---+----+
+```
+
+## 注意事项
+
+* 请确保在数据保留周期内进行恢复操作，否则无法恢复被删除的对象。
+* 在恢复对象之前，请确保没有同名的对象存在。如有同名对象，请先重命名或删除该同名对象。
+
+

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

@@ -0,0 +1,70 @@
+# 更新表记录
+
+## 功能描述
+更新数据库表中的记录，将指定的字段值修改为新的值。
+
+## 语法格式
+```SQL
+UPDATE target_table
+       SET column_name1 = new_value1 [ , column_name2 = new_value2 , ... ]
+  [ WHERE condition ]
+[ORDER BY ...] 
+[LIMIT row_count]
+```
+
+**必选参数**
+
+- `target_table`：需要更新记录的目标表名。
+- `column_name`：需要更新的列名。
+- `new_value`：新的值，可以是常量、变量、函数调用、算术运算符、字符串操作等。支持子查询。
+
+**可选参数**
+- `condition`：更新操作的条件，用于限定哪些记录需要被更新。条件可以包含子查询和表达式。
+- `ORDER BY ...`‌按指定列排序后更新：
+  * 通常与 `LIMIT` 配合使用，控制更新顺序。
+  * 适用于分批更新或按优先级处理数据（如先处理最新记录）。
+- `LIMIT row_count`：限制更新的最大行数：
+  * 常用于分批更新大数据表，避免锁表或事务过长。
+  * 需配合 `ORDER BY` 确保更新顺序的确定性。
+
+
+## 使用示例
+
+### 示例1：更新单个字段值
+假设我们有一个名为`employees`的表，包含员工的ID、姓名和工资。现在我们要将ID为1的员工的工资增加1000元。
+
+```SQL
+UPDATE employees
+SET salary = salary + 1000
+WHERE id = 1;
+```
+
+### 示例2：同时更新多个字段值
+继续使用`employees`表，现在我们要将ID为1的员工的工资增加1000元，并将职位从"Developer"更改为"Senior Developer"。
+
+```SQL
+UPDATE employees
+SET salary = salary + 1000, position = 'Senior Developer'
+WHERE id = 1;
+```
+
+### 示例3：使用子查询更新字段值
+假设我们有一个名为`orders`的表，包含订单ID、客户ID和订单金额。我们还有一个名为`customers`的表，包含客户ID、姓名和会员等级。现在我们要将所有VIP客户的订单金额增加10%。
+
+```SQL
+UPDATE orders
+SET amount = amount * 1.1
+WHERE customer_id IN (
+  SELECT id
+  FROM customers
+  WHERE membership_level = 'VIP'
+);
+```
+### 示例4：UPDATE语句带有ORDER BY
+```
+UPDATE t SET id = id + 1 ORDER BY id DESC;
+```
+
+## 注意事项
+- 在执行更新操作时，请确保`WHERE`子句正确无误，以免错误地更新了不应该更新的记录。
+- 在对生产环境进行更新操作之前，建议先在测试环境中进行验证。

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

@@ -0,0 +1,53 @@
+### 功能描述
+
+`USE SCHEMA` 语句旨在改变当前会话的默认 SCHEMA 设置。当您执行此操作后，所有未明确指定 SCHEMA 的 SQL 查询和命令都将在新设定的 SCHEMA 范围内执行。这有助于简化 SQL 语句的编写，提高工作效率。
+
+### 语法
+
+```SQL
+USE [SCHEMA] schema_name;
+```
+
+### 参数说明
+
+- `schema_name`: 您希望切换至的目标 SCHEMA 名称。
+
+### 使用示例
+
+1. 切换至名为 `reporting` 的 SCHEMA：
+
+   ```SQL
+   USE reporting;
+   ```
+
+2. 在执行一系列针对 `sales` 数据表的操作时，首先切换至相应的 SCHEMA：
+
+   ```SQL
+   USE sales_schema;
+   SELECT * FROM sales_data;
+   UPDATE sales_data SET quantity = 100 WHERE product_id = 12;
+   ```
+
+3. 当需要在不同的 SCHEMA 之间频繁切换时，可以通过 `USE` 语句快速定位至特定的数据集合：
+
+   ```SQL
+   -- 从当前的 sales_schema 切换至 customer_schema
+   USE customer_schema;
+   -- 查询客户信息
+   SELECT * FROM customers;
+   -- 切换回 sales_schema
+   USE sales_schema;
+   ```
+
+4. 如果您希望在创建表时指定 SCHEMA，但不想立即切换至该 SCHEMA，可以在创建表的语句中包含 SCHEMA 名称，而无需使用 `USE` 语句：
+
+   ```SQL
+   CREATE TABLE finance_schema.ledger (
+     id INT PRIMARY KEY,
+     amount DECIMAL(10, 2) NOT NULL
+   );
+   ```
+
+## 注意事项
+- 在使用客户端工具（如[客户端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/UnifiedWorkflowIntro.md

@@ -0,0 +1,31 @@
+# AI + BI 统一工作流
+
+云器 Lakehouse 创新性地提供了 **AI + BI 统一工作流**解决方案，将传统的数据处理流程与 AI 数据应用流程无缝整合在同一平台上，实现真正的数据智能融合。
+
+### 传统分离式架构的痛点
+
+1.  **技术栈割裂**
+    *   BI 系统：基于 SQL、ETL 工具、报表平台。
+    *   AI 应用：基于 Python、向量数据库、推理服务。
+    *   两套系统独立运行，数据难以共享。
+
+2.  **数据孤岛问题**
+    *   结构化数据存储在数据仓库。
+    *   非结构化数据分散在对象存储。
+    *   向量数据独立存储在专门的向量数据库中。
+
+3.  **工作流程断层**
+    *   ETL 流程和 AI 应用流程相互独立。
+    *   数据需要在多个系统间复制和转换。
+    *   维护成本高，数据一致性难保证。
+
+## 云器 Lakehouse 统一工作流方案
+
+### 核心理念
+
+云器 Lakehouse 通过统一的数据湖仓架构，支持在同一平台上运行传统 ETL 工作流和 AI 数据应用工作流，实现：
+
+*   **统一存储**：结构化、非结构化、向量数据统一管理。
+*   **统一计算**：SQL 分析与 AI 推理共享计算资源。
+*   **统一编排**：ETL 任务与 AI 应用统一调度。
+*   **统一治理**：数据血缘、权限、质量统一管控。

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

@@ -0,0 +1,175 @@
+# 基于云器 Lakehouse 的车辆图像智能识别案例
+
+### 概述
+
+云器 Lakehouse 创新性地提供了 **AI + BI 统一工作流**解决方案，将传统的数据处理流程与 AI 数据应用流程无缝整合在同一平台上，实现真正的数据智能融合。本文以车辆图像识别为例，展示如何构建一个完整的 AI + BI 统一工作流。
+
+### 业务场景
+
+某智慧交通管理平台需要：
+
+* 实时处理来自各路口摄像头的车辆图像
+* 自动识别车辆型号、颜色、年份等信息
+* 构建车辆特征数据库，支持后续的交通分析和管理决策
+
+### 架构设计
+
+```
+OSS 图像存储 →  Volume 数据湖 →  AI 识别处理  →  结构化存储  →   BI 分析展示
+     ↓              ↓              ↓            ↓            ↓
+  原始图像         增量检测       AI UDF调用     数据解析入库   可视化报表
+```
+
+### 工作流实现
+
+![](.topwrite/assets/AIworkflow.png =743)
+
+#### **Task 1: 数据源刷新与增量检测**
+
+```sql
+-- 刷新 Volume，检测新增图像文件
+ALTER VOLUME sg_volume_images REFRESH;
+
+-- 记录刷新时间点，用于后续增量处理
+SET refresh_timestamp = CURRENT_TIMESTAMP();
+```
+
+**最佳实践要点**：
+
+* 定期刷新 Volume 以发现新文件
+* 使用时间戳记录刷新点，支持增量处理
+* 建议根据业务需求设置合理的刷新频率（如每 5 分钟）
+
+#### **Task 2: AI 识别与结构化处理**
+
+```sql
+-- 增量处理最近 ${last_min} 分钟内的新图像
+WITH check_new_files AS (
+    SELECT COUNT(*) AS file_count
+    FROM DIRECTORY(VOLUME sg_volume_images)
+    WHERE last_modified_time >= DATEADD(MINUTE, -${last_min}, CURRENT_TIMESTAMP())
+),
+-- AI 识别处理
+recognition AS (
+    SELECT *
+    FROM (
+        SELECT 
+            relative_path as vehicle_images,
+            pre_signed_url,
+            -- 调用 AI 外部函数进行车辆识别
+            public.fc_image_to_text('vehicle_type', pre_signed_url) as vehicle_recognition,
+            last_modified_time
+        FROM (
+            SELECT 
+                relative_path,
+                -- 生成临时访问 URL，有效期 2 小时
+                get_presigned_url(volume sg_volume_images, relative_path, 7200) as pre_signed_url,
+                last_modified_time
+            FROM DIRECTORY(VOLUME sg_volume_images)
+            WHERE last_modified_time >= DATEADD(MINUTE, -${last_min}, CURRENT_TIMESTAMP())
+        )
+    ) subq
+    WHERE EXISTS (SELECT 1 FROM check_new_files WHERE file_count > 0)
+)
+-- 解析 AI 返回的 JSON 结果并入库
+INSERT INTO vehicle_type_data (
+    car_model, car_color, year, score, 
+    vehicle_recognition, pre_signed_url, last_modified_time, process_time
+)
+SELECT 
+    get_json_object(regexp_replace(vehicle_recognition, "'", '"'), '$.result[0].name') as car_model,
+    get_json_object(regexp_replace(vehicle_recognition, "'", '"'), '$.color_result') as car_color,
+    get_json_object(regexp_replace(vehicle_recognition, "'", '"'), '$.result[0].year') as year,
+    cast(get_json_object(regexp_replace(vehicle_recognition, "'", '"'), '$.result[0].score') as decimal(16,6)) as score,
+    vehicle_recognition,
+    r.pre_signed_url,
+    last_modified_time,
+    CURRENT_TIMESTAMP() as process_time
+FROM recognition r
+WHERE EXISTS (SELECT 1 FROM check_new_files WHERE file_count > 0);
+```
+
+**最佳实践要点**：
+
+* 使用 CTE 进行增量检测，避免处理已识别的图像
+* 生成预签名 URL 供 AI 服务访问，确保安全性
+* JSON 解析时注意引号转换和数据类型转换
+* 记录处理时间，便于监控和审计
+
+#### **Task 3: 数据质量控制与异常处理**
+
+```sql
+-- 数据质量检查和异常处理
+WITH quality_check AS (
+    -- 检查识别失败的记录
+    SELECT 
+        vehicle_images,
+        pre_signed_url,
+        vehicle_recognition,
+        CASE 
+            WHEN vehicle_recognition IS NULL THEN 'AI服务调用失败'
+            WHEN score < 0.6 THEN '识别置信度过低'
+            WHEN car_model IS NULL THEN '车型识别失败'
+            ELSE '正常'
+        END as quality_status
+    FROM vehicle_type_data
+    WHERE process_time >= DATEADD(MINUTE, -${last_min}, CURRENT_TIMESTAMP())
+)
+-- 将异常记录写入错误日志表
+INSERT INTO vehicle_recognition_errors (
+    vehicle_images, pre_signed_url, error_type, 
+    error_details, retry_count, created_time
+)
+SELECT 
+    vehicle_images,
+    pre_signed_url,
+    quality_status as error_type,
+    vehicle_recognition as error_details,
+    0 as retry_count,
+    CURRENT_TIMESTAMP() as created_time
+FROM quality_check
+WHERE quality_status != '正常';
+
+-- 更新处理统计信息
+MERGE INTO vehicle_process_stats AS target
+USING (
+    SELECT 
+        DATE(CURRENT_TIMESTAMP()) as process_date,
+        COUNT(*) as total_processed,
+        SUM(CASE WHEN quality_status = '正常' THEN 1 ELSE 0 END) as success_count,
+        SUM(CASE WHEN quality_status != '正常' THEN 1 ELSE 0 END) as error_count
+    FROM quality_check
+) AS source
+ON target.process_date = source.process_date
+WHEN MATCHED THEN UPDATE SET
+    total_processed = target.total_processed + source.total_processed,
+    success_count = target.success_count + source.success_count,
+    error_count = target.error_count + source.error_count,
+    last_update_time = CURRENT_TIMESTAMP()
+WHEN NOT MATCHED THEN INSERT (
+    process_date, total_processed, success_count, 
+    error_count, last_update_time
+) VALUES (
+    source.process_date, source.total_processed, 
+    source.success_count, source.error_count, CURRENT_TIMESTAMP()
+);
+```
+
+**最佳实践要点**：
+
+* 实施数据质量检查，识别低质量结果
+* 建立错误处理机制，支持后续重试
+* 维护处理统计信息，便于监控系统健康度
+
+### 最佳实践总结
+
+1.  **统一平台优势**
+    * 数据存储、AI 处理、BI 分析在同一平台完成
+    * 避免数据搬迁，降低延迟和成本
+    * 统一的权限管理和数据治理
+
+2.  **增量处理策略**
+    * 使用时间戳实现增量识别，避免重复处理
+    * 设置合理的处理批次大小，平衡实时性和资源消耗
+
+通过这个完整的 AI + BI 统一工作流，企业可以快速构建从数据采集、AI 处理到业务分析的端到端智能应用，真正实现数据驱动的业务决策。