You need to enable JavaScript to run this app.
文档中心
大数据研发治理套件

大数据研发治理套件

请输入
  • 文档首页
    • 大数据研发治理套件用户指南数据集成高级参数配置 ByteHouse CE 高级参数
复制全文
下载 pdf
我的收藏
高级参数
配置 ByteHouse CE 高级参数
复制全文
下载 pdf
我的收藏
配置 ByteHouse CE 高级参数

本文将为您介绍 DataSail 向 ByteHouse CE 写入数据时可配置的高级参数，涵盖连接认证、写入模式、性能调优等方面，可以帮助您提升数据同步的实时性、优化吞吐量，并解决日常运维中遇到的问题。

连接与认证

本节包含配置与 ByteHouse CE 数据库建立安全、稳定连接所需的基础参数。

job.writer.bh_connection_properties

  • 参数概述
    • 参数名：job.writer.bh_connection_properties
    • 适用范围：Sink
    • 类型：Map
    • 默认值：N/A
    • 核心作用：透传 JDBC driver properties（例如自定义 socket 超时等）；会覆盖/补充到 Connection Properties。
  • 适用场景
    • 主要应用场景：透传 JDBC driver properties（例如自定义 socket 超时等）；会覆盖/补充到 Connection Properties。
    • 代码参考：该参数主要影响的逻辑位于 BytehouseWriterOptions#BH_CONNECTION_PROPERTIES。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 N/A 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 bh_connection_properties 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.bh_connection_properties 参数用于配置 ByteHouse CE 的写入行为。默认值为 N/A。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

写入模式与表结构

本节参数决定了数据如何被写入 ByteHouse，包括是追加还是更新，以及如何定义目标表的结构。

job.writer.write_mode

  • 参数概述
    • 参数名：job.writer.write_mode
    • 适用范围：Sink
    • 可选值：INSERT, UPSERT
    • 默认值：INSERT
    • 核心作用：定义数据写入 ByteHouse 时的模式。INSERT 模式仅执行追加写入操作，而 UPSERT 模式则会根据主键或唯一键（unique_keys）实现“插入或更新”的语义。
  • 适用场景
    • 场景一：增量数据追加（ETL/ELT）
      • 典型现象：上游是日志类数据或只需持续追加新记录的业务数据，无更新或删除操作。
      • 处理方式：保持默认值 INSERT。这是性能最高的写入模式，因为它不涉及任何写前检查或更新逻辑。
    • 场景二：同步数据库变更（CDC）
      • 典型现象：上游是 MySQL、PostgreSQL 等关系型数据库，通过 CDC 工具捕获了 INSERT, UPDATE, DELETE 操作，需要将这些变更同步到 ByteHouse。
      • 常见报错关键字：如果使用 INSERT 模式处理包含更新的数据，下游会出现主键冲突错误，如 DB::Exception: Duplicate entry ... for key 'PRIMARY'。
      • 处理方式：设置为 UPSERT。此模式下，DataSail 会将 UPDATE 和 DELETE 操作转换为对目标表的更新和删除（逻辑删除或物理删除，取决于表引擎），从而实现数据同步。
  • 调参建议 / 推荐配置
    • 吞吐量优先 / 无更新场景：
      • 配置：job.writer.write_mode: "INSERT"
      • 说明：对于日志、埋点等只需追加写入的场景，INSERT 模式是最佳选择，能最大限度地发挥 ByteHouse 的批量写入性能。
    • 数据同步 / 去重场景：
      • 配置：job.writer.write_mode: "UPSERT"
      • 说明：当需要从业务库同步数据、实现数据去重或应用 CDC 变更时，必须使用 UPSERT 模式。请确保目标 ByteHouse 表使用了支持更新语义的表引擎（如 HaUniqueMergeTree）。
  • 参数联动
    • job.writer.unique_keys 或表主键：UPSERT 模式强依赖于唯一键来识别待更新的记录。您必须通过 job.writer.unique_keys 参数指定用于去重的列，或者目标表已定义了主键。如果两者都未提供，UPSERT 将无法工作。
    • job.writer.engine：在某些情况下，当 UPSERT 写入 HaUniqueMergeTree 表时，如果表的 remote_table_is_ha_unique 设置不正确，DataSail 会尝试自动执行 MODIFY SETTING 来修复。engine 参数的配置会影响此判断。
    • job.writer.ddl_create_table_version_column：如果使用 HaUniqueMergeTree 引擎并指定了版本列，UPSERT 会利用该列进行数据合并，确保数据版本正确性。
  • FAQ（用户提问）
    • 问：为什么我设置了 UPSERT 模式，但数据还是重复了？
      • 答：请检查以下几点：1) 是否正确配置了 job.writer.unique_keys 或目标表是否包含主键？这是 UPSERT 的必要条件。2) 目标表的引擎是否支持更新？推荐使用 HaUniqueMergeTree。3) 您的 unique_keys 组合是否真的能唯一标识一条记录？
  • 注意事项
    • UPSERT 模式相比 INSERT 会带来额外的性能开销，因为它需要在写入时进行比较和判断。请仅在必要时使用。
    • 使用 UPSERT 模式时，务必保证下游 ByteHouse 表的引擎支持去重和更新操作，否则可能导致非预期的行为或错误。
  • 总结说明job.writer.write_mode 参数用于选择数据写入模式。对于只需追加新数据的场景，使用默认值 INSERT 可获得最佳性能。当需要同步来自业务数据库的变更（包括插入、更新和删除），或实现数据去重时，应设置为 UPSERT。UPSERT 模式强依赖于主键或唯一键（通过 job.writer.unique_keys 配置）来识别记录，并需要目标 ByteHouse 表使用 HaUniqueMergeTree 等支持更新语义的引擎。

job.writer.unique_keys

  • 参数概述
    • 参数名：job.writer.unique_keys
    • 适用范围：Sink
    • 类型：String
    • 默认值：N/A
    • 核心作用：建表 DDL 的 UNIQUE KEY 字段列表；UPSERT 场景用于生成 UNIQUE KEY 子句。
  • 适用场景
    • 主要应用场景：建表 DDL 的 UNIQUE KEY 字段列表；UPSERT 场景用于生成 UNIQUE KEY 子句。
    • 代码参考：该参数主要影响的逻辑位于 BytehouseWriterOptions#UNIQUE_KEYS。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 N/A 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 unique_keys 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.unique_keys 参数用于配置 ByteHouse CE 的写入行为。默认值为 N/A。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.engine

  • 参数概述
    • 参数名：job.writer.engine
    • 适用范围：Sink
    • 类型：String
    • 默认值：N/A
    • 核心作用：UPSERT 异常处理分支使用：若 engine=HaUniqueMergeTree 且缺少必要设置，会尝试执行 MODIFY SETTING remote_table_is_ha_unique=1。
  • 适用场景
    • 主要应用场景：UPSERT 异常处理分支使用：若 engine=HaUniqueMergeTree 且缺少必要设置，会尝试执行 MODIFY SETTING remote_table_is_ha_unique=1。
    • 代码参考：该参数主要影响的逻辑位于 BytehouseWriterOptions#ENGINE。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 N/A 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 engine 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.engine 参数用于配置 ByteHouse CE 的写入行为。默认值为 N/A。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

分片与路由

本节参数控制数据如何分布到 ByteHouse 集群的不同分片上。

job.writer.clickhouse_sharding

  • 参数概述
    • 参数名：job.writer.clickhouse_sharding
    • 适用范围：Sink
    • 类型：boolean
    • 默认值：FALSE
    • 核心作用：启用 ClickHouse 分布式表分片表达式：若提供 sharding_func/sharding_columns 则按其生成；否则尝试从 Catalog 获取。
  • 适用场景
    • 主要应用场景：启用 ClickHouse 分布式表分片表达式：若提供 sharding_func/sharding_columns 则按其生成；否则尝试从 Catalog 获取。
    • 代码参考：该参数主要影响的逻辑位于 ByteHouseEnterpriseOptions#CLICKHOUSE_SHARDING。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 FALSE 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 clickhouse_sharding 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.clickhouse_sharding 参数用于配置 ByteHouse CE 的写入行为。默认值为 FALSE。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.sharding_func

  • 参数概述
    • 参数名：job.writer.sharding_func
    • 适用范围：Sink
    • 类型：String
    • 默认值：N/A
    • 核心作用：分片函数名（例如 sipHash64 等）；仅在 clickhouse_sharding=true 且指定了 sharding_columns 时生效。
  • 适用场景
    • 主要应用场景：分片函数名（例如 sipHash64 等）；仅在 clickhouse_sharding=true 且指定了 sharding_columns 时生效。
    • 代码参考：该参数主要影响的逻辑位于 ByteHouseEnterpriseOptions#CLICKHOUSE_SHARDING_FUNC。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 N/A 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 sharding_func 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.sharding_func 参数用于配置 ByteHouse CE 的写入行为。默认值为 N/A。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.sharding_columns

  • 参数概述
    • 参数名：job.writer.sharding_columns
    • 适用范围：Sink
    • 类型：String
    • 默认值：N/A
    • 核心作用：分片列列表（字符串，内部按分隔符切分为 List）；用于构造分片表达式或分片选择器。
  • 适用场景
    • 主要应用场景：分片列列表（字符串，内部按分隔符切分为 List）；用于构造分片表达式或分片选择器。
    • 代码参考：该参数主要影响的逻辑位于 ByteHouseEnterpriseOptions#CLICKHOUSE_SHARDING_COLUMNS。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 N/A 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 sharding_columns 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.sharding_columns 参数用于配置 ByteHouse CE 的写入行为。默认值为 N/A。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.write_local_table

  • 参数概述
    • 参数名：job.writer.write_local_table
    • 适用范围：Sink
    • 类型：boolean
    • 默认值：TRUE (存量任务)、FALSE (新增任务)
    • 核心作用：决定数据是直接写入 ByteHouse 集群的本地表（_local 后缀的表）还是分布式表（Distributed Table）。
  • 适用场景
    • 场景一：追求极致写入性能，且上游已做分片
      • 典型现象：数据源本身已经按某种分片键（Sharding Key）进行了拆分，或者用户希望在 DataSail 层面精确控制数据写入到哪个物理分片。
      • 处理方式：设置为 TRUE。DataSail 会将数据直接写入每个分片节点的本地表。这种方式绕过了分布式表的额外分发逻辑，通常写入性能更高。
    • 场景二：简化配置，由 ByteHouse 负责数据分发
      • 典型现象：用户不关心数据具体落在哪个物理分片，希望由 ByteHouse 集群根据分布式表的定义自动完成数据路由和分发。
      • 处理方式：设置为 FALSE (推荐用于新任务)。DataSail 会将所有数据写入分布式表，由 ByteHouse 接管后续的数据分发。
  • 调参建议 / 推荐配置
    • 新任务推荐配置：
      • 配置：job.writer.write_local_table: false
      • 说明：这是推荐用于新作业的模式。它将数据分片的复杂性交给了 ByteHouse，使得 DataSail 侧的配置更简单，也更容易利用 ByteHouse 的集群能力。
    • 高性能或精细控制场景：
      • 配置：job.writer.write_local_table: true
      • 说明：当写入性能是首要瓶颈，或者需要手动控制数据布局时使用。但这要求用户对 ByteHouse 的分片机制有深入了解，并可能需要配合 job.writer.sharding_* 系列参数进行手动分片。
  • 参数联动
    • job.writer.clickhouse_sharding, job.writer.sharding_func, job.writer.sharding_columns, job.writer.sharding_strategy：
      • 当 write_local_table 为 TRUE 时，上述分片参数才真正生效。DataSail 需要根据这些配置来决定每条数据应该被路由到哪个分片的本地表。
      • 当 write_local_table 为 FALSE 时，DataSail 仅将数据写入分布式表，上述分片参数会被忽略。
    • job.writer.insert_distributed_sync：
      • 此参数仅在 write_local_table 为 FALSE 时有意义，用于控制写入分布式表时的数据同步级别。
  • FAQ（用户提问）
    • 问：为什么我的数据都写到同一个分片上了？
      • 答：如果您设置了 write_local_table: true，但没有正确配置分片参数（sharding_columns 等），DataSail 的分片选择器可能会退化为默认行为（如轮询或随机），或者在某些配置错误下全部发送到同一个节点。请检查您的分片相关配置。如果设置为 write_local_table: false，则需要检查 ByteHouse 分布式表的定义。
  • 注意事项
    • 存量任务的默认值为 TRUE，而新创建的任务默认为 FALSE。在迁移或对比新旧任务时，请特别注意此参数的差异。
    • 切换 write_local_table 的值是一个重大变更，它会彻底改变写入逻辑和数据流向。在生产环境中修改前，必须经过充分测试。
  • 总结说明job.writer.write_local_table 参数用于控制数据是写入 ByteHouse 的本地表 (_local) 还是分布式表，默认值为 FALSE（新任务）。设置为 false 时，由 ByteHouse 负责数据分发，配置简单，是推荐用法；设置为 true 时，DataSail 会直接写入分片本地表，性能更高，但需要您在 DataSail 侧自行处理分片逻辑，适合对性能和数据布局有精细控制需求的高级用户。

job.writer.insert_distributed_sync

  • 参数概述
    • 参数名：job.writer.insert_distributed_sync
    • 适用范围：Sink
    • 类型：boolean
    • 默认值：TRUE
    • 核心作用：在写入分布式表（job.writer.write_local_table: false）时，控制数据插入的一致性级别。当设置为 true 时，协调节点会等待数据在所有分片上都写入成功后，才向客户端返回成功响应。
  • 适用场景
    • 场景一：要求高数据可靠性
      • 典型现象：写入操作返回成功后，必须能立即在所有分片上查询到该数据，不允许出现短暂的数据不一致。
      • 处理方式：保持默认值 TRUE。这是最安全、可靠性最高的模式。
    • 场景二：追求更高写入吞吐，可容忍最终一致性
      • 典型现象：业务对写入性能要求极高，可以接受数据在写入成功后有短暂的延迟才能在所有分片上可见。
      • 处理方式：设置为 FALSE。此时，协调节点在接收到数据后会立即返回成功，并在后台异步地将数据分发到各个分片。这种方式减少了客户端的等待时间，能显著提升写入吞吐，但引入了数据最终一致性的窗口期。
  • 调参建议 / 推荐配置
    • 可靠性优先（默认推荐）：
      • 配置：job.writer.insert_distributed_sync: true
      • 说明：对于绝大多数业务场景，尤其是涉及金融、订单等关键数据的场景，应始终使用同步写入，以保证数据的强一致性。
    • 吞吐量优先：
      • 配置：job.writer.insert_distributed_sync: false
      • 说明：仅在对写入性能的要求远高于数据实时一致性，且业务逻辑能处理短暂数据延迟的场景下（如大规模日志采集），才可考虑设置为 false。
  • 参数联动
    • job.writer.write_local_table：insert_distributed_sync 仅在 write_local_table 为 FALSE 时生效。如果直接写入本地表，则不存在跨分片的同步问题，此参数会被忽略。
  • FAQ（用户提问）
    • 问：设置为 false（异步）后，数据会丢失吗？
      • 答：理论上，ByteHouse 的分布式表写入机制是可靠的，异步模式下数据只是在后台排队分发。但在极端情况下（如协调节点宕机、网络长时间中断），存在极低概率的后台分发失败风险。而同步模式则能通过客户端的重试机制来更好地应对这些问题。
  • 注意事项
    • 异步写入（false）会使问题排查变得更加复杂。当发生数据不一致或丢失时，很难判断是客户端写入问题还是 ByteHouse 后台分发问题。
    • 在决定使用异步写入前，请务必与您的 ByteHouse 运维团队确认其对集群稳定性和数据可靠性的影响。
  • 总结说明job.writer.insert_distributed_sync 参数控制向 ByteHouse 分布式表写入数据时的一致性模式。保持默认值 true 可启用同步写入，确保写入成功后数据在所有分片上立即可见，可靠性最高；若设置为 false，则变为异步写入，客户端会更快收到成功响应，吞吐更高，但需容忍数据在分片间的短暂延迟和极低概率下的后台分发失败风险。请注意，此参数仅在 job.writer.write_local_table 为 false（即写入分布式表）时生效。

job.writer.sharding_strategy

  • 参数概述
    • 参数名：job.writer.sharding_strategy
    • 适用范围：Sink
    • 可选值：round_robin, random
    • 默认值：round_robin
    • 核心作用：在写入本地表（job.writer.write_local_table: true）且无法通过其他方式确定分片策略时，提供一种“兜底”的数据分发策略。
  • 适用场景
    • 场景一：写入无主键、无分片键的表
      • 典型现象：目标表既没有主键，用户也没有通过 job.writer.sharding_func / job.writer.sharding_columns 指定分片键。在这种情况下，DataSail 无法基于数据内容进行哈希分片。
      • 处理方式：此时 sharding_strategy 会生效。
        • round_robin（默认）：数据会以轮询的方式，依次发送到集群的各个分片节点。
        • random：数据会被随机发送到任意一个分片节点。
  • 调参建议 / 推荐配置
    • 强烈不推荐依赖此参数：
      • 配置：无，应优先配置主键或 sharding_columns。
      • 说明：sharding_strategy 是一个低优先级的备选方案。依赖它意味着您放弃了对数据分布的控制，可能导致数据倾斜或查询性能问题。最佳实践是始终为您的表定义一个明确的分片键（通过主键或 sharding_columns），让数据分布可预期、可控制。
    • 临时测试或非关键场景：
      • 配置：job.writer.sharding_strategy: "round_robin"
      • 说明：如果只是临时导入一些非核心数据，并且不关心其物理分布，使用默认的 round_robin 可以在大多数情况下实现基本的数据打散。
  • 参数联动
    • job.writer.write_local_table：此参数仅在 write_local_table 为 TRUE 时生效。如果写入的是分布式表，分片由 ByteHouse 自身负责。
    • 表主键 & job.writer.sharding_columns：
      • 如果目标表有主键，或用户配置了 sharding_columns，DataSail 会优先使用这些键进行哈希分片，sharding_strategy 将不会被使用。
      • 它的生效优先级是最低的：sharding_columns > 表主键 > sharding_strategy。
  • FAQ（用户提问）
    • 问：我设置了 sharding_strategy 为 random，为什么数据还是看起来分布不均？
      • 答：首先，请确认您的 write_local_table 是否为 true，并且目标表确实没有主键、您也没有配置 sharding_columns。其次，“随机”不保证在短期内或小数据量下绝对均匀，它只是一种概率上的均等。要实现可控的均匀分布，最佳方式仍然是使用基于哈希的分片策略（即配置 sharding_columns）。
  • 注意事项
    • 依赖此参数进行生产数据写入是一种风险较高的行为，因为它使得数据布局变得不可预测。
    • 在大多数情况下，您应该将注意力放在如何为业务数据设计一个合理的分片键上，而不是调整 sharding_strategy。
  • 总结说明job.writer.sharding_strategy 参数定义了在目标表无主键、且未指定分片键（sharding_columns）时的备选数据分发策略。它提供了 round_robin（轮询，默认）和 random（随机）两种方式来写入数据。然而，这是一个低优先级的“兜底”配置，强烈建议您通过为表设置主键或配置明确的分片键来主动控制数据分布，而不是依赖此参数。

会话与连接属性

本节参数用于微调与 ByteHouse 建立的每个连接和会话的行为。

job.writer.query_timeout

  • 参数概述
    • 参数名：job.writer.query_timeout
    • 适用范围：Sink
    • 类型：long(ms)
    • 默认值：180000
    • 核心作用：SQL 超时时间（毫秒）；内部会转为秒级写入 PreparedStatement setQueryTimeout。
  • 适用场景
    • 主要应用场景：SQL 超时时间（毫秒）；内部会转为秒级写入 PreparedStatement setQueryTimeout。
    • 代码参考：该参数主要影响的逻辑位于 BytehouseWriterOptions#QUERY_TIMEOUT。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 180000 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 query_timeout 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.query_timeout 参数用于配置 ByteHouse CE 的写入行为。默认值为 180000。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.connection_validity_timeout

  • 参数概述
    • 参数名：job.writer.connection_validity_timeout
    • 适用范围：Sink
    • 类型：int(s)
    • 默认值：10
    • 核心作用：检测 JDBC 连接是否有效的超时秒数；无效则尝试按 node candidates 重新连接。
  • 适用场景
    • 主要应用场景：检测 JDBC 连接是否有效的超时秒数；无效则尝试按 node candidates 重新连接。
    • 代码参考：该参数主要影响的逻辑位于 BytehouseWriterOptions#CONNECTION_VALIDITY_TIMEOUT。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 10 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 connection_validity_timeout 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.connection_validity_timeout 参数用于配置 ByteHouse CE 的写入行为。默认值为 10。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.session_properties

  • 参数概述
    • 参数名：job.writer.session_properties
    • 适用范围：Sink
    • 类型：Map
    • 默认值：N/A
    • 核心作用：每次获取 Statement 时会对连接执行 SET k=v；适合注入会话级 ClickHouse 参数。
  • 适用场景
    • 主要应用场景：每次获取 Statement 时会对连接执行 SET k=v；适合注入会话级 ClickHouse 参数。
    • 代码参考：该参数主要影响的逻辑位于 BytehouseWriterOptions#SESSION_PROPERTIES。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 N/A 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 session_properties 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.session_properties 参数用于配置 ByteHouse CE 的写入行为。默认值为 N/A。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.max_partitions_per_insert_block

  • 参数概述
    • 参数名：job.writer.max_partitions_per_insert_block
    • 适用范围：Sink
    • 类型：int
    • 默认值：10000
    • 核心作用：若未在 session_properties 显式设置，会自动补齐到 session properties；用于避免单次 insert block 分区过多。
  • 适用场景
    • 主要应用场景：若未在 session_properties 显式设置，会自动补齐到 session properties；用于避免单次 insert block 分区过多。
    • 代码参考：该参数主要影响的逻辑位于 BytehouseWriterOptions#MAX_PARTITIONS_PER_INSERT_BLOCK。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 10000 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 max_partitions_per_insert_block 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.max_partitions_per_insert_block 参数用于配置 ByteHouse CE 的写入行为。默认值为 10000。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

性能与资源

本节参数主要用于调整写入性能、内存使用和重试行为。

job.writer.buffer_count

  • 参数概述
    • 参数名：job.writer.buffer_count
    • 适用范围：Sink
    • 类型：int
    • 默认值：8192
    • 核心作用：控制在 DataSail 的 Sink 端内存中最多缓冲的数据行数。当缓冲的行数达到此阈值时，会触发一次向 ByteHouse 的刷写（Flush）操作。
  • 适用场景
    • 场景一：高吞吐数据写入
      • 典型现象：数据源流量巨大，需要最大化写入吞吐量，减少与 ByteHouse 的网络交互次数。
      • 处理方式：适当调大 buffer_count 的值，例如 16384 或 32768。这会使得每次批量写入的数据更多，通常能提升整体吞吐性能。
    • 场景二：内存资源受限或数据实时性要求高
      • 典型现象：作业运行环境的内存有限，或者业务要求数据尽快在 ByteHouse 中可见。
      • 常见报错关键字：如果 buffer_count 设置过大，可能会导致 Flink TaskManager 出现内存溢出（OutOfMemoryError: Java heap space）。
      • 处理方式：适当调小 buffer_count 的值，例如 1024 或 2048。这会降低内存占用，并更频繁地触发刷写，从而缩短数据的端到端延迟。
  • 调参建议 / 推荐配置
    • 吞吐量优先：
      • 配置：job.writer.buffer_count: 16384 (或更大，取决于内存)
      • 说明：在内存允许的情况下，增加此值可以显著提高写入效率。建议从默认值开始，逐步加倍进行测试，同时观察 Flink TaskManager 的内存使用情况。
    • 实时性优先：
      • 配置：job.writer.buffer_count: 1000
      • 说明：如果数据可见性延迟是首要考虑因素，可以调小此值。但请注意，过小的值会增加刷写频率，可能给 ByteHouse 服务器带来更大压力。
    • 资源受限环境：
      • 配置：job.writer.buffer_count: 4096 (或更小)
      • 说明：在内存紧张的容器或虚机中，减小此值是避免 OOM 的有效手段。
  • 参数联动
    • job.writer.flush_interval：buffer_count 和 flush_interval 是共同决定刷写时机的两个条件，满足任一条件都会触发刷写。
      • 如果数据流入速度很快，通常是 buffer_count 先达到阈值。
      • 如果数据流入速度较慢或有间歇，flush_interval（按时间触发）则会成为主要的刷写触发器，避免数据在内存中停留过久。
      • 调优时必须同时考虑这两个参数。例如，即使 buffer_count 设得很大，但如果 flush_interval 设得很小，刷写依然会很频繁。
  • FAQ（用户提问）
    • 问：我把 buffer_count 调得很大，为什么吞吐量没有提升，反而下降了？
      • 答：可能原因有几个：1) 单次写入的数据包过大，可能触发了 ByteHouse 或网络层的一些限制，导致单次请求耗时变长。2) TaskManager 内存压力变大，导致频繁的 GC（垃圾回收），影响了整体性能。3) 您的瓶颈不在于 Sink 端的刷写，而在于 Source 端的数据读取或中间的转换逻辑。建议使用 Flink Web UI 和相关监控指标综合分析。
  • 注意事项
    • buffer_count 的最优值与数据行的平均大小强相关。如果每行数据很大，即使 buffer_count 值不高，也可能占用大量内存。
    • 调整此参数时，务必配套监控 Flink TaskManager 的内存使用率和 GC 情况。
  • 总结说明job.writer.buffer_count 参数用于控制内存中最多缓冲的数据行数，当达到此数值时会触发一次刷写操作，默认值为 8192。您可以根据业务对吞吐量和内存的诉求调整此参数：若需提升单次写入效率和总吞吐量，可适当调大此值（如 16384），但这会增加内存消耗；若内存资源有限或对数据实时性要求高，应适当调小此值。该参数与 job.writer.flush_interval（按时间缓冲）共同决定刷写时机。

job.writer.flush_interval

  • 参数概述
    • 参数名：job.writer.flush_interval
    • 适用范围：Sink
    • 类型：long
    • 单位：毫秒（ms）
    • 默认值：60000 (60秒)
    • 核心作用：设置定期将内存缓冲区中的数据刷写（Flush）到 ByteHouse 的时间间隔。即使缓冲区中的数据行数未达到 buffer_count 的阈值，只要距离上次刷写的时间超过了 flush_interval，也会触发一次刷写。
  • 适用场景
    • 场景一：数据流持续但流量较低
      • 典型现象：数据源持续有数据进入，但速度较慢，长时间无法填满 buffer_count 指定的行数，导致数据在内存中停留过久，下游迟迟不可见。
      • 处理方式：设置一个合理的 flush_interval，例如 5000 (5秒) 或 10000 (10秒)。这样可以确保即使在低流量下，数据也能在可接受的延迟内被写入 ByteHouse。
    • 场景二：追求极致的写入吞吐量
      • 典型现象：数据同步的重点是最大化总吞吐量，对单条数据的可见延迟不敏感。
      • 处理方式：适当调大 flush_interval 的值，例如 120000 (2分钟)。这会减少刷写的频率，让每次写入的数据块尽可能大（由 buffer_count 决定），从而降低网络和数据库的开销。
  • 调参建议 / 推荐配置
    • 实时性优先：
      • 配置：job.writer.flush_interval: 1000 (1秒)
      • 说明：对于需要近实时看到数据的场景，可以设置一个较短的时间间隔。这保证了即使数据流量中断，内存中的少量数据也能被及时刷写。
    • 吞吐量优先：
      • 配置：job.writer.flush_interval: 180000 (3分钟)
      • 说明：在离线或准实时场景下，通过延长刷写间隔，可以有效降低写入操作的频率，提升整体效率。
    • 均衡配置（默认）：
      • 配置：job.writer.flush_interval: 60000 (60秒)
      • 说明：默认值在实时性和吞吐量之间提供了一个较好的平衡点，适用于大多数常规场景。
  • 参数联动
    • job.writer.buffer_count：flush_interval 与 buffer_count 共同构成刷写的“或”条件。flush_interval 是一个“兜底”机制，用于处理那些因流量不足而长时间无法触发 buffer_count 阈值的批次。
      • 在高流量下，刷写主要由 buffer_count 触发。
      • 在低流量或流量波动大的情况下，flush_interval 的作用更为关键。
  • FAQ（用户提问）
    • 问：我将 flush_interval 设置为1秒，但为什么数据延迟还是高于1秒？
      • 答：flush_interval 仅控制 Sink 端何时将数据发送给 ByteHouse。端到端的延迟还包括数据从 Source 读取、在 Flink 内部处理、网络传输以及数据在 ByteHouse 内部合并和可见所需的时间。如果 buffer_count 很大，即使 flush_interval 很小，任务也可能因为在等待填满 buffer 而没有触发刷写。请综合检查整个数据链路的耗时。
  • 注意事项
    • flush_interval 设置得过小（如小于500ms），可能会导致过于频繁的刷写操作，对 ByteHouse Server 造成不必要的压力，甚至在高并发下影响其稳定性。
    • 在流处理作业中，即使没有新数据到来，定时刷写线程也会周期性地被唤醒检查，这会带来微小的 CPU 开销。
  • 总结说明job.writer.flush_interval 参数用于控制数据在写入 ByteHouse 前在内存中缓冲的最长时间，单位是毫秒，默认值为 60000 (60秒)。您可以根据业务需求调整此参数以平衡数据写入的实时性和吞吐效率：若需降低数据可见延迟，请适当调小该值（如 1000-5000ms）；若需提升批量写入性能和总吞吐量，请适当调大该值（如 120000ms）。请注意，此参数与 job.writer.buffer_count（按行数缓冲）共同决定刷写时机，调整时建议结合数据流量和性能目标综合考虑。

job.writer.retry

  • 参数概述
    • 参数名：job.writer.retry
    • 适用范围：Sink
    • 类型：int
    • 默认值：3
    • 核心作用：在数据刷写（Flush）到 ByteHouse 失败时，自动进行重试的最大次数。
  • 适用场景
    • 场景一：应对网络抖动或瞬时故障
      • 典型现象：由于网络瞬时中断、ByteHouse 节点临时不可用等原因，导致某次写入请求失败。
      • 常见报错关键字：Connection timed out, Broken pipe, Max attempts reached
      • 处理方式：保持默认值 3。内置的重试机制可以在不影响整个作业失败的情况下，自动恢复这些临时性错误，提高作业的健壮性。
  • 调参建议 / 推荐配置
    • 可靠性优先（默认推荐）：
      • 配置：job.writer.retry: 3
      • 说明：对于大多数生产环境，3 次重试提供了一个合理的平衡点，既能覆盖大部分瞬时故障，又不会在持续性问题上无限期等待。
    • 快速失败场景：
      • 配置：job.writer.retry: 0
      • 说明：在测试或调试阶段，或者当您希望任何写入失败都立即导致作业失败以便快速发现问题时，可以设置为 0 来禁用重试。
  • 参数联动
    • job.writer.connection_validity_timeout：在每次重试前，系统可能会检查连接的有效性。如果连接失效，会尝试重新建立连接，connection_validity_timeout 控制了这个检查的超时时间。
    • Fatal Errors：某些严重的、不可恢复的错误（如认证失败、SQL 语法错误）被定义为“致命错误”，它们会跳过重试机制，直接导致作业失败。
  • 注意事项
    • 过高的重试次数（如 10）在面对持续性问题（如 ByteHouse 集群长时间宕机）时，会导致作业长时间卡住，无法及时失败并报警。
    • 重试针对的是整个批次的数据。如果一个批次持续重试失败，其中的数据将无法写入。
  • 总结说明job.writer.retry 参数为数据写入提供了一层“安全网”，它定义了在遇到可恢复的错误（如网络抖动）时，系统应尝试重新写入的最大次数，默认值为 3。对于大多数生产作业，保持默认值即可有效提升任务的稳定性。

DDL 与建表选项

本节参数控制在目标表不存在时，DataSail 如何自动创建表，以及表的各项属性。

job.writer.ddl_default_on_cluster

  • 参数概述
    • 参数名：job.writer.ddl_default_on_cluster
    • 适用范围：Sink
    • 类型：boolean
    • 默认值：FALSE
    • 核心作用：true 时认为 BH 会自动补 ON CLUSTER：common table 的 preSQL 会移除 ON CLUSTER 子句；并走 Catalog 执行路径。
  • 适用场景
    • 主要应用场景：true 时认为 BH 会自动补 ON CLUSTER：common table 的 preSQL 会移除 ON CLUSTER 子句；并走 Catalog 执行路径。
    • 代码参考：该参数主要影响的逻辑位于 ByteHouseEnterpriseOptions#DDL_DEFAULT_ON_CLUSTER。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 FALSE 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 ddl_default_on_cluster 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.ddl_default_on_cluster 参数用于配置 ByteHouse CE 的写入行为。默认值为 FALSE。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.schema_sync_wait_sec

  • 参数概述
    • 参数名：job.writer.schema_sync_wait_sec
    • 适用范围：Sink
    • 类型：int
    • 默认值：60
    • 核心作用：Catalog 同步表结构的最大等待秒数（CE 覆盖默认值）。
  • 适用场景
    • 主要应用场景：Catalog 同步表结构的最大等待秒数（CE 覆盖默认值）。
    • 代码参考：该参数主要影响的逻辑位于 ByteHouseEnterpriseOptions#SCHEMA_SYNC_WAIT_SEC。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 60 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 schema_sync_wait_sec 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.schema_sync_wait_sec 参数用于配置 ByteHouse CE 的写入行为。默认值为 60。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.ddl_create_table_order_by_fields

  • 参数概述
    • 参数名：job.writer.ddl_create_table_order_by_fields
    • 适用范围：Sink
    • 类型：String
    • 默认值：N/A
    • 核心作用：建表 DDL 的 ORDER BY 表达式（可选）；未提供时按主键或 tuple()。
  • 适用场景
    • 主要应用场景：建表 DDL 的 ORDER BY 表达式（可选）；未提供时按主键或 tuple()。
    • 代码参考：该参数主要影响的逻辑位于 BytehouseWriterOptions#DDL_CREATE_TABLE_ORDER_BY_FIELDS。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 N/A 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 ddl_create_table_order_by_fields 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.ddl_create_table_order_by_fields 参数用于配置 ByteHouse CE 的写入行为。默认值为 N/A。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.ddl_create_table_partition_by_fields

  • 参数概述
    • 参数名：job.writer.ddl_create_table_partition_by_fields
    • 适用范围：Sink
    • 类型：String
    • 默认值：N/A
    • 核心作用：建表 DDL 的 PARTITION BY 表达式（可选）。
  • 适用场景
    • 主要应用场景：建表 DDL 的 PARTITION BY 表达式（可选）。
    • 代码参考：该参数主要影响的逻辑位于 BytehouseWriterOptions#DDL_CREATE_TABLE_PARTITION_BY_FIELDS。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 N/A 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 ddl_create_table_partition_by_fields 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.ddl_create_table_partition_by_fields 参数用于配置 ByteHouse CE 的写入行为。默认值为 N/A。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.ddl_create_table_sample_by_expression

  • 参数概述
    • 参数名：job.writer.ddl_create_table_sample_by_expression
    • 适用范围：Sink
    • 类型：String
    • 默认值：N/A
    • 核心作用：建表 DDL 的 SAMPLE BY 表达式（可选）。
  • 适用场景
    • 主要应用场景：建表 DDL 的 SAMPLE BY 表达式（可选）。
    • 代码参考：该参数主要影响的逻辑位于 BytehouseWriterOptions#DDL_CREATE_TABLE_SAMPLE_BY_EXPRESSION。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 N/A 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 ddl_create_table_sample_by_expression 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.ddl_create_table_sample_by_expression 参数用于配置 ByteHouse CE 的写入行为。默认值为 N/A。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.ddl_create_table_ttl_expression

  • 参数概述
    • 参数名：job.writer.ddl_create_table_ttl_expression
    • 适用范围：Sink
    • 类型：String
    • 默认值：N/A
    • 核心作用：建表 DDL 的 TTL 表达式（可选）。
  • 适用场景
    • 主要应用场景：建表 DDL 的 TTL 表达式（可选）。
    • 代码参考：该参数主要影响的逻辑位于 BytehouseWriterOptions#DDL_CREATE_TABLE_TTL_EXPRESSION。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 N/A 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 ddl_create_table_ttl_expression 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.ddl_create_table_ttl_expression 参数用于配置 ByteHouse CE 的写入行为。默认值为 N/A。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.ddl_create_table_settings

  • 参数概述
    • 参数名：job.writer.ddl_create_table_settings
    • 适用范围：Sink
    • 类型：Map
    • 默认值：N/A
    • 核心作用：建表 SETTINGS 透传；会默认补齐 index_granularity 与 partition_level_unique_keys（可通过同名 key 覆盖）。
  • 适用场景
    • 主要应用场景：建表 SETTINGS 透传；会默认补齐 index_granularity 与 partition_level_unique_keys（可通过同名 key 覆盖）。
    • 代码参考：该参数主要影响的逻辑位于 BytehouseWriterOptions#DDL_CREATE_SETTINGS。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 N/A 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 ddl_create_table_settings 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.ddl_create_table_settings 参数用于配置 ByteHouse CE 的写入行为。默认值为 N/A。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.ddl_create_table_index_granularity

  • 参数概述
    • 参数名：job.writer.ddl_create_table_index_granularity
    • 适用范围：Sink
    • 类型：int
    • 默认值：8192
    • 核心作用：默认补齐到建表 settings 的 index_granularity（若用户未显式提供）。
  • 适用场景
    • 主要应用场景：默认补齐到建表 settings 的 index_granularity（若用户未显式提供）。
    • 代码参考：该参数主要影响的逻辑位于 ByteHouseEnterpriseOptions#INDEX_GRANULARITY。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 8192 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 ddl_create_table_index_granularity 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.ddl_create_table_index_granularity 参数用于配置 ByteHouse CE 的写入行为。默认值为 8192。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.ddl_create_table_table_level_uniqueness

  • 参数概述
    • 参数名：job.writer.ddl_create_table_table_level_uniqueness
    • 适用范围：Sink
    • 类型：boolean
    • 默认值：FALSE
    • 核心作用：控制默认补齐的 partition_level_unique_keys：true -> 0；false -> 1。
  • 适用场景
    • 主要应用场景：控制默认补齐的 partition_level_unique_keys：true -> 0；false -> 1。
    • 代码参考：该参数主要影响的逻辑位于 ByteHouseEnterpriseOptions#TABLE_LEVEL_UNIQUENESS。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 FALSE 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 ddl_create_table_table_level_uniqueness 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.ddl_create_table_table_level_uniqueness 参数用于配置 ByteHouse CE 的写入行为。默认值为 FALSE。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.ddl_create_table_version_column

  • 参数概述
    • 参数名：job.writer.ddl_create_table_version_column
    • 适用范围：Sink
    • 类型：String
    • 默认值：N/A
    • 核心作用：unique key + version column 场景：会作为 HaUniqueMergeTree 的 version 参数拼入 engine 参数列表。
  • 适用场景
    • 主要应用场景：unique key + version column 场景：会作为 HaUniqueMergeTree 的 version 参数拼入 engine 参数列表。
    • 代码参考：该参数主要影响的逻辑位于 ByteHouseEnterpriseOptions#VERSION_COLUMN。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 N/A 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 ddl_create_table_version_column 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.ddl_create_table_version_column 参数用于配置 ByteHouse CE 的写入行为。默认值为 N/A。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.ddl_create_table_account_id

  • 参数概述
    • 参数名：job.writer.ddl_create_table_account_id
    • 适用范围：Sink
    • 类型：String
    • 默认值："0"
    • 核心作用：写入 HaMergeTree/HaUniqueMergeTree 引擎参数路径中的 accountId；也会尝试从 job.common.extra_metric_tags["AccountId"] 注入（若存在）。
  • 适用场景
    • 主要应用场景：写入 HaMergeTree/HaUniqueMergeTree 引擎参数路径中的 accountId；也会尝试从 job.common.extra_metric_tags["AccountId"] 注入（若存在）。
    • 代码参考：该参数主要影响的逻辑位于 ByteHouseEnterpriseOptions#ACCOUNT_ID。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 "0" 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 ddl_create_table_account_id 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.ddl_create_table_account_id 参数用于配置 ByteHouse CE 的写入行为。默认值为 '0'。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

近实时/合并写特性

本节参数主要服务于特定的近实时合并（Merge Job）场景。

job.common.is_merge_job / job.writer.init_with_previous_partition / job.writer.event_time_partition_column_name / job.common.start_event_timestamp / job.common.time_unit

  • 参数概述
    • 参数名：job.common.is_merge_job / job.writer.init_with_previous_partition / job.writer.event_time_partition_column_name / job.common.start_event_timestamp / job.common.time_unit
    • 适用范围：Common
    • 类型：boolean / boolean / String / long / String
    • 默认值：false / false / N/A / Long.MIN_VALUE / DAY
    • 核心作用：Merge job 场景：可在写入前基于“昨日分区”初始化“当日分区”的数据（仅特定模式下执行）。
  • 适用场景
    • 主要应用场景：Merge job 场景：可在写入前基于“昨日分区”初始化“当日分区”的数据（仅特定模式下执行）。
    • 代码参考：该参数主要影响的逻辑位于 CdcNearRealtimeOptions。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 false / false / N/A / Long.MIN_VALUE / DAY 即可满足大部分需求。
    • 特定场景调整：若默认行为不符合预期，例如时区问题或多表过滤逻辑，可进行调整。
  • 参数联动
    • job.common.global_timezone 会影响所有与时间相关的计算和展示，请确保其与您的数据源和目标端时区一致。
    • table_pattern 和 sink_table_mode 是多表写入场景下的核心控制参数，需配合使用。
  • FAQ（用户提问）
    • 问：这个通用参数会影响哪些部分？
    • 答：它会影响整个作业的全局行为。例如，global_timezone 影响时间处理，table_pattern 影响多表场景下的表发现。
  • 注意事项
    • Common 参数会影响整个作业链路，修改时需格外谨慎，并充分理解其全局影响。
  • 总结说明job.common.is_merge_job / ... 参数用于配置 ByteHouse CE 的写入行为。默认值为 false / false / ...。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.atomic_write

  • 参数概述
    • 参数名：job.writer.atomic_write
    • 适用范围：Sink
    • 类型：boolean
    • 默认值：FALSE
    • 核心作用：批任务可启用“原子写”：写入临时表后在 commit 阶段 detach/attach partition 转移数据（需要 DDL 权限）。
  • 适用场景
    • 主要应用场景：批任务可启用“原子写”：写入临时表后在 commit 阶段 detach/attach partition 转移数据（需要 DDL 权限）。
    • 代码参考：该参数主要影响的逻辑位于 BytehouseWriterOptions#ATOMIC_WRITE。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 FALSE 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 atomic_write 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.atomic_write 参数用于配置 ByteHouse CE 的写入行为。默认值为 FALSE。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

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
    • 类型：int / long
    • 默认值：30 / 10000
    • 核心作用：原子写的重试次数与重试等待间隔。
  • 适用场景
    • 主要应用场景：原子写的重试次数与重试等待间隔。
    • 代码参考：该参数主要影响的逻辑位于 BytehouseWriterOptions。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 30 / 10000 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 atomic_write_retry_wait_millis 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明暂无总结说明。请参考核心作用与适用场景。

通用参数

本节包含一些适用于更广泛场景的通用参数。

job.writer.partition

  • 参数概述
    • 参数名：job.writer.partition
    • 适用范围：Sink
    • 类型：String
    • 默认值：N/A
    • 核心作用：写入分区（非空时使用 DelegatePartitionRecordsWriter）；具体 partition 语义依赖 ByteHouse 表的分区与写入实现。
  • 适用场景
    • 主要应用场景：写入分区（非空时使用 DelegatePartitionRecordsWriter）；具体 partition 语义依赖 ByteHouse 表的分区与写入实现。
    • 代码参考：该参数主要影响的逻辑位于 WriterOptions#PARTITION。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 N/A 即可满足大部分需求。
    • 特定场景调整：在进行精细化调优或排查特定问题时，可参考“总结说明”和“注意事项”进行调整。
  • 参数联动
    • 此参数的行为可能受其他相关参数影响。例如，所有ddl_create_table_*系列的参数都服务于自动建表逻辑，需结合使用。sharding_func和sharding_columns需在clickhouse_sharding=true时才会生效。
  • FAQ（用户提问）
    • 问：在什么情况下我需要关心这个参数？
    • 答：当您需要对数据写入的 partition 行为进行定制时，例如调整性能、可靠性或特定功能时，需要关注此参数。
  • 注意事项
    • 请谨慎修改此参数，不正确的配置可能会导致写入失败、性能下降或非预期的行为。
    • 在生产环境中修改前，请务必在测试环境充分验证其影响。
  • 总结说明job.writer.partition 参数用于配置 ByteHouse CE 的写入行为。默认值为 N/A。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.table_pattern

  • 参数概述
    • 参数名：job.writer.table_pattern
    • 适用范围：Common
    • 类型：String
    • 默认值：.*
    • 核心作用：multi-table sink 场景下用于过滤 Catalog 内的表（对 ByteHouse CE 同样适用）。
  • 适用场景
    • 主要应用场景：multi-table sink 场景下用于过滤 Catalog 内的表（对 ByteHouse CE 同样适用）。
    • 代码参考：该参数主要影响的逻辑位于 WriterOptions#TABLE_PATTERN。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 .* 即可满足大部分需求。
    • 特定场景调整：若默认行为不符合预期，例如时区问题或多表过滤逻辑，可进行调整。
  • 参数联动
    • job.common.global_timezone 会影响所有与时间相关的计算和展示，请确保其与您的数据源和目标端时区一致。
    • table_pattern 和 sink_table_mode 是多表写入场景下的核心控制参数，需配合使用。
  • FAQ（用户提问）
    • 问：这个通用参数会影响哪些部分？
    • 答：它会影响整个作业的全局行为。例如，global_timezone 影响时间处理，table_pattern 影响多表场景下的表发现。
  • 注意事项
    • Common 参数会影响整个作业链路，修改时需格外谨慎，并充分理解其全局影响。
  • 总结说明job.writer.table_pattern 参数用于配置 ByteHouse CE 的写入行为。默认值为 .*。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.writer.sink_table_mode

  • 参数概述
    • 参数名：job.writer.sink_table_mode
    • 适用范围：Common
    • 类型：String
    • 默认值：single_table
    • 核心作用：控制 sink 的表路由模式（如 single_table/multi_table/...），决定是否按表拆分 sink。
  • 适用场景
    • 主要应用场景：控制 sink 的表路由模式（如 single_table/multi_table/...），决定是否按表拆分 sink。
    • 代码参考：该参数主要影响的逻辑位于 WriterOptions#SINK_TABLE_MODE。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 single_table 即可满足大部分需求。
    • 特定场景调整：若默认行为不符合预期，例如时区问题或多表过滤逻辑，可进行调整。
  • 参数联动
    • job.common.global_timezone 会影响所有与时间相关的计算和展示，请确保其与您的数据源和目标端时区一致。
    • table_pattern 和 sink_table_mode 是多表写入场景下的核心控制参数，需配合使用。
  • FAQ（用户提问）
    • 问：这个通用参数会影响哪些部分？
    • 答：它会影响整个作业的全局行为。例如，global_timezone 影响时间处理，table_pattern 影响多表场景下的表发现。
  • 注意事项
    • Common 参数会影响整个作业链路，修改时需格外谨慎，并充分理解其全局影响。
  • 总结说明job.writer.sink_table_mode 参数用于配置 ByteHouse CE 的写入行为。默认值为 single_table。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

job.common.global_timezone

  • 参数概述
    • 参数名：job.common.global_timezone
    • 适用范围：Common
    • 类型：String
    • 默认值：N/A
    • 核心作用：设置 JVM 默认时区（仅在第一次进入 writer 时生效）；影响日期/时间类字段序列化。
  • 适用场景
    • 主要应用场景：设置 JVM 默认时区（仅在第一次进入 writer 时生效）；影响日期/时间类字段序列化。
    • 代码参考：该参数主要影响的逻辑位于 BytehouseSink。
  • 调参建议 / 推荐配置
    • 默认配置：通常情况下，保持默认值 N/A 即可满足大部分需求。
    • 特定场景调整：若默认行为不符合预期，例如时区问题或多表过滤逻辑，可进行调整。
  • 参数联动
    • job.common.global_timezone 会影响所有与时间相关的计算和展示，请确保其与您的数据源和目标端时区一致。
    • table_pattern 和 sink_table_mode 是多表写入场景下的核心控制参数，需配合使用。
  • FAQ（用户提问）
    • 问：这个通用参数会影响哪些部分？
    • 答：它会影响整个作业的全局行为。例如，global_timezone 影响时间处理，table_pattern 影响多表场景下的表发现。
  • 注意事项
    • Common 参数会影响整个作业链路，修改时需格外谨慎，并充分理解其全局影响。
  • 总结说明job.common.global_timezone 参数用于配置 ByteHouse CE 的写入行为。默认值为 N/A。您可以根据业务对实时性、吞吐量和资源利用率的不同要求进行调整。调整时建议参考详细文档，并结合监控指标观察效果。

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

1. 核心参数调优路径

说明

调优检查清单

  1. 模式选择 (write_mode)：首先确定您的业务场景。是纯追加写入（INSERT），还是需要处理更新/删除（UPSERT）？这是最基础的决策。
  2. 缓冲策略 (buffer_count & flush_interval)：
    • 目标是低延迟？ -> 减小 flush_interval (如 1000) 和 buffer_count (如 1024)。
    • 目标是高吞吐？ -> 增大 buffer_count (如 16384) 和 flush_interval (如 180000)，并确保 Flink TaskManager 内存充足。
  3. 写入路径 (write_local_table)：
    • 新手或简化配置？ -> 使用新任务默认值 false，让 ByteHouse 处理分片。
    • 专家或性能极致追求？ -> 设置为 true，并仔细配置 sharding_columns，自行掌控数据分布。

2. 常见问题排查流程

  1. 作业启动失败
    • 检查：job.writer.user_name, job.writer.password, 以及 ByteHouse 的网络可达性。
    • 关键字：Authentication failed, Connection refused。
  2. 写入数据重复或未更新
    • 检查：write_mode 是否为 UPSERT？unique_keys 或主键是否正确配置？目标表引擎是否为 HaUniqueMergeTree？
  3. 数据写入慢 / 吞吐量低
    • 检查：
      • 增大 buffer_count 和 flush_interval 是否有改善？
      • Flink Web UI 中是否存在反压？瓶颈是否在 Source 或 Transform？
      • write_local_table 是否为 true 但分片不均导致热点？
      • ByteHouse 侧 system.query_log 中 INSERT 语句的执行耗时是否过长？
  4. 数据延迟高
    • 检查：
      • 减小 flush_interval 和 buffer_count 是否有改善？
      • 是否因为数据流量过低，长时间无法填满 buffer_count，导致数据积压在内存中？
  5. 数据分布不均
    • 检查：
      • write_local_table 是否为 true？
      • sharding_columns 是否配置正确且选择的列具有良好的区分度？
      • 是否退化到了 sharding_strategy 的 random 或 round_robin 模式？

通过遵循上述结构化的建议与排查流程，您应能解决大部分与 DataSail ByteHouse CE Sink 相关的配置与性能问题。如果问题依然存在，建议联系技术支持并提供详细的作业配置、日志以及相关的监控截图。

最近更新时间：2026.05.07 14:11:24
这个页面对您有帮助吗？
有用
有用
无用
无用