文档中心

大数据研发治理套件

高级参数

配置 ByteHouse CDW 高级参数

本文将为您介绍 DataSail 读写 ByteHouse CDW 时可配置的高级参数，涵盖 CDC Source 和 Sink 两侧，可以帮助您提升数据同步的实时性、优化吞吐量，并解决日常运维问题。

Source 参数（读取侧）

本章节详细介绍 ByteHouse CDW CDC Source 在读取数据时可供配置的高级参数。

job.reader.initial_offset_type

参数概述
- 参数名：job.reader.initial_offset_type
- 适用范围：Source
- 单位：无
- 默认值：latest
- 核心作用：定义 CDC 作业首次启动且没有可恢复状态（Checkpoint/Savepoint）时，从哪个位点开始读取数据变更日志。
适用场景
- 场景一：只关心增量数据
  - 典型现象：作业启动后，只需要处理从启动时刻开始的新增或变更数据，历史存量数据无需同步。
  - 建议：使用默认值 latest。
- 场景二：需要全量+增量同步
  - 典型现象：首次同步时，需要将源端表的全部历史数据同步到下游，并在完成后继续消费增量数据。
  - 建议：设置为 earliest。这会从数据源可追溯的最早位点开始读取，可能产生大量历史数据读取，请确保下游有能力处理。
- 场景三：从精确位置启动或失败后重跑
  - 典型现象：作业因故失败，或需要从一个已知的特定时间点/事件点（BSN, Bytehouse Sequence Number）重新开始消费。
  - 建议：设置为 specified，并配合 job.reader.initial_offset_props 参数指定每个表的具体位点。
调参建议 / 推荐配置
- 默认推荐（增量场景）：
  - job.reader.initial_offset_type: "latest"
  - 保持默认即可，这是最常见的配置，避免了历史数据的扫描开销。
- 全量同步场景：
  - job.reader.initial_offset_type: "earliest"
  - 注意：这会导致作业启动时对源端产生较大的读取负载，请评估源端性能并规划好同步时间窗口。
- 精确回溯/断点重跑：
  - job.reader.initial_offset_type: "specified"
  - job.reader.initial_offset_props: {"your_db.your_table1": 1234567890, "your_db.your_table2": 2345678901}
  - BSN 值需要从 ByteHouse 的系统表或日志中获取，此操作通常由具备运维经验的工程师执行。
参数联动
- job.reader.initial_offset_props：
  - 当且仅当 job.reader.initial_offset_type 设置为 specified 时，此参数才生效。它是一个 Map<String, Long> 结构，其中 key 是数据库和表的完全限定名（如 db_name.table_name），value 是要启动的 BSN 位点。
  - 如果 initial_offset_type 为 specified，但 initial_offset_props 中未包含某个表的条目，则该表会自动回退到 latest 模式启动。
FAQ（用户提问）
- 问：为什么我的 CDC 作业启动了，但是没有同步历史数据？
  - 答：很可能是因为 job.reader.initial_offset_type 保持了默认值 latest。此模式下，作业只会从启动时刻开始消费新的变更。如需同步历史数据，请将其设置为 earliest。
- 问：设置为 earliest 后作业启动非常慢，并且源端负载很高，怎么办？
  - 答：这是正常现象。earliest 模式会读取全部历史数据，对于大表来说会产生巨大的读 IO 和网络流量。建议在业务低峰期执行首次全量同步。如果源端无法承受压力，可以考虑先通过批量任务或其他方式导出历史数据，然后将 CDC 作业设置为 latest 来处理增量。
- 问：这个参数可以用来控制作业运行中的读取位点吗？
  - 答：不可以。此参数仅决定作业 首次启动 时的初始位点。一旦作业成功启动并生成了 Checkpoint，后续的位点管理将完全由 Flink 的 Checkpoint/Savepoint 机制接管。作业从失败恢复时，会从最新的 Checkpoint 记录的位点继续，而不是再次读取此参数。
注意事项
- 一次性参数：本参数仅在作业第一次启动时生效。后续的位点管理依赖 Flink Checkpoint。
- 资源评估：使用 earliest 模式前务必评估源端数据库的性能和网络带宽，避免对线上业务造成冲击。
- specified 模式的复杂性：使用 specified 模式需要准确获取 BSN，操作不当可能导致数据丢失或重复。这通常用于专业的故障恢复场景。
总结说明job.reader.initial_offset_type 参数用于决定 CDC 作业首次启动时的数据读取起点。使用默认值 latest 可实现纯增量同步；设置为 earliest 则会进行全量历史数据同步；若需从特定位点恢复，可使用 specified 并配合 job.reader.initial_offset_props 参数。请注意，这是一个仅在作业首次启动时生效的初始化参数。

job.reader.initial_offset_props

参数概述
- 参数名：job.reader.initial_offset_props
- 适用范围：Source
- 单位：无
- 默认值：无
- 核心作用：在 job.reader.initial_offset_type 设置为 specified 时，为一张或多张表提供精确的 CDC 启动位点（BSN）。
适用场景
- 场景一：从指定位点恢复失败作业
  - 典型现象：CDC 作业因逻辑错误或下游问题处理了一批错误数据，需要从故障发生前的某个精确 BSN 位点重新消费。
  - 处理方式：通过监控或日志找到故障前的安全 BSN，配置此参数进行精确回溯。
- 场景二：分阶段、分表启动同步任务
  - 典型现象：一个同步任务包含多张表，但希望它们从不同的历史时间点开始同步。
  - 处理方式：为每张表在 initial_offset_props 中指定不同的 BSN。
调参建议 / 推荐配置
- 配置格式：这是一个 JSON Map 结构，键（Key）为表的完全限定名 database.table，值（Value）为长整型的 BSN。
```
"job.reader.initial_offset_props": {
  "sales.orders": 1672502400000,
  "inventory.products": 1672512400000
}
```
- 获取 BSN：BSN 是 ByteHouse 内部的序列号，需要通过查询系统表或联系技术支持获取。切勿随意填写。
参数联动
- job.reader.initial_offset_type：此参数强依赖于 initial_offset_type 被设置为 specified。如果 initial_offset_type 为 latest 或 earliest，则 initial_offset_props 会被完全忽略。
- 回退逻辑：如果在 specified 模式下，initial_offset_props 中没有提供某张表的条目，那么该表将自动回退到 latest 模式，即从作业启动时开始消费增量。
FAQ（用户提问）
- 问：我配置了 initial_offset_props，为什么没有生效？
  - 答：请检查 job.reader.initial_offset_type 是否已正确设置为 specified。同时，确认 Map 中的键 database.table 与您的实际库表名完全匹配（包括大小写）。
- 问：如果我填写的 BSN 已经被清理了怎么办？
  - 答：如果指定的 BSN 因为超过了 ByteHouse 的日志保留期而被清理，作业启动时会因找不到起始位点而失败。此时需要重新评估一个在有效期内的、更近的 BSN。
注意事项
- 精确性要求：库名和表名必须完全准确，任何拼写错误都会导致该条配置失效。
- BSN 的有效性：确保您使用的 BSN 仍然在源端 ByteHouse 的可查询范围内。
- 专家级参数：这是一个用于精细化控制的专家级参数，常规场景下很少使用。请在完全理解其作用和风险后谨慎操作。
总结说明job.reader.initial_offset_props 是一个高级参数，当且仅当 job.reader.initial_offset_type 为 specified 时生效。它允许您为 CDC 作业中的一张或多张表提供精确的启动位点（BSN），主要用于专业的故障恢复和数据回溯场景。使用此参数需要准确提供“库名.表名”和对应的 BSN 值。

job.reader.scan_split_size

参数概述
- 参数名：job.reader.scan_split_size
- 适用范围：Source
- 单位：行数
- 默认值：10000
- 核心作用：控制 CDC 作业从 ByteHouse 拉取数据时每个批次（Split）的大小。
适用场景
- 场景一：源端压力大或网络不稳定
  - 典型现象：CDC 作业运行时，源端 ByteHouse 负载过高，或者因单次请求数据量太大导致网络超时。
  - 常见报错关键字：Timeout waiting for response, Connection reset by peer
  - 建议：适当调小此值，例如 2048 或 4096。减小单次拉取的数据量可以降低对源端的瞬时压力和网络传输压力。
- 场景二：追求更高吞吐量
  - 典型现象：源端负载空闲，网络条件良好，希望提升数据同步的整体吞吐。
  - 建议：适当调大此值，例如 32768 或 65536。增大批次可以减少拉取数据的请求次数，从而降低 RPC 开销，提升吞吐。
调参建议 / 推荐配置
- 默认推荐：10000 是一个较为均衡的默认值，适用于大多数场景。
- 吞吐优先：在资源允许的情况下，可以逐步增大此值，并观察源端负载和作业吞吐指标，找到最佳平衡点。
- 稳定性优先：在遇到超时或源端压力问题时，应果断调小此值。
参数联动
- job.reader.cdc_retry_times：当单次拉取（受 scan_split_size 影响）失败时，系统会进行重试。如果调大了 scan_split_size 导致超时概率增加，可能也需要关注重试次数的配置。
FAQ（用户提问）
- 问：这个值是不是越大越好？
  - 答：不是。虽然更大的批次可以减少 RPC 次数，但也意味着单次请求需要更长的处理时间和更大的内存占用（在源端和客户端）。过大的值可能反而因为频繁的超时和重试导致性能下降，甚至影响源端服务的稳定性。
注意事项
- 调整此参数是在“降低单次请求压力”与“减少总请求次数”之间做权衡。
- 修改前请务必评估源端 ByteHouse 的承载能力。
总结说明job.reader.scan_split_size 参数控制 CDC 作业从 ByteHouse 拉取数据时每个批次的大小（行数），默认值为 10000。您可以根据需求调整此参数以平衡源端负载和同步吞吐量：为保护源端或解决超时问题，请适当调小该值；为在网络良好且源端空闲时提升吞吐，可适当调大。这是一个在降低单次请求压力与减少请求频率之间进行权衡的关键参数。

job.reader.cdc_retry_times & job.reader.cdc_retry_interval_ms

参数概述
- 参数名：job.reader.cdc_retry_times / job.reader.cdc_retry_interval_ms
- 适用范围：Source
- 单位：cdc_retry_times (次) / cdc_retry_interval_ms (毫秒)
- 默认值：cdc_retry_times: 5 / cdc_retry_interval_ms: 1000
- 核心作用：定义 CDC Source 在拉取数据遇到可重试错误（如网络抖动、临时服务不可用）时的重试策略。
适用场景
- 场景一：网络环境不稳定
  - 典型现象：作业日志中频繁出现因网络瞬断或临时连接问题导致的拉取失败。
  - 常见报错关键字：ConnectException, SocketTimeoutException
  - 建议：适当增加 job.reader.cdc_retry_times 的值，例如 10 或 20，以提高任务对网络抖动的容忍度。可以同时略微增加 cdc_retry_interval_ms（如 5000）来避免过于频繁的重试冲击。
- 场景二：希望作业快速失败
  - 典型现象：对于一些监控或告警类任务，希望在遇到连接问题时能尽快失败并触发报警，而不是长时间等待重试。
  - 建议：减小 job.reader.cdc_retry_times 的值，例如 1 或 0。
调参建议 / 推荐配置
- 默认推荐：cdc_retry_times: 5, cdc_retry_interval_ms: 1000。这套默认配置提供了一个合理的容错窗口（总计约 5-6 秒的重试时间），能应对大部分短暂的网络问题。
- 高容错场景：
  - job.reader.cdc_retry_times: 30
  - job.reader.cdc_retry_interval_ms: 10000 (10秒)
  - 这样的配置会让作业在长达数分钟的连接中断后仍能尝试恢复，适合稳定性要求极高的核心业务。
参数联动
- job.reader.scan_split_size：如果调大了 scan_split_size 导致单次请求耗时增加，进而增加了超时的风险，那么一个更宽松的重试策略（更大的 cdc_retry_times）可能有助于提升作业稳定性。
FAQ（用户提问）
- 问：cdc_retry_interval_ms 参数在代码中似乎没有被完全透传，它实际生效吗？
  - 答：根据代码分析，cdc_retry_times 在 CdwFlinkSourceBuilder 中被明确用于构建 CnchCdcSource，是生效的。而 cdc_retry_interval_ms 虽然在配置项中定义，但在当前的构建逻辑中可能未被直接使用，重试间隔可能由底层 CDC 连接器或框架的默认退避策略控制。尽管如此，保留此参数配置是向前兼容的良好实践。
注意事项
- 过多的重试次数和过长的间隔会延长作业在真正遇到持久性故障时的失败发现时间。
- 无限制的重试可能掩盖更严重的网络或服务问题。
总结说明job.reader.cdc_retry_times 参数用于设定 CDC Source 在遇到网络抖动等可恢复的拉取错误时的最大重试次数，默认值为 5 次。您可以根据网络稳定性与故障恢复的期望，适当调大此值以提升任务容错性，或调小它以实现快速失败。此参数与 job.reader.cdc_retry_interval_ms（重试间隔）共同决定了作业在因临时性问题而彻底失败前的总容忍时长。

job.reader.src_meta_info_column_enabled & job.reader.src_meta_info_column_name

参数概述
- 参数名：job.reader.src_meta_info_column_enabled / job.reader.src_meta_info_column_name
- 适用范围：Source
- 单位：无
- 默认值：src_meta_info_column_enabled: false / src_meta_info_column_name: _src_meta_info_
- 核心作用：控制是否在输出的数据流中，额外附加一列包含丰富源端元信息的 JSON 字符串。
适用场景
- 场景一：需要进行数据溯源或问题排查
  - 典型现象：下游发现脏数据，需要追溯其在源端的原始信息，如来源库、表、BSN（位点）等。
  - 建议：设置 job.reader.src_meta_info_column_enabled: true。
- 场景二：下游需要根据 CDC 操作类型进行逻辑分流
  - 典型现象：ETL 逻辑需要区分处理 INSERT、UPDATE、DELETE 操作，例如将 DELETE 事件写入单独的归档表。
  - 建议：开启此参数，并解析元数据列中的 message_type 或 row_kind 字段。
- 场景三：下游需要事件发生时间
  - 典型现象：需要记录每条变更在源端发生的精确时间。
  - 建议：开启此参数，并解析元数据列中的 timestamp 字段。
调参建议 / 推荐配置
- 默认关闭：为了减少不必要的数据传输量和下游处理的复杂性，该功能默认关闭。
- 按需开启：
  - job.reader.src_meta_info_column_enabled: true
  - job.reader.src_meta_info_column_name: "my_cdc_meta" (可选，自定义列名)
- 开启后，输出的 Row 中会增加一列，其内容为类似如下的 JSON 字符串：
```
{
  "db": "my_db",
  "table": "my_table",
  "bsn": 1234567890123,
  "message_type": "INSERT",
  "timestamp": 1672531200000
}
```
参数联动
- job.reader.meta_db_seq_enabled：如果开启了元数据列，并且此参数也为 true（默认），元数据中还会包含一个 db_seq 字段，用于标识数据源于哪个数据库（按配置顺序的索引）。
注意事项
- 开启此功能会略微增加数据量的大小。
- 下游需要有能力解析 JSON 字符串来获取所需的元信息。
总结说明job.reader.src_meta_info_column_enabled 参数控制是否在 CDC 数据流中附加一列包含源端元数据（如数据库名、表名、操作类型、BSN等）的 JSON 字符串。当您需要进行数据溯源、实现依赖于操作类型（增/删/改）的复杂 ETL 逻辑或进行数据审计时，应将此参数设为 true。您还可以通过 job.reader.src_meta_info_column_name 自定义该元数据列的名称。

job.reader.meta_db_seq_enabled

参数概述
- 参数名：job.reader.meta_db_seq_enabled
- 适用范围：Source
- 单位：无
- 默认值：true
- 核心作用：在多数据库同步场景下，控制是否在 CDC 元数据中添加一个名为 db_seq 的字段。该字段是一个从 0 开始的整数，用于唯一标识事件来源于哪个数据库。
适用场景
- 场景一：多数据库到单目标的数据合并
  - 典型现象：一个 DataSail 作业同时从多个 ByteHouse CDW 数据库（如 marketing_db, sales_db）中读取表，并写入到同一个下游系统。下游需要一种高效的方式来区分和路由来自不同源库的数据。
  - 建议：保持默认值 true。下游可以直接使用 db_seq 字段（0, 1, 2...）作为分区键、索引或路由逻辑的判断依据，这比直接比较字符串形式的库名更高效。
- 场景二：单数据库同步或下游不关心来源库
  - 典型现象：作业只从一个数据库读取数据，或者下游的处理逻辑与数据来源库无关。
  - 建议：可以设置为 false 以减少元数据的大小，但通常保持默认值也无妨。
调参建议 / 推荐配置
- 默认推荐：保持 true。这是一个低开销但高价值的元数据字段，尤其在未来可能扩展到多库同步时，能提供很好的扩展性。
- 配置示例：
```
"job.reader.meta_db_seq_enabled": true
```
- 开启后，_src_meta_info_ 列的 JSON 内容将包含 db_seq：
```
{
  "db": "sales_db",
  "table": "orders",
  "db_seq": 1, 
  ...
}
```
参数联动
- job.reader.src_meta_info_column_enabled：meta_db_seq_enabled 必须在 src_meta_info_column_enabled 为 true 的前提下才能生效。如果元数据列本身被禁用了，db_seq 也就无处安放。
- job.reader.database_include_list：db_seq 的值与数据库在 database_include_list 中出现的顺序相关。列表中的第一个数据库对应的 db_seq 为 0，第二个为 1，以此类推。
注意事项
- db_seq 的值依赖于配置中数据库列表的顺序。如果调整了 database_include_list 中数据库的顺序，同一个数据库的 db_seq 值可能会发生变化。
总结说明job.reader.meta_db_seq_enabled 参数控制是否在 CDC 事件的元数据中添加一个 db_seq 字段，用于标识事件来源于哪个数据库（根据其在配置列表中的顺序）。在多数据库同步场景下，这个从0开始的整数序列号为下游提供了稳定、高效的来源区分和排序依据。该参数默认开启，建议保持，但需确保 job.reader.src_meta_info_column_enabled 也已启用。

job.common.cdc_multiplex_record_case_insensitive

参数概述
- 参数名：job.common.cdc_multiplex_record_case_insensitive
- 适用范围：Common (主要影响 CDC Source)
- 单位：无
- 默认值：true
- 核心作用：这是一个全局性的兼容性开关，用于控制 CDC 数据在被解析和处理时，是否忽略数据库名、表名和字段名的大小写。
适用场景
- 场景一：源端库、表、字段名大小写不规范
  - 典型现象：源端数据库中同时存在 my_table 和 My_Table，或者字段有 userId 和 userid 等大小写混用的情况。在下游进行 schema 映射或处理时，希望能将它们视为同一个对象。
  - 建议：保持默认值 true。系统会自动将所有标识符转换为小写进行处理，从而屏蔽源端的大小写差异。
- 场景二：需要严格区分大小写
  - 典型现象：业务上确实需要区分 my_table 和 My_Table 这两个不同的表，它们存储的是不同业务含义的数据。
  - 建议：设置为 false。此时，系统将严格按照原始的大小写来匹配和处理库、表、字段名。
调参建议 / 推荐配置
- 强烈建议保持默认：
  - job.common.cdc_multiplex_record_case_insensitive: true
  - 在大多数数据集成场景中，忽略大小写可以避免大量因开发、建表不规范或异构系统差异带来的匹配问题，极大提升了作业的健壮性和易用性。
- 专家模式：
  - job.common.cdc_multiplex_record_case_insensitive: false
  - 仅在您完全确定需要，并且能自行处理所有严格的大小写匹配问题时，才关闭此开关。
参数联动
- 此参数会影响所有与库、表、字段名匹配相关的逻辑，包括但不限于：
  - job.reader.initial_offset_props 中的 database.table 键。
  - 下游 Sink 的 schema 映射逻辑。
  - Transform 算子中基于字段名的转换规则。
FAQ（用户提问）
- 问：为什么我的作业里有两个名字一样但大小写不同的表，结果只同步了一个？
  - 答：这正是因为 cdc_multiplex_record_case_insensitive 默认开启。系统将 my_table 和 My_Table 都处理为 my_table，导致它们被视为同一个对象。如果您确实需要区分它们，请将此参数设为 false。
注意事项
- 将此参数从 true 改为 false 可能会导致现有作业因找不到表或字段而失败，需要仔细检查并修正所有相关配置的大小写。
- 在多源异构同步链路中，保持 true 是最佳实践。
总结说明job.common.cdc_multiplex_record_case_insensitive 是一个全局性的兼容性参数，用于控制 CDC 数据同步过程中是否忽略库、表、字段名的大小写，默认值为 true（忽略大小写）。强烈建议保持此默认设置，它可以自动处理因开发不规范或异构数据库差异引起的大小写不匹配问题。仅在您需要严格区分如 myTable 和 mytable 这类仅大小写不同的对象时，才考虑将其设为 false。

Sink 参数（写入侧）

本章节详细介绍 ByteHouse CDW Sink 在写入数据时可供配置的高级参数。

job.writer.atomic_write

参数概述
- 参数名：job.writer.atomic_write
- 适用范围：Sink
- 单位：无
- 默认值：false
- 核心作用：在批处理（Batch）模式下，启用原子写入功能。开启后，数据会先写入一个临时表，待作业成功结束后，通过 ATTACH PARTITION 命令将数据原子性地迁移到目标表，从而实现“all-or-nothing”的写入语义。
适用场景
- 场景一：要求批作业的端到端原子性
  - 典型现象：一个 T+1 的批处理作业，需要保证其产出的所有分区要么全部成功替换目标表中的旧分区，要么在作业失败时不产生任何影响。
  - 建议：设置为 true。这可以有效避免作业运行到一半失败，导致目标表数据处于不一致的“半新半旧”状态。
- 场景二：流式作业或对原子性无严格要求
  - 典型现象：流式作业（Streaming）持续写入，或者批处理作业可以接受在失败后通过重跑来覆盖数据。
  - 建议：保持默认值 false。非原子写入路径更简单，开销更低。流式作业会忽略此参数。
调参建议 / 推荐配置
- 批处理强一致场景：
  - job.writer.atomic_write: true
  - 注意：开启此功能要求作业所用的数据库账号拥有 CREATE TABLE 和 DROP TABLE 的权限，因为框架需要创建和清理临时表。
- 流处理或通用批处理：
  - job.writer.atomic_write: false
  - 保持默认即可。
参数联动
- job.common.job_type：atomic_write 仅在 job.common.job_type 为 BATCH 时生效。
- job.writer.atomic_write_retry_*：在原子提交阶段（ATTACH PARTITION），如果遇到可重试错误，atomic_write_retry_limits 和 atomic_write_retry_wait_millis 将控制重试行为。
- job.writer.table_name：开启原子写后，写入过程中实际操作的是一个临时表（如 __your_table_temporary_for_job_id__），table_name 指定的原始表名仅在最终提交阶段被使用。
FAQ（用户提问）
- 问：开启原子写后，作业日志里为什么提示找不到我配置的表，而去写一个奇怪名字的表？
  - 答：这是原子写正常的工作机制。它会创建一个与目标表结构相同的临时表进行写入，以隔离未完成的数据。只有在作业所有流程都成功结束后，才会将临时表中的数据分区（Partition）迁移到您的目标表中。
注意事项
- 权限要求：开启此功能需要额外的数据库权限。
- 性能开销：原子写引入了创建临时表、查询分区、迁移分区等额外元数据操作，相比直接写入会有一定的性能开销。
- 流式作业无效：此参数对流式作业（Streaming Job）不生效。
总结说明job.writer.atomic_write 参数仅在批处理（Batch）模式下生效，用于提供端到端的原子写入保证，默认关闭。当您需要确保一个批次作业的产出要么完整替换目标分区、要么在失败时完全不留痕迹，可以将其设为 true。请注意，这会带来额外的权限要求和性能开销，且对流式作业无效。

job.writer.atomic_write_retry_limits & job.writer.atomic_write_retry_wait_millis

参数概述
- 参数名：job.writer.atomic_write_retry_limits / job.writer.atomic_write_retry_wait_millis
- 适用范围：Sink
- 单位：atomic_write_retry_limits (次) / atomic_write_retry_wait_millis (毫秒)
- 默认值：atomic_write_retry_limits: 30 / atomic_write_retry_wait_millis: 10000
- 核心作用：在原子写入的最终提交阶段（即执行 ATTACH PARTITION 等命令时），如果遇到临时性、可恢复的错误，这对参数将控制系统的重试行为。
适用场景
- 场景一：原子提交阶段遇到临时故障
  - 典型现象：作业数据处理和临时表写入都已完成，但在最后一步迁移分区到目标表时，因网络抖动或协调服务短暂不可用而失败。
  - 常见报错关键字：ETIMEDOUT (Connection timed out)
  - 建议：通常无需调整。默认配置（重试 30 次，每次间隔 10 秒）提供了长达 5 分钟的重试窗口，足以应对大多数临时性问题。
调参建议 / 推荐配置
- 默认推荐：绝大多数场景下，保持默认值即可。
  - job.writer.atomic_write_retry_limits: 30
  - job.writer.atomic_write_retry_wait_millis: 10000
- 快速失败场景：如果业务上要求在提交阶段遇到问题时能尽快失败，可以缩短重试窗口，例如：
  - job.writer.atomic_write_retry_limits: 3
  - job.writer.atomic_write_retry_wait_millis: 5000
参数联动
- job.writer.atomic_write：这对参数仅在 job.writer.atomic_write 为 true 时才有意义。如果未开启原子写，它们将被完全忽略。
注意事项
- 这组参数只对原子提交阶段的特定可重试错误生效。对于如“权限不足”、“表不存在”等确定性错误，系统不会进行重试。
总结说明job.writer.atomic_write_retry_limits 和 job.writer.atomic_write_retry_wait_millis 这组参数仅在启用原子写入（atomic_write=true）时生效。它们用于控制在向事务协调器发起全局提交的阶段，如果遇到网络超时等临时性错误时的重试策略。默认配置提供了长达5分钟的重试窗口（重试30次，每次间隔10秒），足以应对大多数临时故障，通常无需修改。

job.writer.buffer_count & job.writer.flush_interval

参数概述
- 参数名：job.writer.buffer_count / job.writer.flush_interval
- 适用范围：Sink
- 单位：buffer_count (行数) / flush_interval (毫秒)
- 默认值：buffer_count: 8192 / flush_interval: 60000
- 核心作用：共同控制 Sink 端内存缓冲区的刷写（Flush）时机。当缓冲区中的数据行数达到 buffer_count，或者自上次刷写以来的时间超过 flush_interval，就会触发一次从内存到 ByteHouse 的实际写入操作。
适用场景
- 场景一：追求更高的数据写入实时性
  - 典型现象：数据写入下游后，需要尽快可见。
  - 建议：适当调小 job.writer.flush_interval，例如 5000 (5秒) 或 10000 (10秒)。这会使数据在内存中停留的时间更短。
- 场景二：提升写入吞吐量，降低服务端压力
  - 典型现象：源端数据量巨大，希望最大化单次写入的效率，减少与 ByteHouse 的交互次数。
  - 建议：适当调大 job.writer.buffer_count（如 65536）和 job.writer.flush_interval（如 120000）。这使得每次写入的批次更大，能有效利用网络和数据库资源，提升总吞吐。
- 场景三：内存资源受限
  - 典型现象：作业因内存溢出（OOM）而失败。
  - 建议：适当调小 job.writer.buffer_count，例如 4096。减少缓冲区大小可以显著降低 Sink 端的内存占用。
调参建议 / 推荐配置
- 实时性优先：
  - job.writer.flush_interval: 5000 (5s)
  - job.writer.buffer_count: 8192 (可保持默认或略微调小)
- 吞吐优先：
  - job.writer.flush_interval: 120000 (2min)
  - job.writer.buffer_count: 65536
- 均衡配置（默认）：
  - job.writer.flush_interval: 60000 (1min)
  - job.writer.buffer_count: 8192
参数联动
- 这两个参数是“或”的关系，任何一个条件满足都会触发刷写。在实际调优中，需要根据您的数据流入速率来综合考虑。
  - 如果数据流速很快，那么 buffer_count 通常会先被触发。
  - 如果数据流速很慢或有中断，那么 flush_interval 将作为兜底，确保数据不会无限期地滞留在内存中。
注意事项
- 过大的 buffer_count 会增加 Flink TaskManager 的内存消耗，请确保集群资源充足。
- 过小的 flush_interval 和 buffer_count 会导致频繁的小批量写入，增加数据库的查询（QPS）和连接压力，可能反而降低整体性能。
总结说明job.writer.buffer_count 和 job.writer.flush_interval 共同决定了数据写入 ByteHouse 的时机和批次大小。您可以根据业务需求在数据实时性、写入吞吐量和内存消耗之间进行权衡：若需降低延迟，请调小 flush_interval；若需提升吞吐，请调大 buffer_count；若内存紧张，请调小 buffer_count。

job.writer.connection_validity_timeout

参数概述
- 参数名：job.writer.connection_validity_timeout
- 适用范围：Sink
- 单位：秒
- 默认值：10
- 核心作用：在从连接池获取一个 JDBC 连接后，框架会检查该连接是否依然有效。此参数定义了这次有效性检查的最大等待时间。
适用场景
- 场景一：网络环境复杂，连接易失效
  - 典型现象：作业长时间运行后，因网络防火墙策略、负载均衡器超时或数据库端空闲连接回收等原因，持有的连接变为“僵尸连接”，导致写入失败。
  - 常见报错关键字：Broken pipe, Connection is closed
  - 建议：保持默认值 10。这确保了每次写入前都会用一个合理的超时时间来快速验证连接。如果连接失效，框架会自动尝试重新建立连接，从而提升作业的健壮性。
- 场景二：网络质量极高，希望减少检查开销
  - 典型现象：在专有网络或内部稳定环境中，连接几乎不会失效，希望消除每次检查带来的微小开销。
  - 建议：可以适当调小此值，例如 5 或 3。但不建议完全关闭或设置得过小，因为连接有效性检查是保障写入可靠性的重要一环。
调参建议 / 推荐配置
- 默认推荐：保持默认值 10 即可。这是一个在可靠性与性能之间取得良好平衡的值。
注意事项
- 此参数与 JDBC 驱动的 isValid() 方法行为相关。一个合理的超时设置可以防止作业在等待一个失效连接的响应时被长时间卡住。
总结说明job.writer.connection_validity_timeout 参数用于设定在写入数据前检查数据库连接是否仍然有效的超时时间（秒），默认值为 10。这是一个保障作业在网络不稳定环境下稳定运行的“健康检查”参数，它能帮助系统及时发现并替换掉已失效的“僵尸连接”。对于绝大多数场景，保持默认值即可。

job.writer.max_partitions_per_insert_block

参数概述
- 参数名：job.writer.max_partitions_per_insert_block
- 适用范围：Sink
- 单位：无
- 默认值：10000
- 核心作用：通过 SET max_partitions_per_insert_block = xxx 的方式，为当前会话设置单次 INSERT 操作能够涉及的最大分区数量。这是一个保护性参数，旨在防止因单次写入过于分散而触达 ByteHouse 服务端的默认限制。
适用场景
- 场景一：写入数据过于分散导致报错
  - 典型现象：作业在写入数据时失败，日志中出现 Too many partitions for single insert block 错误。
  - 处理方式：这通常意味着您的数据在单次刷写（Flush）的批次中，包含了超过 ByteHouse 默认限制（通常是 100）的分区。首先应检查上游数据或表的分区键设计是否合理，尽量提高数据写入的“局部性”。如果确认业务上确实需要一次性写入大量分区，可以调大此参数的值，例如 1000 或更高，以放宽服务端的限制。
- 场景二：常规写入
  - 典型现象：数据分布较为集中，单次写入很少触及大量分区。
  - 建议：保持默认值 10000。这个值远大于服务端默认的 100，足以应对绝大多数场景，通常无需修改。
调参建议 / 推荐配置
- 问题驱动型调整：仅在遇到 Too many partitions 错误时，才需要关注和调整此参数。
- 推荐做法：遇到此问题时，优先优化上游数据或表分区设计。如果无法优化，再根据错误日志中提示的实际分区数量，将 max_partitions_per_insert_block 设置为一个大于该值的数值。
参数联动
- job.writer.buffer_count 和 job.writer.flush_interval：这两个参数决定了刷写批次的大小和频率。一个更大的 buffer_count 可能会导致一个批次中包含更多样化的数据，从而更容易触及分区数量限制。
注意事项
- 放宽此限制会增加 ByteHouse 服务端的内存和协调开销。无限制地调大此参数可能会对服务端性能产生负面影响。
- 治本之策是优化数据模型和写入逻辑，而不是仅仅依赖放宽服务端限制。
总结说明job.writer.max_partitions_per_insert_block 参数用于限制单次写入操作能涉及的最大分区数，默认值为 10000。这是一个保护性参数，旨在防止因数据写入过于分散而导致的服务端性能问题。当您遇到 “Too many partitions for single insert block” 错误时，如果确认业务上确实需要一次性写入更多分区，可以根据实际需求调大此值。但更推荐的做法是优化上游数据或表的分区键设计，以提高数据写入的局部性。

job.writer.query_timeout

参数概述
- 参数名：job.writer.query_timeout
- 适用范围：Sink
- 单位：毫秒
- 默认值：180000 (3分钟)
- 核心作用：设置 JDBC Statement 的执行超时时间。如果在指定时间内，一个 SQL 查询（包括 INSERT）没有执行完成，客户端将主动中断它。
适用场景
- 场景一：写入大批量数据耗时较长
  - 典型现象：单次刷写的数据量非常大（例如，buffer_count 设置得很高），或者目标表结构复杂、有较重的写入时计算，导致 INSERT 语句执行时间超过默认的 3 分钟，从而引发超时失败。
  - 常见报错关键字：Query timed out
  - 建议：适当调大此值，例如 600000 (10分钟)。
- 场景二：防止作业因写入卡住而无响应
  - 典型现象：希望对最长的写入时间有一个明确的预期，避免作业因数据库端问题（如死锁、查询队列拥堵）而被无限期阻塞。
  - 建议：根据业务对写入延迟的容忍度，设置一个合理的超时时间。
调参建议 / 推荐配置
- 默认推荐：180000。对于大多数场景，3 分钟的写入超时是比较宽裕的。
- 大批量写入场景：如果您的 buffer_count 非常大，或者单条记录很大，可以相应地增加 query_timeout。一个粗略的估算方法是：在测试环境尝试一次大的 flush，观察其耗时，然后设置一个大于该耗时 2-3 倍的值作为安全边际。
注意事项
- 此超时是客户端（DataSail 作业）侧的设置，它会中断等待，但可能不会立即中止 ByteHouse 服务端正在执行的查询。
- 请将此参数与 job.writer.connection_validity_timeout（连接检查超时）和 job.writer.flush_interval（刷写间隔）区分开。
总结说明job.writer.query_timeout 参数用于设置单次数据写入 SQL 操作的最大允许执行时间（单位：毫秒），默认值为 3 分钟。当您处理超大规模数据批次或遇到写入超时错误时，可以适当调大此值。它为写入操作提供了一个“熔断”机制，防止作业因数据库长时间无响应而被永久阻塞。

job.writer.secure & job.writer.cnch_engine

参数概述
- 参数名：job.writer.secure / job.writer.cnch_engine
- 适用范围：Sink
- 单位：无
- 默认值：均为 true
- 核心作用：这对参数是用于建立到 ByteHouse CDW 的 JDBC 连接时的关键属性。
  - secure: 控制是否启用安全连接（SSL/TLS）。
  - cnch_engine: 告知驱动程序目标是 CNCH（Cloud Native ClickHouse）架构。
适用场景
- 连接标准的 ByteHouse CDW 服务：
  - 建议：必须保持这两个参数的默认值 true。这是与 CDW 服务正确、安全通信的基础。
- 连接非国密或非安全端口：
  - 典型现象：在特定的内部测试或调试环境中，需要连接一个未启用 SSL/TLS 的 ByteHouse 端口。
  - 建议：仅在这种极少数情况下，可以将 job.writer.secure 设置为 false。
- 使用此连接器连接非 CNCH 架构的数据库：
  - 典型现象：出于特殊目的，使用 CDW 连接器去连接一个开源 ClickHouse 或 ByteHouse CE 实例。
  - 建议：将 job.writer.cnch_engine 设置为 false。
调参建议 / 推荐配置
- 生产环境强烈建议：
  - job.writer.secure: true
  - job.writer.cnch_engine: true
- 任何对这两个参数的修改都应被视为专家级操作，并且需要有充分的理由。
注意事项
- 安全风险：关闭 secure 会使数据在网络中以明文传输，存在安全风险。
- 功能异常：关闭 cnch_engine 去连接一个真正的 CDW 实例，可能会导致某些依赖 CNCH 架构的功能（如原子写、多副本写入策略）行为异常或性能下降。
总结说明job.writer.secure 和 job.writer.cnch_engine 是连接 ByteHouse CDW 的两个基础性关键参数，默认均为 true。secure 确保了数据传输的安全性，cnch_engine 则保证了与 CDW 云原生架构的正确适配。在任何情况下，除非有明确的技术指导和特殊需求，您都应保持这两个参数的默认设置。

job.writer.bh_connection_properties & job.writer.session_properties

参数概述
- 参数名：job.writer.bh_connection_properties / job.writer.session_properties
- 适用范围：Sink
- 单位：无
- 核心作用：这两个参数都提供了向 ByteHouse “透传”自定义参数的能力，但作用于不同的生命周期。
  - bh_connection_properties：作用于连接建立时。其中的键值对会作为属性附加到 JDBC 连接串上。
  - session_properties：作用于每次 SQL 执行前。其中的键值对会通过 SET key = value 的方式在当前会话中生效。
适用场景
- 场景一：设置底层驱动参数
  - 典型现象：需要配置一个 BitSail 未直接封装的底层 JDBC 驱动参数，例如 sslrootcert。
  - 建议：使用 job.writer.bh_connection_properties。
- 场景二：临时调整会话级行为进行调优或调试
  - 典型现象：为了诊断一个慢查询，需要临时开启某个查询日志；或者为了提升特定 INSERT 语句的性能，需要临时关闭某个去重开关。
  - 常见参数：insert_deduplicate, enable_optimizer
  - 建议：使用 job.writer.session_properties。
调参建议 / 推荐配置
- 格式：两个参数都是 JSON Map 结构。
```
"job.writer.bh_connection_properties": {
  "sslmode": "verify-full",
  "sslrootcert": "/path/to/ca.pem"
},
"job.writer.session_properties": {
  "insert_deduplicate": "0"
}
```
- 按需使用：这两个都是高级参数，仅在您明确知道需要配置哪个具体参数时才使用。请参考 ByteHouse/ClickHouse 官方文档或在技术支持的指导下进行配置。
注意事项
- 日志暴露风险：bh_connection_properties 和 session_properties 的内容可能会被打印在作业的 INFO 级别日志中。请避免在其中放置任何敏感信息（如密码、token 等）。
- 作用域：bh_connection_properties 只在建连时生效一次；session_properties 则在每次 flush 前都可能被重新设置，作用范围是当前会话。
总结说明bh_connection_properties 和 session_properties 是两个专家级的“透传”参数，分别用于在建立连接时和执行查询前向 ByteHouse 传递自定义属性。当您需要配置 BitSail 未直接封装的底层驱动参数或临时调整会话行为时，可以使用它们。请在查阅官方文档或在技术支持指导下使用，并注意避免在其中配置敏感信息。

写入模式与 DDL 相关参数

注意

以下参数组主要控制 Sink 端的写入行为（追加 vs. 更新），以及在下游目标表不存在时，如何根据上游 schema 自动创建表（DDL）。

job.writer.write_mode & job.writer.unique_keys

参数概述
- 参数名：job.writer.write_mode / job.writer.unique_keys
- 核心作用：
  - write_mode: 定义写入模式。INSERT（默认）表示纯粹的追加写入；UPSERT 表示根据主键进行更新或插入。
  - unique_keys: 在 UPSERT 模式下，指定用于判断数据唯一性的一个或多个字段，多个字段用逗号分隔。
适用场景
- 场景一：简单的日志、事件流数据追加
  - 建议：使用默认的 job.writer.write_mode: "INSERT"。这是性能最高的模式。
- 场景二：同步业务数据库的变更数据（CDC）
  - 典型现象：源端数据会发生 UPDATE 和 DELETE，下游需要保持一致。
  - 建议：
    - job.writer.write_mode: "UPSERT"
    - job.writer.unique_keys: "id,other_unique_col"
    - 要求：目标 ByteHouse 表必须是支持 UPSERT 语义的引擎（如 CnchMergeTree 家族），并且 unique_keys 必须与表定义中的主键或唯一键一致。
注意事项
- UPSERT 模式相比 INSERT 会有额外的合并开销。
- 如果 unique_keys 未配置，系统会尝试从 Catalog 中获取表的主键定义。如果两者都没有，UPSERT 模式将无法正常工作。
总结说明write_mode 用于选择数据写入模式。对于只需追加新数据的场景，使用默认值 INSERT 可获得最佳性能。当需要同步来自业务数据库的变更（包括更新和删除）或实现数据去重时，应设置为 UPSERT，并配合 unique_keys 参数指定唯一键。UPSERT 模式强依赖于表引擎和主键定义。

DDL 自动建表参数系列

参数列表：
- job.writer.ddl_create_table_order_by_fields
- job.writer.ddl_create_table_partition_by_fields
- job.writer.ddl_create_table_cluster_by_fields & job.writer.ddl_create_table_buckets
- job.writer.ddl_create_table_sample_by_expression
- job.writer.ddl_create_table_ttl_expression
- job.writer.ddl_create_table_settings
- job.writer.table_without_primary_key_strategy
核心作用这组参数仅在 DataSail 结合元数据服务、需要自动创建目标表时生效。它们允许用户在建表时，为新表指定 ORDER BY, PARTITION BY, CLUSTER BY, TTL 等物理存储属性。
适用场景
- Schema on Write：在数据写入前，由数据集成任务自动在 ByteHouse 中创建结构化、性能优化的目标表。
调参建议
- 按需配置：根据您的查询模式和数据生命周期管理需求，配置相应的参数。
  - ddl_create_table_order_by_fields: （强烈建议） 指定排序键，这是影响查询性能最重要的物理属性。
  - ddl_create_table_partition_by_fields: （强烈建议） 指定分区键，用于数据裁剪和生命周期管理。
  - 其他参数：如 TTL 用于数据自动过期，CLUSTER BY 用于更细粒度的数据组织，请根据高级需求配置。
- table_without_primary_key_strategy：在 UPSERT 模式下，如果上游 schema 没有主键，此参数决定了建表行为。SKIP（默认）表示跳过建表并丢弃数据，CREATE_AS_APPEND 表示降级为 INSERT 模式创建一张普通追加表。
总结说明DDL 自动建表系列参数，允许您在数据写入前，精细化地控制 DataSail 自动创建的 ByteHouse 目标表的物理存储属性，如排序键、分区键和 TTL 等。合理配置这些参数对于优化下游查询性能至关重要。这通常在结合了元数据管理的整库同步等高级场景中使用。

Common 参数（通用）

本章节介绍在 Source 和 Sink 两端都可能用到的通用参数。

job.common.global_timezone

参数概述
- 参数名：job.common.global_timezone
- 适用范围：Common
- 单位：无
- 默认值：无（依赖 JVM 默认时区）
- 核心作用：为整个 DataSail 作业的 JVM 实例设置一个统一的默认时区（如 Asia/Shanghai 或 UTC）。
适用场景
- 场景一：处理带时区的时间类型数据
  - 典型现象：源端或目标端的时间、日期类型字段，其解析或格式化结果与预期不符，出现“差8小时”等问题。
  - 建议：显式设置 job.common.global_timezone 为您的业务标准时区。例如，如果业务数据都以北京时间为基准，应设置为 Asia/Shanghai。
- 场景二：保证跨环境运行的一致性
  - 典型现象：同一个作业，在本地（通常是 Asia/Shanghai 时区）运行结果正确，部署到服务端（可能是 UTC 时区）后出现时间偏差。
  - 建议：在所有生产作业中都明确配置此参数，消除对运行环境的隐式依赖。
调参建议 / 推荐配置
- 强烈建议配置：
  - job.common.global_timezone: "Asia/Shanghai"
- 保持所有作业的时区配置一致，是避免时间相关问题的最佳实践。
注意事项
- 此参数影响所有基于 JVM 默认时区进行操作的函数，包括但不限于 Date, Timestamp 类型的字符串转换、JDBC 驱动的时区处理等。
- 一旦设置，它将在每个 TaskManager 的 JVM 首次调用时生效。
总结说明job.common.global_timezone 参数用于为 BitSail 作业设置一个统一的 JVM 默认时区（如 Asia/Shanghai 或 UTC），以确保所有时间相关类型（如 Date, Timestamp）的解析和格式化都基于一个确定的基准。强烈建议在所有生产作业中显式配置此参数，以消除对运行环境的依赖，避免因时区不一致导致的数据偏差问题，并确保时间函数和分区表达式的行为符合预期。

近实时 CDC Merge 作业相关参数

说明

以下参数组是一套高级实验性功能，用于在 ByteHouse CDW Sink 中实现天级分区的近实时滚动快照，作为对传统 T+1 批量作业的一种替代方案。请在充分理解其机制和风险后使用。

参数列表：
- job.common.is_merge_job
- job.writer.init_with_previous_partition
- job.writer.event_time_partition_column_name
- job.common.time_unit
- job.common.start_event_timestamp
核心作用这组参数协同工作，用于实现一种特殊的 CDC 写入模式：在每日分区切换的时刻（例如凌晨），作业会自动将“昨天”分区的最终数据状态，复制一份到“今天”的分区作为初始数据。随后，今天的增量 CDC 数据会继续写入“今天”的分区。
适用场景
- 替代 T+1 全量任务：
  - 典型现象：业务需要一张每日更新的 ODS/DWD 层事实表，传统做法是每天凌晨跑一个 T+1 的全量任务。这种做法资源消耗大，且延迟高。
  - 建议：通过启用这组参数，可以将 T+1 任务改造为一个 7x24 小时运行的流式 CDC 作业。作业会在分区切换时自动完成“日切”，无需额外的调度和全量抽取。
调参建议 / 推荐配置
- 启用配置示例：
  - job.common.is_merge_job: true
  - job.writer.init_with_previous_partition: true
  - job.writer.event_time_partition_column_name: "your_date_partition_col" (目标表中必须有此 Date 类型分区列)
  - job.common.time_unit: "DAY" (当前仅支持天级别)
  - job.common.start_event_timestamp: (可选) 提供一个基准时间戳，用于计算“今天”和“昨天”。
注意事项
- 实验性功能：此功能目前仍处于实验阶段，其行为和 API 在未来可能发生变化。
- 幂等性：此操作的幂等性需要依赖于外部调度系统来保证。例如，您需要确保“日切”操作（即触发 init_with_previous_partition 的那次运行）在每个自然日只被精确执行一次。重复执行会导致数据重复。
- 分区列要求：event_time_partition_column_name 指定的列必须是 Date 类型。
总结说明这是一组高级参数，用于在 ByteHouse CDW Sink 中实现天级分区的近实时滚动快照。通过将 job.common.is_merge_job 和 job.writer.init_with_previous_partition 设置为 true，并提供分区列名和基准时间戳，您可以让 CDC 作业在每日分区切换时，自动将前一天的最终数据状态复制到当天分区作为初始数据。此功能可替代传统的每日全量 T+1 批量任务，但需要精细的调度策略来保证其幂等性。

总体使用建议与排障流程小结

1. 核心调优思路

在配置 DataSail ByteHouse CDW 连接器时，性能调优通常围绕以下几个核心权衡展开：

实时性 vs. 吞吐量
- 追求实时性：减小 job.writer.flush_interval，让数据更快地从内存写入数据库。
- 追求吞吐量：增大 job.writer.buffer_count 和 job.writer.flush_interval，用更大的批次来摊薄单次写入的开销。同时，在源端（如果资源允许），可以尝试增大 job.reader.scan_split_size。
资源消耗 vs. 性能
- 内存：job.writer.buffer_count 是 Sink 端内存消耗的主要来源。如果遇到 OOM，优先降低此值。
- CPU/网络：过于频繁的刷写（小 flush_interval）或拉取（小 scan_split_size）会增加网络和 CPU 的开销。
健壮性 vs. 快速失败
- 追求健壮性：在网络不稳定的环境中，适当增加 job.reader.cdc_retry_times 可以让作业更能容忍暂时的网络抖动。
- 追求快速失败：在需要快速响应和告警的场景，可以减少重试次数，让问题更快暴露。

2. 常见问题与排障流程

说明

问题一：CDC 作业启动后没数据

检查 initial_offset_type：确认是否为 latest 且源端确实没有新数据。如果需要同步历史数据，应改为 earliest。
检查过滤条件：确认 database_include_list 和 table_include_list 是否正确配置，是否无意中排除了目标表。
检查连接信息：确认 host, port, token, virtual_warehouse 等连接参数是否正确，作业是否有权限访问源端。
查看日志：搜索 No tables are matched 或 Offset for table ... is set to latest 等日志，确认表的发现和位点设置情况。

说明

问题二：写入超时或源端压力大

减小拉取批次：调小 job.reader.scan_split_size，降低对源端的单次请求压力。
减小写入批次：调小 job.writer.buffer_count，让每次 INSERT 的数据量变小。
延长写入超时：如果确认大批量写入是必须的，则调大 job.writer.query_timeout 以给予更长的执行时间。
查看 ByteHouse 慢查询日志：在 ByteHouse 端排查是否有性能瓶颈，如锁等待、资源不足等。

说明

问题三：时间/日期字段错乱（“差8小时”）

设置全局时区：在作业配置中显式添加 job.common.global_timezone: "Asia/Shanghai"，统一作业运行的 JVM 时区。这是解决此类问题的最根本方法。
检查源和目标表类型：确认源端和目标端对于时间字段的类型定义是否一致（如 DATETIME, TIMESTAMP），以及它们是否带有时区信息。

说明

问题四：作业因 `Too many partitions` 失败

优化数据分布：这是首选方案。检查上游数据逻辑或表的分区键设计，尽量让单批次数据写入更集中的分区。
放宽会话限制：如果无法优化数据分布，作为临时解决方案，调大 job.writer.max_partitions_per_insert_block 的值，例如设置为 1000。

最近更新时间：2026.05.07 14:11:24

这个页面对您有帮助吗？

有用

无用

大数据研发治理套件

Source 参数（读取侧） #

job.reader.initial_offset_type #

job.reader.initial_offset_props #

job.reader.scan_split_size #

job.reader.cdc_retry_times & job.reader.cdc_retry_interval_ms #

job.reader.src_meta_info_column_enabled & job.reader.src_meta_info_column_name #

job.reader.meta_db_seq_enabled #

job.common.cdc_multiplex_record_case_insensitive #

Sink 参数（写入侧） #

job.writer.atomic_write #

job.writer.atomic_write_retry_limits & job.writer.atomic_write_retry_wait_millis #

job.writer.buffer_count & job.writer.flush_interval #

job.writer.connection_validity_timeout #

job.writer.max_partitions_per_insert_block #

job.writer.query_timeout #

job.writer.secure & job.writer.cnch_engine #

job.writer.bh_connection_properties & job.writer.session_properties #

写入模式与 DDL 相关参数 #