@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/cluster-table.md

@@ -0,0 +1,64 @@
+# 分桶键（Clustered Key）和排序键（Sorted Key）
+
+在大数据存储与分析领域，数据的组织方式对于查询性能和存储效率具有重要影响。本文将详细介绍分桶键（Clustered Key）和排序键（Sorted Key）的概念、使用方法以及实际应用示例，帮助您更好地优化数据组织结构。
+
+## 分桶键（Clustered Key）
+
+分桶键是表数据分布的核心，通过指定列的Hash Key，Lakehouse会根据这些键对数据进行Hash运算，并将数据分散到不同的数据分桶（buckets）中。这种分散有助于避免数据倾斜和热点问题，同时提高并行处理的能力。
+
+### 选择分桶键的准则
+
+- 选择取值范围广、重复值少的列作为分桶键，以实现数据的均匀分布。
+- 在进行`JOIN`操作时，如果连接的键与分桶键一致，可以显著提高性能。
+- 适用于数据量大的场景，推荐的数据分桶大小约为128MB到1GB，具体取决于数据的压缩率和访问模式。
+- 如果没有指定分桶键，则默认使用256个分桶。
+
+### 注意事项
+
+- 避免指定过小的分桶键数量，以免产生大量小文件，影响元数据管理和I/O操作效率。
+- 过多的小文件会导致数据局部性差，增加任务调度开销，降低处理效率。
+
+## 排序键（Sorted Key）
+
+排序键用于定义文件内数据的排序方式。对于需要按排序键进行排序的查询，预先将数据按排序键组织可以提高查询性能。
+
+### 使用排序键的注意事项
+
+- 可以为排序键指定升序（ASC）或降序（DESC）。
+- 虽然排序键可以提高查询性能，但对大量数据进行插入时排序可能会消耗较多资源。
+
+## 实际应用示例
+
+### 示例1：创建表并指定分桶键与排序键
+
+```sql
+CREATE TABLE sales_data (
+    sale_id INT,
+    product_id INT,
+    quantity_sold INT,
+    sale_date DATE,
+    ...
+) CLUSTERED BY (product_id)
+SORTED BY (sale_date DESC)
+INTO 50 BUCKETS;
+```
+
+在这个示例中，创建了一个名为`sales_data`的表，数据将根据`product_id`列的Hash值被分散到50个分桶中。同时，分桶内的数据将按照`sale_date`列的降序进行排序。
+
+### 示例2：优化数据仓库的查询性能
+
+假设您正在处理一个包含大量交易记录的数据仓库，可以通过以下方式优化查询性能：
+
+```sql
+CREATE TABLE transaction_records (
+    transaction_id INT,
+    customer_id INT,
+    transaction_date DATE,
+    amount DECIMAL(10,2),
+    ...
+) CLUSTERED BY (customer_id)
+SORTED BY (transaction_date ASC)
+INTO 128 BUCKETS;
+```
+
+在这个示例中，`transaction_records`表根据`customer_id`进行分桶，分桶内的数据按照`transaction_date`进行排序。这样的设计有助于提高按客户查询交易记录的效率。

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

@@ -0,0 +1,178 @@
+# 组合任务
+
+组合任务是一种特殊的任务类型，它支持将多个周期任务（例如离线同步、SQL 任务）封装为独立单元，以实现**统一调度配置、参数管理和运维操作**，并且能够与其他普通节点建立依赖关系。本任务类型适用于需要批量管理任务流程、统一控制调度周期的业务场景（如增量计算、跨任务协同）。组合任务与[任务组](task_group.md)功能进行对比，两者存在以下核心区别：
+* 任务组属于逻辑管理概念，可将多种任务置于一个组内进行统一展示与编排。组合任务是一种任务类型的实体，与普通的 SQL 任务处于同等地位，可在任务组中添加组合任务作为其元素之一。
+* 从外部看，组合任务是一个整体，但内部会包含一到多个子任务节点（这些子任务可以是 SQL 任务、离线同步任务等各种周期调度任务）。
+* 组合任务支持统一设定调度时间，其内部所有子任务节点依据该调度时间进行同频调度。这尤其适用于对所有任务节点的数据新鲜度有相同要求的数据处理链路。任务组上不支持设定调度定时属性。
+
+## 快速上手：创建组合任务
+
+组合任务的创建操作，整体上和普通周期 SQL 任务等非常类似。
+
+### 创建入口
+
+支持通过以下路径新建组合任务：
+
+* 任务开发：任务Tab → 新建任务 → 选择“组合任务”
+
+  ![](.topwrite/assets/image_1752130018729.png =420)
+
+* 任务组详情页：任务组内 → 添加新任务 → 选择“组合任务”；
+  
+  ![](.topwrite/assets/image_1752130033606.png =680)
+
+* 工作区：顶部导航栏 → 新建任务 → 选择“组合任务”。
+  
+  ![](.topwrite/assets/image_1752130048252.png =680)
+
+### 基础信息填写
+
+在创建组合任务的弹框中，和其他普通 SQL 任务一样，填写需要的信息：
+
+* 任务名称：必填。
+* 文件夹：任务要放入的文件夹（必填）。
+* 任务组：选择是否放入任务组，如需放入则选定具体的任务组名称（可选）。
+
+  ![](.topwrite/assets/image_1752130064673.png =680)
+
+## 核心功能操作指南
+
+### 子任务管理（画布模式）
+
+组合任务目前通过**画布**（DAG 图）来展示子任务节点，并支持以下操作：
+![](.topwrite/assets/image_1752130101512.png =680)
+
+#### 添加子任务
+
+* **入口**：画布工具栏 → 「新建子任务」→ 选择任务类型（仅支持周期任务：离线同步、SQL等；**不支持实时任务**）。通过单击任务类型或拖拽的方式，可将子任务添加到组合任务中。
+
+  ![](.topwrite/assets/image_1752130110716.png =360)
+
+* **默认状态**：新增的子任务，默认无依赖，需手动调整依赖关系（通过页面上连线或在子任务详情进行配置）。
+
+#### 编辑子任务
+
+* **方式**：
+  * 在添加子任务节点时，会默认进入子任务的详情页，便于编写代码和配置调度信息。
+  * 双击子任务 → 进入普通节点编辑页（复用现有编辑功能）；
+
+* **限制**：为了确保组合任务提交后运行正常，子任务不支持独立保存为半成品，需填写所有必填属性（如代码、集群、调度属性）后才能保存。在退出子任务编辑前，请确保这些信息完整且已正确保存。
+
+#### 依赖编排
+
+* **子任务中配置**：在子任务上，点击「调度」→ 在「调度依赖」中设定它依赖的上游子任务。
+* **画布上连线**：在组合任务的DAG画布上，选中源节点 → 拖拽连线至目标节点 → 建立“上游→下游”依赖。也可以通过操作连线来删除依赖关系。
+
+#### 画布工具
+
+* **自动排版**：工具栏 → 「自动布局」→ 按依赖关系优化DAG展示；
+* **缩放/刷新**：工具栏 → 「+/-」调整画布大小，或「刷新」重置视图。
+
+### 调度配置（全局与局部结合）
+
+组合任务的调度策略通过**全局配置**（组合任务层级）与**局部配置**（子任务层级）协同管理。整体思路是：子任务默认继承组合任务的全局配置，也支持在局部单独配置；若局部已配置，则以局部配置为准。关键配置项如下表：
+
+| 配置项   | 全局配置（组合任务）              | 局部配置（子任务）                    |
+| ----- | ----------------------- | ---------------------------- |
+| 调度时间  | 必配，支持Cron表达式（子任务不可独立设置） | 无（子任务遵循组合任务全局设定的调度时间、同频调度运行） |
+| 实例重跑  | 全局设置（重跑次数、间隔），子任务默认继承   | 可选覆盖全局设置（仅支持SQL等特定任务类型）      |
+| 任务优先级 | 全局设置（默认值）               | 可选单独设置（覆盖全局，仅SQL节点支持）        |
+| 自依赖   | 全局设置（控制组合任务周期依赖）        | 无（子任务自依赖通过组合任务全局自依赖间接实现）     |
+
+**示例**：若组合任务全局设置为“重跑次数 3 次，间隔 5 分钟”，某子任务单独配置为“重跑次数 5 次”，则该子任务实际使用“重跑 5 次，间隔 5 分钟”。
+
+![](.topwrite/assets/image_1752130126629.png =680)
+
+![](.topwrite/assets/image_1752130133390.png =680)
+
+### 参数管理（组合任务→子任务传递）
+
+#### 定义参数
+
+* **入口**：组合任务详情页 → 点击「参数」→ 在弹框中新增参数（如`composite_task_param`）：
+
+  ![](.topwrite/assets/image_1752130143435.png =680)
+
+  ![](.topwrite/assets/image_1752130151838.png =680)
+
+* **作用域**：仅当前组合任务内部有效，不同组合任务之间参数隔离。
+
+#### 引用参数
+
+在子任务的参数配置中，若参数名称与组合任务定义的参数名称相同，在参数取值处会自动识别并提示选择参数的取值来源。若要使用组合任务全局定义的参数，在取值来源处选择“组合任务”；否则，可选择“任务”。
+
+![](.topwrite/assets/image_1752130161305.png =680)
+
+在子任务的代码中，支持通过`${参数名}`引用参数。**示例**（SQL子任务）：
+
+```
+SELECT * FROM user_log WHERE dt = '${composite_task_param}'  
+```
+
+## 高级操作：保存与提交
+
+### 保存组合任务
+
+* 组合任务当前不支持全局统一保存所有子任务节点。请逐一保存每个子任务，确保其代码、调度配置等信息已保存。之后，再提交组合任务。
+
+### 提交组合任务
+
+* **作用**：支持将组合任务及内部所有子任务提交到生产环境周期调度运行，会生成对应的“提交版本”。
+
+* **操作入口**：组合任务详情页 → 「提交」。
+
+  ![](.topwrite/assets/image_1752130174992.png =680)
+
+## 运维与监控
+
+### 组合任务的运维
+
+组合任务在运维中心会与其他周期任务一并在列表中展示，并支持类似的操作，如暂停、补数据、下线等。
+
+![](.topwrite/assets/image_1752130184652.png =680)
+
+| 操作     | 说明                                                                 |
+| ------ | ------------------------------------------------------------------ |
+| 暂停/恢复 | 暂停后，组合任务及子任务停止调度；恢复后，按当前配置继续执行。                             |
+| 补数据    | 选择时间范围 → 组合任务整体按调度规则生成补数据实例（包含所有子任务实例）。                        |
+| 下线     | 下线后任务不再调度。需检查是否存在下游依赖（若存在下游依赖，则无法直接下线，需使用“下线（含下游）”功能）。 |
+
+### 组合任务实例的运维
+
+在实例运维 Tab 页，可以查看到组合任务的实例，与其他周期任务实例并列，并支持重跑、置成功/置失败等操作，如下图所示：
+
+![](.topwrite/assets/image_1752130199325.png =680)
+
+#### 状态查看
+
+* **整体状态**：组合任务实例状态由子任务状态综合判定，具备以下状态：未运行（所有子任务未运行）、运行中（任一子任务运行中）、运行成功（所有子任务成功）、运行失败（至少一个子任务失败）。
+* **下钻查看**：点击实例ID → 进入子任务实例DAG页，查看各子任务运行详情（含日志、状态）。
+
+#### 实例操作
+
+| 操作        | 在哪些状态下支持       | 行为说明                                                                 |
+| --------- | -------------- | ---------------------------------------------------------------------- |
+| 重跑        | 任意终态（失败/成功）    | 整体重跑组合任务，子任务按各自重跑规则生成新实例（不支持选择部分子任务）。                                 |
+| 置成功/置失败 | 未运行/终态         | 组合任务及所有子任务实例状态强制变更为成功/失败。                                            |
+| 终止        | 运行中            | 终止所有运行中/未运行的子任务实例，状态置为失败。                                              |
+
+### 组合任务的监控告警
+
+在监控告警中，组合任务会被归入周期调度任务这一大类。先前的“任务实例运行失败”、“周期任务实例完成时间”等监控项，对其也同样生效。可以像配置普通SQL周期任务一样，配置监控规则来对其运行状态和耗时等进行监控。
+
+![](.topwrite/assets/image_1752131374833.png =680)
+
+### 组合任务触发质量规则校验
+
+在配置数据质量规则时，于规则运行触发方式中，可选择组合任务作为调度触发对象，如下图所示。可以选择具体的子任务来触发；若“子任务”留空，则会在组合任务整体运行完成后触发。
+
+![](.topwrite/assets/image_1752131279717.png =680)
+
+## 注意事项
+
+1. **类型限制**：组合任务的子任务，仅支持周期任务（离线同步、SQL等），实时任务（多表实时同步、Continuous Job等）不可添加。
+2. **参数作用域**：组合任务参数仅内部可见，不能被其他组合任务使用。跨组合任务共享参数，需通过任务组参数等来承接。
+3. **版本管理**：组合任务仅支持“提交版本”（无保存版本），暂不支持版本回滚。
+4. **任务依赖**：在任务组内，组合任务作为整体存在，不可单独添加任务组内部的子任务，且依赖关系为组合任务整体与其他任务的依赖。组合任务的内部子任务不能依赖任务组内其他任务，也不能被任务组内其他任务依赖。
+
+^

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

@@ -0,0 +1,11 @@
+# 将数据导入云器 Lakehouse 的完整指南
+
+## 数据入仓：通过第三方工具
+
+### 参考资料
+
+[通过Airbyte将数据加载到Lakehouse](ELTModernDataStack.md)
+
+[将八爪鱼采集到的数据通过MySQL协议加载到Lakehouse](simpletosimple_bazhuayu_datagpt.md)
+
+[通过Bluepipe实现Oracle数据库到云器Lakehouse的实时数据同步](BluepipeOracleLakehouse_DataSync.md)

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

@@ -0,0 +1,48 @@
+# 将数据导入云器 Lakehouse 的完整指南
+
+## 数据入湖：通过数据库客户端 DBV/SQLWorkbench PUT 文件的方式
+
+#### 概述
+
+PUT 命令是 Lakehouse SQL 中的一个实用工具，用于将客户端主机的本地文件上传到 Lakehouse 的数据湖 Volume 对象中。通过该命令，用户可以轻松地将本地文件传输至云端，实现数据的快速迁移和同步。要执行 PUT 命令，您可以使用 sqlline 工具或数据库管理工具。
+
+#### 使用场景
+
+* 将本地文件上传到数据湖 Volume 对象。
+* 快速迁移和同步本地与云端数据。
+
+#### 实现步骤
+
+##### 下载安装 DBV
+
+本指南示例数据库管理工具使用 [DbVisualizer Free版](https://www.dbvis.com/)。如已安装请跳过。
+
+下载云器 Lakehouse 的 [JDBC Driver](JDBC-Driver.md) 到本地。
+
+在 DBV 中安装 Lakehouse 的 JDBC Driver。
+
+##### 在 DBV 中新建 Database
+
+建立与云器 Lakehouse 的连接。
+
+##### 新建 SQL Script 并运行
+
+```SQL
+PUT 'data/lift_tickets_data.csv.zip' TO volume ingest_demo  FILE 'gz/lift_tickets_data_put.csv.zip';SHOW  VOLUME DIRECTORY ingest_demo;
+```
+
+##### ![](.topwrite/assets/image_1736215162253.png =531)
+
+##### 检查 PUT 结果
+
+```SQL
+SHOW  VOLUME DIRECTORY ingest_demo;
+```
+
+#### 资料
+
+[SQL PUT 命令](PUT.md)
+
+[JDBC Driver](JDBC-Driver.md)
+
+[数据库管理工具](data-mamager-tool.md)