@clickzetta/cz-cli-darwin-x64 0.3.1

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

@@ -0,0 +1,463 @@
+# 多表离线同步任务
+
+## 功能概述
+
+多表离线同步任务是云器 Lakehouse Studio 提供的批量数据同步能力，支持将源端数据库的整库或多张表以周期调度的方式同步到 Lakehouse 中。与多表实时同步任务不同，多表离线同步采用定期全量同步的方式，适合数据时效性要求相对不高、数据更新具有周期性特征的场景。
+
+## 适用场景
+
+多表离线同步任务适用于以下场景：
+
+* **整库迁移**：需要将源端数据库的所有表批量同步到 Lakehouse，减少逐表配置的工作量
+* **周期性数据更新**：源端数据按固定周期（如每天、每小时）批量更新，无需保持实时同步
+* **分库分表合并**：需要将多个分库分表的数据合并同步到统一的目标表
+* **定期数据校准**：通过周期性全量同步确保目标端数据与源端保持一致
+* **资源优化**：在数据时效性要求不高的情况下，通过离线同步降低资源消耗。
+
+## 功能特性
+
+### 支持的数据源
+
+**来源端**
+* MySQL
+* PostgreSQL
+* SQL Server
+* Aurora MySQL
+* Aurora PostgreSQL
+* PolarDB MySQL
+* PolarDB PostgreSQL
+
+**目标端**
+* Lakehouse
+
+### 同步模式
+
+1. **整库镜像**：同步源端整个数据库的所有表到目标端。
+2. **多表镜像**：选择源端多张表同步到目标端，保持表结构独立。
+3. **多表合并**：将多个源表（如分库分表）合并同步到一张表或多张目标表。
+
+### 核心能力
+
+* **自动建表**：目标端表不存在时自动创建，支持主键表和非主键表，支持灵活使用参数来定制目标端表的命名。
+* **Schema变更适配**：支持源端表结构变化时自动同步到目标端（可选）。
+* **灵活的写入模式**：支持覆盖写入（overwrite）、更新写入（upsert）等多种写入模式。
+* **并发控制**：支持配置分组策略和并发度，以优化同步性能并灵活控制对源端的压力。
+* **调度管理**：基于Cron表达式的灵活调度配置，可与其他任务节点统一编排。
+
+## 操作步骤
+
+### 第一步：创建任务
+
+![](/.topwrite/assets/image_1763375029154.png =680)
+
+1. 在Lakehouse Studio开发模块中，点击「新建」按钮
+2. 在任务类型中选择「多表离线同步」（位于"数据同步"分组下）
+3. 输入任务名称、选择文件夹
+
+### 第二步：配置来源数据
+
+#### 选择数据源类型
+
+![](/.topwrite/assets/image_1763375044630.png =680)
+
+在"数据源类型"区域，选择源端和目标端的数据源类型：
+
+* 来源端：选择需要同步的数据库类型（如PostgreSQL、MySQL等）
+* 目标端：选择Lakehouse
+
+#### 选择来源数据源
+
+1. 在"来源数据源"下拉框中选择已配置的数据源连接
+2. 系统会自动加载该数据源下的数据库列表
+
+#### 配置同步对象
+
+根据您的需求选择同步对象：
+
+**整库镜像模式**
+
+* 选择整个数据库进行同步
+* 系统会自动同步该数据库下的所有表
+
+**多表镜像模式**
+
+* 展开数据库和Schema结构
+* 勾选需要同步的表
+* 支持按数据库、Schema、表三个层级进行批量选择
+
+**多表合并模式**
+
+* 额外配置虚拟表，以表达源端多张表到目标表的合并关系
+* 支持按数据库、Schema、表三个层级进行批量配置规则，以圈选源端数据表范围，并合并到目标同一张表中
+
+**同步对象筛选**
+
+* 可使用搜索框快速定位表
+* 支持按已选/Schema/表进行过滤查看
+* 右上角会统计显示已选择的对象数量（如“已选：数据库3 表45”）
+
+  ![](/.topwrite/assets/image_1763375059693.png =680)
+
+### 第三步：配置目标设置
+
+#### 选择目标数据源
+
+在"数据源类型"区域选择目标Lakehouse数据源
+
+#### 配置目标数据源
+
+1. 选择目标workspace（数据空间）
+2. 配置目标命名空间（Schema）
+
+#### 命名空间规则
+
+系统提供三种命名规则：
+
+* **镜像来源**：保持与源端Schema名称一致
+* **指定选择**：手动选择一个已存在的目标Schema
+* **自定义**：使用规则表达式自定义目标Schema名称
+
+**规则表达式说明**
+
+* 支持使用变量：
+
+  * `{SOURCE_DATABASE}`表示源端数据库名称。
+
+* 支持使用自定义任务参数：
+
+  * `比如${bizdate}`等。任务参数的使用详见：[任务参数](task_param.md)
+
+* 示例：`{SOURCE_DATABASE}_${bizdate}`
+
+#### 目标表命名规则
+
+配置目标表的命名规则：
+
+* **镜像来源**：保持与源端表名一致
+* **自定义**：使用规则表达式自定义目标表名
+
+**规则表达式说明**
+
+* 支持使用变量：
+
+  * `{SOURCE_DATABASE}`表示源端数据库名称，`{SOURCE_SCHEMA}`表示源端Schema名称，`{SOURCE_TABLE}`表示源端表名。
+
+* 支持使用自定义任务参数：
+
+  * `比如${bizdate}`等，任务参数的使用详见：[任务参数](task_param.md)
+
+* 示例：`{SOURCE_DATABASE}_{SOURCE_TABLE}_${bizdate}`
+
+#### 分区配置（可选）
+
+如需创建分区表，可配置：
+
+* 是否创建为分区表
+* 分区字段选择
+* 分区值表达式
+
+### 第四步：配置映射关系
+
+![](/.topwrite/assets/image_1763375076182.png =680)
+
+#### 查看同步对象
+
+系统会展示所有配置的同步对象及其映射关系：
+
+* 左侧显示源端表列表
+* 中间显示字段级映射详情
+* 右侧显示目标表的完整路径
+
+#### 字段映射
+
+* 系统自动识别主键（标记为PK）
+* 展示字段类型映射关系
+* 支持查看每个表的详细字段映射
+
+统计信息会显示：
+
+* 映射成功的对象数量
+* 映射失败的对象数量（如有）
+
+### 第五步：配置同步规则
+
+#### 来源数据规则
+
+**来源数据删除字段**
+
+* 继续同步，删除的字段写入Null空值
+
+**来源数据新增字段**
+
+* 自动适配，在目标表新增字段
+
+**来源数据删除表**
+
+* 自动适配，继续同步，忽略已删除的表
+
+#### 分组策略
+
+控制同步任务的分组和并发执行：
+
+**智能分组**
+
+* 系统根据表大小等特征自动分组
+
+**静态分组**
+
+* 按固定的表数量进行分组
+* 可配置单个分组中的表个数
+
+  ![](/.topwrite/assets/image_1763375092075.png =680)
+
+#### 并发控制
+
+**单分组中表个数**
+
+* 在静态分组模式下手动指定
+* 控制单个分组包含的表数量
+* 默认值：4
+
+**单分组中源端最大连接数**
+
+* 限制单个分组对源端的最大并发连接数
+* 默认值：4
+
+**并发执行的分组数量**
+
+* 可同时执行的分组数量
+* 默认值：2
+
+> **性能调优建议**：并发度过高可能对源端数据库造成压力，建议根据源端数据库性能进行合理配置。
+
+#### 数据写入模式
+
+针对不同表类型配置写入策略：
+
+**非主键表写入模式**
+
+* **覆盖写入（overwrite）**：每次同步清空目标表后写入新数据
+
+**主键表写入模式**
+
+* **覆盖写入（overwrite）**：每次同步清空目标表后写入新数据
+* **更新写入（upsert）**：基于主键进行插入或更新操作
+
+### 第六步：任务调试（可选）
+
+完成任务配置并保存后，会进入任务概览页面，如下图：
+![](/.topwrite/assets/image_1763375133438.png =680)
+
+页面右上角的「运行」按钮提供了调试运行功能，可用于验证数据源和任务配置是否正确。触发运行后，可在页面右下角的「运行历史」中查看运行详情。
+
+> 请特别注意，为了控制验证的同步时长，在运行时，系统自动增加了对源端每张表默认只抽取 1000 条数据的限制（也可以手动调整，最多 10000 条）。如果要全量同步所有的数据，请参考后续步骤配置周期定时调度。
+
+### 第七步：配置调度属性
+
+![](/.topwrite/assets/image_1763375144107.png =680)
+
+点击「调度」按钮，可以配置任务的周期调度规则：
+
+1. **调度周期**：按需选择周期调度的频次，比如每天调度、每小时调度等
+
+2. **调度周期配置**：
+   1. 支持小时、天、周、月等多种周期。
+   2. 可使用可视化配置（系统会自动转化为 Cron 表达式）。
+
+3. **生效日期和失效日期**：设置任务调度的起止日期
+
+4. **依赖配置**：设置任务的上下游依赖关系（可选）
+
+5. **其它配置**：实例信息等配置，和普通任务的周期调度配置一样。
+
+### 第八步：提交任务
+
+![](/.topwrite/assets/image_1763375154481.png =680)
+
+1. 完成配置后点击「提交」按钮
+2. 系统会进行配置验证
+3. 提交成功后任务进入调度系统，按设定周期自动执行
+
+## 任务运维
+
+在「任务运维」中，多表离线同步任务归类的「周期任务」分类下。点击任务名称可以下钻查看任务的详细信息。
+
+![](/.topwrite/assets/image_1763375175483.png =680)
+
+### 任务详情
+
+在任务详情页可以查看：
+
+**任务详情Tab**
+
+* 展示任务上下游依赖关系的DAG图
+* 任务配置信息
+* 调度配置
+* 责任人信息
+
+**任务实例Tab**
+
+* 展示任务的全部实例列表，包含手动触发的临时运行和定时调度运行的周期实例
+* 点击具体的实例
+
+  ![](/.topwrite/assets/image_1763375189472.png =680)
+
+**节点代码Tab**
+
+* 任务配置信息的代码化展示
+
+**同步对象Tab**
+
+* 查看任务中配置的所有源表和目标表
+* 查看字段映射关系
+* 实时反映当前配置状态
+
+**操作日志Tab**
+
+* 展示对于任务的暂停启动、上线更新等运维操作的审计信息
+
+### 任务操作
+
+**编辑**：
+
+* 快速跳转任务开发界面去修改任务配置
+
+**暂停/恢复**：暂停或恢复周期调度
+
+**下线**：
+
+* 停止任务并从调度系统中移除，任务回退到未提交（调度）的状态。
+* **下线（含下游）**：使用此功能可以将当前任务及其下游任务一并下线。如果任务有下游依赖，则不允许单独下线该任务。
+
+**补数据**：
+
+* 对历史周期进行数据补录
+
+### 实例管理
+
+#### 实例列表
+
+每次任务执行会生成一个实例，在「任务运维」->「实例运维」Tab下，可以查看到多表离线同步任务的任务实例。
+
+![](/.topwrite/assets/image_1763375203084.png =680)
+
+#### 实例详情
+
+点击实例ID，可以查看到实例的详细信息：
+
+![](/.topwrite/assets/image_1763375213755.png =680)
+
+**实例详情Tab**
+
+* 本次实例的上下游DAG任务血缘关系
+* 实例状态、开始时间、结束时间
+* 运行时长统计
+
+**同步对象Tab**
+
+![](/.topwrite/assets/image_1763375221058.png =680)
+
+* 查看本次执行中同步的所有表
+* 显示每张表的读取行数、写入行数、同步速率
+* 展示各表的执行状态
+
+**脚本内容Tab**
+
+* 本次实例，任务配置信息的代码化展示
+
+**执行日志Tab**
+
+* 查看详细的执行日志
+* 包括初始化、表同步、完成等阶段的日志信息
+
+**操作日志Tab**
+
+* 展示实例的重跑、置成功/置失败等运维操作的审计日志
+
+#### 实例操作
+
+**重跑**
+
+* 重新执行该实例
+* 支持选择重跑范围：
+  * 全部对象：重新同步所有表
+  * 仅失败对象：只重跑同步失败的表
+
+**置成功/置失败**
+
+* 手动设置实例的最终状态
+
+**取消运行**
+
+* 强制终止正在运行的实例
+
+**单表操作**（在同步对象Tab中）
+
+![](/.topwrite/assets/image_1763375229763.png =680)
+
+* 查看同步详情：查看单张表的同步详情
+* 重新同步：仅重新同步该表
+* 强制停止：终止该表的同步
+
+### 监控告警
+
+#### 配置告警规则
+
+多表离线同步整体，可以跟其他周期任务配置一样的监控告警。也可针对同步任务中的单表额外配置告警：
+
+**告警项：任务实例失败**
+
+* 告警类型：事件告警
+* 触发条件：整个任务实例执行失败
+* 支持配置告警过滤条件
+
+**告警项：多表离线同步单表同步失败**
+* 告警类型：事件告警
+* 触发条件：任务中任一目标表同步失败
+* 告警粒度：以目标表为单位，每张失败的表独立触发告警
+* 支持配置告警接收人和通知方式
+
+## 注意事项
+
+### 权限要求
+
+* **源端权限**：在数据源中配置的账号需要具备读取源端数据库元数据和表数据的权限（SELECT 权限）。
+* **目标端权限**：任务的负责人需要具备在目标端 Lakehouse 创建表和插入数据的权限（CREATE、INSERT 权限）。
+
+### 性能考虑
+
+1. **源端压力**：合理配置并发度，避免对源端数据库造成过大压力。
+2. **初始化时间**：首次执行时需要初始化所有同步对象，可能耗时较长。
+3. **表数量限制**：建议单个任务同步的表数量控制在合理范围，过多表可能影响任务执行效率。
+
+### 数据一致性
+
+1. **覆盖写入模式**：采用覆盖写入时，每次执行会完全刷新目标表数据。
+2. **更新写入模式**：采用upsert模式时，基于主键进行增量更新。
+3. **源端数据变化**：离线同步采用定期全量同步，两次同步间隔期间的数据变化会在下次同步时体现。
+
+### Schema Evolution限制
+
+启用Schema Evolution功能时需注意：
+
+* 不支持修改主键字段（Lakehouse主键表限制）
+* 字段类型修改仅支持同类型扩展（如 int8 → int16 → int32 → int64）
+* 跨类型转换（如 int → double）不支持
+* 建议在源端Schema相对稳定时使用此功能
+
+### 最佳实践
+
+1. **任务粒度**：根据业务关联性和同步需求合理划分任务粒度
+2. **调度时间**：选择源端数据库压力较小的时间窗口执行
+3. **测试验证**：使用"运行"功能进行小批量数据测试后再正式调度
+4. **监控配置**：及时配置告警规则，确保同步异常时能快速感知
+5. **定期检查**：定期查看"表自动变更记录"，了解Schema变更情况
+
+## 相关文档
+
+* [任务开发](ide.md)
+* [数据源连接配置](config-datasource.md)
+* [调度管理](task_scheduling.md)
+* [任务和实例运维](task-instance-maintenance.md)
+
+如有其他问题，请联系技术支持或查阅完整产品文档。