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

大数据研发治理套件

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

本文将为您介绍 DataSail 数据集成任务中 Doris Writer（Sink）侧的高级参数配置，包括各参数的适用场景、默认值、调优建议等，以帮助您在数据同步的实时性、吞吐量和稳定性之间实现最佳平衡。

1. job.writer.sink_flush_interval_ms

1.1. 参数概述

  • 参数名: job.writer.sink_flush_interval_ms
  • 适用范围/模块: Doris 数据写入（Writer/Sink）
  • 单位: 毫秒 (ms)
  • 默认值: 5000
  • 核心作用: 期望的数据刷写（Flush）时间间隔。它定义了一个“计时器”，当达到这个时间后，会触发一次数据提交操作，将内存中缓存的数据批量写入 Doris。

1.2. 适用场景

典型现象

常见报错关键字

是否相关

建议调大/调小

数据写入延迟较高，实时性不满足要求：数据在源端产生后，需要等待较长时间才能在 Doris 中查询到。

是

调小

Doris 端出现大量小文件或小批次导入：监控显示 Stream Load 的频率过高，但每次导入的数据量很小，增加了 Doris 的合并（Compaction）压力。

too many versions

是

调大

任务在低流量时频繁刷写空数据或极少量数据，造成资源浪费。

是

调大

常见报错关键字

  • stream load error
  • StreamLoad error
  • doris sink error, retry times
  • Failed to load data into doris
  • Commit failed

1.3. 调参建议 / 推荐配置

  • 默认推荐 (5000 ms): 适用于大多数对实时性要求不高（秒级延迟）、流量较平稳的场景，在吞吐量和延迟之间取得了较好的平衡。
  • 实时性优先:
    • 起始值: 尝试从 1000 ms (1秒) 开始。
    • 安全方向: 逐步调小，例如 1000 -> 500。
    • 预期影响: 数据写入延迟降低，能更快地在 Doris 中可见。但会增加数据写入的频率，可能导致 Doris 端产生更多的小批次，增加合并压力。适用于对数据可见性有准实时（秒级）要求的业务。
  • 吞吐优先 / 高流量场景:
    • 起始值: 尝试从 10000 ms (10秒) 或更高开始。
    • 安全方向: 逐步调大，例如 10000 -> 30000。
    • 预期影响: 减少向 Doris 提交数据的频率，增大每次提交的数据批次，提升整体吞吐量，并降低 Doris 的元数据和合并压力。适用于大批量离线数据导入或对实时性不敏感的场景。
  • 排障临时配置:
    • 现象: 怀疑数据是否正常进入写入缓存。
    • 配置: 可临时调至一个极小值（如 200 ms），快速验证数据流是否通畅。验证后务必恢复，否则会严重影响性能。

1.4. 参数联动

sink_flush_interval_ms 与控制批次大小的参数 sink_record_size 和 sink_record_count 共同决定了数据刷写的时机。刷写操作会在 任意一个 阈值达到时触发。

  • sink_flush_interval_ms (时间): 无论数据量多少，时间一到就刷写。
  • sink_record_count (行数): 无论耗时多久，达到指定行数就刷写。
  • sink_record_size (字节数): 无论耗时多久，达到指定字节数就刷写。

联动建议:

  • 在高流量场景下，通常由 sink_record_count 或 sink_record_size 主导刷写，此时 sink_flush_interval_ms 主要作为“兜底”机制，防止数据因流量降低而长时间滞留在缓存中。
  • 在低流量或实时性要求高的场景下，sink_flush_interval_ms 成为主要触发条件。此时应适当调小该值，同时确保 sink_record_count 和 sink_record_size 不会设置得过大，以免时间到了但数据量一直达不到阈值。

1.5. FAQ（用户提问）

  1. 问：为什么我把 sink_flush_interval_ms 调到 1000ms，但数据延迟还是有 5-6 秒？
    • 答：请检查是否存在其他触发条件。如果您的数据流量非常大，可能在 1 秒内就已经达到了 sink_record_count (默认10万行) 或 sink_record_size (默认20MB) 的阈值，导致提前刷写。此外，Doris 端的数据导入和生效本身也需要时间 (通常是秒级)，这也是延迟的一部分。
  2. 问：这个参数是不是越小越好？
    • 答：不是。过小的值（例如低于 500ms）会导致系统向 Doris 发起非常频繁的写入请求，即使每次只有少量数据。这不仅会给 Doris 带来巨大的合并压力，还可能因为网络交互和任务调度开销而降低整体吞吐量。应根据业务对实时性的真实需求来设定。
  3. 问：如果我的任务没有数据输入，这个计时器会一直空转吗？
    • 答：当没有数据流入时，刷写逻辑通常不会被激活，也就不会向 Doris 发起空的写入请求。这个参数主要作用于已有数据在缓存中的停留时间。

1.6. 注意事项

  • 副作用: 调小此值会显著增加与 Doris 的 HTTP 交互频率，并可能增加 Doris Tablet 的版本数量，加大后台合并（Compaction）的负担。
  • 边界: 该参数仅控制数据从 DTS 写入端到 Doris 的提交频率，不影响数据在 Doris 内部的生效（Publish Version）时间。
  • 不解决的问题: 无法解决因 Doris 本身负载过高、查询性能差或 Tablet 副本异常等问题导致的数据可见延迟。
  • 调整建议: 调整时建议以 500ms 或 1000ms 为单位进行观察，避免一次性调整幅度过大。

1.7. 总结说明

job.writer.sink_flush_interval_ms 控制数据写入 Doris 的时间间隔，默认 5000 毫秒。若您需要更高的实时性，可适当调小此值（如 1000ms），但这会增加 Doris 的写入压力；若追求更高吞吐，可适当调大（如 10000ms），以合并更大批次的数据。请根据业务需求在延迟和吞吐之间进行权衡。

2. job.writer.sink_max_retries

2.1. 参数概述

  • 参数名: job.writer.sink_max_retries
  • 适用范围/模块: Doris 数据写入（Writer/Sink）
  • 单位: 次
  • 默认值: 3
  • 核心作用: 当数据写入 Doris 的过程中（包括 Stream Load 数据提交和 2PC 事务提交）发生可重试的失败时，系统将尝试重新执行的最大次数。这是保障数据写入稳定性的关键容错参数。

2.2. 适用场景

典型现象

常见报错关键字

是否相关

建议调大/调小

网络偶发抖动导致任务失败：任务日志中出现连接超时、读取超时或 connection reset 等网络相关错误。

timeout, Connection refused, Read timed out

是

适当调大

Doris 集群因临时高负载（如 Compaction 或大查询）导致写入请求被拒绝或超时。

too many load jobs, stream load failed

是

适当调大

任务因 2PC 提交阶段的瞬时失败而中断，例如 Pre-commit 或 Commit 阶段与 FE 通信失败。

2PC commit failed, label already exists

是

适当调大

排查问题时，希望任务快速失败，而不是长时间等待重试。

是

调小

常见报错关键字

  • doris sink error, retry times
  • StreamLoad error
  • stream load error, reason=
  • Commit failed
  • commit transaction failed

2.3. 调参建议 / 推荐配置

  • 默认推荐 (3 次): 适用于大多数网络环境和 Doris 集群负载情况，能够应对常见的瞬时抖动。
  • 高可靠性要求 / 不稳定环境:
    • 起始值: 建议设置为 5 或 10 次。
    • 安全方向: 调大。
    • 预期影响: 显著增强任务对网络或 Doris 临时故障的容忍度，降低任务因偶发问题而失败的概率。但如果问题持续存在，会导致任务在最终失败前卡住更长时间，延迟问题发现。
  • 排障或快速失败场景:
    • 起始值: 建议设置为 0 或 1。
    • 安全方向: 调小。
    • 预期影响: 当写入失败时，任务会迅速失败并报告错误，便于快速定位问题根源，避免长时间等待。适用于调试和问题排查阶段。

2.4. 参数联动

sink_max_retries 通常与控制超时的参数 request_connect_timeouts, request_read_timeouts 以及 request_retries 协同工作。

  • sink_max_retries: 控制的是整个写入批次（一个 Stream Load 周期）的重试逻辑。
  • request_retries: 控制的是在发起单次 HTTP 请求（如获取 BE 节点、提交 2PC 事务）失败后的内部重试。

联动关系:一个批次的写入失败（由 sink_max_retries 控制），其内部可能已经执行了多次 HTTP 请求的重试（由 request_retries 控制）。如果网络非常不稳定，同时调大 sink_max_retries 和 request_retries 能够提供更强的容错性。但请注意，总的等待时间会是两者与超时时间的乘积，可能导致任务卡顿时间很长。

2.5. FAQ（用户提问）

  1. 问：是不是把重试次数设置得越大，任务就越稳定？
    • 答：在一定程度上是的，但并非绝对。非常大的重试次数（如超过 20 次）在应对瞬时网络抖动时是有效的，但如果 Doris 集群本身存在持续性问题（如磁盘满、BE 节点宕机），过多的重试只会延长任务的失败时间，并可能持续冲击有问题的集群。建议根据实际的故障恢复时间来合理设置。
  2. 问：任务日志里报 label already exists 错误，增加重试次数有用吗？
    • 答：这个错误通常与 2PC 两阶段提交和 sink_label_prefix 有关。它表示上一个批次的 Commit 请求可能成功了，但系统没有收到确认，导致重试时使用了相同的 Label。Doris 的幂等性保证了数据不会重复，但这个错误本身可能会导致重试失败。增加重试次数对此类特定逻辑错误帮助有限，更应关注 sink_label_prefix 的配置和网络稳定性。
  3. 问：哪些错误不会触发重试？
    • 答：通常，参数配置错误、数据格式错误、字段不匹配（schema error）等确定性的、无法通过重试解决的问题，系统会直接判定为失败而不会触发重试。重试主要针对网络问题、Doris 临时不可用等瞬时性、非确定性故障。

2.6. 注意事项

  • 副作用: 过高的重试次数会掩盖一些潜在的、需要被关注的持续性问题，并延长任务的端到端延迟。
  • 边界: 重试只对特定的、可恢复的异常生效。对于不可恢复的错误（如认证失败、SQL 语法错误等），该参数无效。
  • 不解决的问题: 无法解决由于 Doris 集群硬件故障、数据本身有问题（如格式、类型错误）或权限不足等根本性问题导致的写入失败。
  • 调整建议: 除非在极其不稳定的网络环境中，否则不建议将此值设置得过大。通常 3 到 5 次是比较合理的范围。

2.7. 总结说明

job.writer.sink_max_retries 控制写入 Doris 失败后的最大重试次数，默认为 3 次，用于保障数据写入的稳定性。如果您的网络环境不稳定或 Doris 集群偶有抖动，可适当调大此值（如 5 次）以增强容错性；在排查问题时可调小至 0 或 1 以实现快速失败。

3. job.writer.sink_record_size

3.1. 参数概述

  • 参数名: job.writer.sink_record_size
  • 适用范围/模块: Doris 数据写入（Writer/Sink）
  • 单位: 字节 (Bytes)
  • 默认值: 20,971,520 (即 20MB)
  • 核心作用: 基于数据大小的刷写阈值。当内存中缓存的数据累计达到这个字节数时，会触发一次刷写操作，将数据批量提交给 Doris。这是控制写入批次大小的核心参数之一。

3.2. 适用场景

典型现象

常见报错关键字

是否相关

建议调大/调小

Doris 端出现大量小文件或小批次导入，增加了合并压力。通常伴随着高频的 Stream Load。

too many versions

是

调大

任务吞吐量未达到预期，尤其是在高流量场景下，网络和 Doris 均有空闲资源。

是

调大

任务内存占用过高，导致 OOM (Out of Memory) 风险。

OutOfMemoryError

是

调小

单行数据非常大（例如包含大文本字段），导致单行就超过默认阈值，批次效果差。

是

调大

常见报错关键字

  • stream load error
  • StreamLoad error
  • doris sink error, retry times
  • Failed to load data into doris
  • Failed parse response

3.3. 调参建议 / 推荐配置

  • 默认推荐 (20MB): 适用于大多数业务场景，在内存使用和写入效率之间提供了良好的平衡。
  • 吞吐优先 / 高流量场景:
    • 起始值: 建议从 52,428,800 (50MB) 或 104,857,600 (100MB) 开始。
    • 安全方向: 逐步调大。
    • 预期影响: 显著增大每个批次的数据量，减少写入频率，有效提升端到端吞吐量，并降低 Doris 的元数据和合并压力。非常适合大批量数据同步或追加场景。
  • 内存敏感 / 实时性优先场景:
    • 起始值: 可考虑调小至 5,242,880 (5MB) 或 10,485,760 (10MB)。
    • 安全方向: 逐步调小。
    • 预期影响: 降低单批次数据大小，减少内存占用。在低流量下，可能与 sink_flush_interval_ms 配合，更快地触发刷写，略微提升实时性。
  • 排障临时配置:
    • 可临时调至一个较小值（如 1MB），以便更快地触发写入，观察数据流转情况。

3.4. 参数联动

sink_record_size 与 sink_record_count (行数) 和 sink_flush_interval_ms (时间) 共同决定刷写时机。刷写操作在三者中任意一个达到阈值时触发。
联动建议:

  • 核心关系: sink_record_size 和 sink_record_count 是最直接的批次大小控制器。通常，您只需要关心并调整这两个参数中的一个，另一个可以保持默认或设置为一个非常大的值，以避免干扰。
  • 如何选择:
    • 如果您的数据行大小比较均匀，使用 sink_record_count 更直观。
    • 如果您的数据行大小差异很大（例如，有的行几十字节，有的行几 MB），使用 sink_record_size 能更好地控制内存使用和批次大小的稳定性。
  • 将此参数与 sink_buffer_size、sink_buffer_count 一起调整。批次大小 (sink_record_size) 不应远大于总缓冲区大小 (sink_buffer_size * sink_buffer_count)，否则可能导致内存压力。

4. job.writer.sink_record_count

4.1. 参数概述

  • 参数名: job.writer.sink_record_count
  • 适用范围/模块: Doris 数据写入（Writer/Sink）
  • 单位: 行
  • 默认值: 100,000
  • 核心作用: 基于行数的刷写阈值。当内存中缓存的数据累计达到这个行数时，会触发一次刷写操作。这是另一个控制写入批次大小的核心参数。

4.2. 适用场景

典型现象

常见报错关键字

是否相关

建议调大/调小

Doris 端出现大量小文件或小批次导入，增加了合并压力。

too many versions

是

调大

任务吞吐量未达到预期，尤其是在数据行本身较小的高流量场景。

是

调大

任务内存占用过高，尤其是当 sink_record_size 设置得很大时。

OutOfMemoryError

是

调小

常见报错关键字

  • stream load error
  • StreamLoad error
  • doris sink error, retry times
  • Failed to load data into doris
  • Commit failed

4.3. 调参建议 / 推荐配置

  • 默认推荐 (100,000 行): 适用于大多数行大小适中的场景。
  • 吞吐优先 / 行较小的场景:
    • 起始值: 建议从 200,000 或 500,000 行开始。
    • 安全方向: 逐步调大。
    • 预期影响: 增大批次，提升吞吐，降低 Doris 压力。
  • 内存敏感 / 行较大的场景:
    • 起始值: 可考虑调小至 50,000 或 10,000 行。
    • 安全方向: 逐步调小。
    • 预期影响: 减少内存占用，避免因行数过多而导致批次字节大小超出预期。

4.4. 共同的 FAQ、注意事项和总结 (针对 sink_record_size & sink_record_count)

FAQ（用户提问）

  1. 问：sink_record_size 和 sink_record_count 我应该同时调整吗？
    • 答：不建议。通常您只需关注一个。如果您的数据行大小稳定，调 sink_record_count 更直观。如果行大小不定，调 sink_record_size 更能稳定控制内存和批次。可以将另一个参数设置得非常大，使其基本不起作用。
  2. 问：为什么我把批次大小调得很大，吞吐量反而下降了？
    • 答：可能原因有几个：1) 批次过大导致单次写入的准备和提交时间变长，如果 sink_flush_interval_ms 设置得过小，可能导致频繁的时间触发，而批次大小实际未达到；2) 批次大小超过了 Doris Stream Load 的推荐上限（通常建议单次导入在 100MB-1GB 之间），导致 Doris 处理效率下降；3) 增大了内存压力，可能引发 GC，影响任务性能。
  3. 问：这两个参数会影响数据一致性吗？
    • 答：不会。这两个参数只影响数据分批的策略，不影响数据写入的原子性和一致性。数据要么整个批次成功，要么整个批次失败重试，不会出现部分写入的情况。

注意事项

  • 副作用: 过大的批次会增加任务的内存消耗，并可能增加单次写入失败后的重试成本。同时，也会略微增加端到端的数据延迟，因为需要等待更长时间才能凑够一个大批次。
  • 边界: 批次大小会受到 Doris 本身配置的限制，例如 stream_load_max_mb 等参数，过大的批次可能被 Doris 拒绝。
  • 不解决的问题: 无法解决源端读取慢、网络带宽瓶颈等上游问题导致的吞吐量上不去。
  • 调整建议: 调整时建议以翻倍或减半的方式进行，并密切关注任务的内存使用（JVM GC 情况）和 Doris 的负载变化。

总结说明

job.writer.sink_record_size (默认20MB) 和 job.writer.sink_record_count (默认10万行) 共同决定了向 Doris 写入数据时每个批次的大小。为了提升吞吐量和降低 Doris 压力，您可以适当调大这两个值中的一个；为了控制内存或在低流量下提升一点实时性，可以适当调小。通常建议您只调整其中一个，并将另一个设置得很大以避免干扰。

5. job.writer.sink_buffer_size

5.1. 参数概述

  • 参数名: job.writer.sink_buffer_size
  • 适用范围/模块: Doris 数据写入（Writer/Sink）
  • 单位: 字节 (Bytes)
  • 默认值: 1,048,576 (即 1MB)
  • 核心作用: 定义了内部数据流（RecordStream）中单个缓冲区（Buffer）的大小。数据在被序列化并发往 Doris 之前，会先暂存在这些缓冲区中。

5.2. 适用场景

典型现象

常见报错关键字

是否相关

建议调大/调小

任务内存占用过高（OOM），尤其是在高并发或 sink_buffer_count 值也较大的情况下。

OutOfMemoryError

是

调小

单行数据记录本身非常大，超过了 1MB，导致一条记录都无法装入一个缓冲区。

Record too large (类似概念)

是

调大

系统吞吐量达到瓶颈，且 CPU 和网络资源有富余，可能是缓冲区设置不当导致的数据流转不畅。

可能相关

适当调大

常见报错关键字

  • failed to stream load data
  • stream load error
  • StreamLoad error
  • OutOfMemoryError

5.3. 调参建议 / 推荐配置

  • 默认推荐 (1MB): 适用于绝大多数场景，特别是对于行大小在几 KB 到几十 KB 的数据，这是一个比较高效且内存友好的配置。
  • 大记录 / 吞吐优先场景:
    • 起始值: 建议根据平均行大小进行估算，例如，如果平均行大小为 100KB，可以考虑将缓冲区设置为 4MB (4194304) 或 8MB (8388608)，以容纳更多的记录，减少缓冲区交换的频率。
    • 安全方向: 逐步调大。
    • 预期影响: 提升大数据记录的处理能力，减少内存分配和GC的频率，可能有助于提升吞吐量。
  • 内存极度受限的场景:
    • 起始值: 可调小至 512KB (524288) 或 256KB (262144)。
    • 安全方向: 逐步调小。
    • 预期影响: 显著降低任务的内存占用，但可能会增加数据在缓冲区之间流转的开销，略微影响性能。

6. job.writer.sink_buffer_count

6.1. 参数概述

  • 参数名: job.writer.sink_buffer_count
  • 适用范围/模块: Doris 数据写入（Writer/Sink）
  • 单位: 个
  • 默认值: 3
  • 核心作用: 定义了在数据写入链路中，可以同时存在的缓冲区（Buffer）的最大数量。它构成了一个缓冲池，用于平滑数据处理和网络发送之间的速度差异。

6.2. 适用场景

典型现象

常见报错关键字

是否相关

建议调大/调小

任务因数据处理（序列化）与网络发送速度不匹配而出现卡顿。例如，网络发送慢，导致处理线程无可用缓冲区可写。

是

调大

任务内存占用过高（OOM），尤其是在 sink_buffer_size 值也较大的情况下。

OutOfMemoryError

是

调小

希望在不增加单个缓冲区大小的情况下，提升系统的缓冲能力。

是

调大

常见报错关键字

  • failed to stream load data
  • stream load error
  • StreamLoad error
  • OutOfMemoryError

6.3. 调参建议 / 推荐配置

  • 默认推荐 (3个): 采用经典的“双缓冲”思想（一个读、一个写、一个备用），能够应对大部分场景。
  • 高延迟网络 / 生产消费速度不均场景:
    • 起始值: 建议设置为 5 或更高。
    • 安全方向: 逐步调大。
    • 预期影响: 提供更多的缓冲空间，使得数据生产方（处理线程）和消费方（发送线程）可以更独立地工作，减少因速度差异造成的相互等待，提升整体流水线效率。
  • 内存极度受限的场景:
    • 起始值: 可调小至 2。
    • 安全方向: 调小。
    • 预期影响: 降低内存占用。设置为 2 也能工作，但会降低缓冲效果；不建议设置为 1，那样会完全失去缓冲意义。

6.4. 共同的参数联动、FAQ、注意事项和总结 (针对 sink_buffer_size & sink_buffer_count)

参数联动

这两个参数直接决定了写入端的总缓冲能力：总缓冲内存 ≈ sink_buffer_size × sink_buffer_count × 并发度(parallelism)

  • 与 sink_record_size 的关系:一个批次的数据（由 sink_record_size 或 sink_record_count 决定）在发送前会被写入这些 Buffer。理论上，总缓冲内存应至少能容纳一个完整的批次，并有一定余量。如果 sink_record_size 远大于 sink_buffer_size，意味着一个批次的数据需要跨越多个 Buffer，这会增加管理的复杂性。
  • 调整策略:
    • 如果想在不增加内存占用的前提下提升缓冲效果，可以**“一增一减”**：适度调小 sink_buffer_size，同时调大 sink_buffer_count。
    • 如果任务 OOM，应优先考虑同时调小这两个参数，或在保持 sink_buffer_count 不变的情况下，主要调小 sink_buffer_size。

FAQ（用户提问）

  1. 问：这两个参数和 sink_record_size 有什么区别？
    • 答：可以这样理解：sink_record_size 定义了“包裹”的大小（我要寄多大一箱货），而 sink_buffer_size 和 sink_buffer_count 定义了“仓库”的容量和隔间（我有多少个、多大的临时货架来放这些包裹）。“包裹”打包好后，会放到“货架”上，等待卡车（网络线程）来拉走。
  2. 问：是不是把总缓冲内存调得越大，性能就越好？
    • 答：不是。缓冲区的目的是平滑速度差异，过大的缓冲并不能无限提升性能，反而会徒增内存消耗和 Full GC 的风险。当生产和消费速度基本匹配时，过大的缓冲就失去了意义。
  3. 问：调整了这两个参数，为什么任务内存占用没变化？
    • 答：请确认您的任务并发度。总内存占用是与并发度成正比的。如果您有 4 个并发，那么总缓冲内存就是 sink_buffer_size × sink_buffer_count × 4。此外，JVM 的内存管理机制也可能导致您在监控中看到的内存变化有一定延迟。

注意事项

  • 副作用: 不恰当的配置是导致 OOM 的常见原因之一。调整时必须综合考虑任务的并发度和分配给任务的总内存。
  • 边界: 这两个参数控制的是 JVM 堆内内存的使用。如果使用了堆外内存（Off-Heap），则不受此直接控制。
  • 不解决的问题: 无法解决因数据源读取慢、或目标端 Doris 持续无响应导致的性能问题。它们主要优化的是写入端内部的数据流转效率。
  • 调整建议: 调整前，请先通过 jmap 或其他 JVM 工具了解当前任务的内存分配情况。调整后，密切关注 GC 日志和内存监控，确保没有引入新的稳定性问题。

总结说明

sink_buffer_size (单个缓冲区大小) 和 sink_buffer_count (缓冲区数量) 共同决定了数据写入 Doris 前的内存缓冲能力，其总大小约为 size * count * 并发数。若任务因内存溢出（OOM）而失败，应适当调小它们；若网络延迟高或处理/发送速度不均，可适当增加 sink_buffer_count 以平滑数据流。请在调整时密切关注任务的内存使用情况。

7. job.writer.sink_label_prefix

7.1. 参数概述

  • 参数名: job.writer.sink_label_prefix
  • 适用范围/模块: Doris 数据写入（Writer/Sink）
  • 单位: N/A (字符串)
  • 默认值: "" (空字符串)
  • 核心作用: 为 Doris Stream Load 和 2PC（两阶段提交）的导入任务提供一个自定义的 Label 前缀。Doris 使用 Label 来唯一标识每一次导入，从而实现幂等性（同一 Label 的任务重复提交，只有第一次会生效）。

7.2. 适用场景

典型现象

常见报错关键字

是否相关

建议调大/调小

任务因网络或超时问题重试时，出现 Label already used 或 Label already exists 错误，导致任务最终失败。

Label already used, Label already exists, ETL_QUALITY_UNSATISFIED

是

建议配置

需要从外部系统排查或关联 DTS 写入的特定批次。例如，希望在 Doris 的导入历史中，能快速识别出由某个特定任务生成的导入作业。

是

建议配置

多个不同的任务可能在极短时间内向同一个 Doris 表写入数据，存在极低概率的 Label 冲突风险（当默认的随机生成策略恰好产生相同 Label 时）。

是

建议配置

常见报错关键字

  • Label already exist
  • Label already exist and load job finished, change you label prefix or restore from latest savepoint!
  • has already been used, relate to txn
  • is already COMMITTED, not pre-committed.
  • try abort committed transaction, do you recover from old savepoint?

7.3. 调参建议 / 推荐配置

  • 默认推荐 (空字符串): 在这种情况下，系统会生成一个完全随机的 UUID 作为 Label。这在大多数情况下是安全的，但当发生需要重试的场景时，如果前一次请求实际已成功但客户端未收到响应，重试时会生成新的随机 Label，可能不符合严格的幂等性预期（尽管在 2PC 机制下，Doris 侧的事务处理能提供保障）。
  • 生产环境 / 高可靠性要求:
    • 建议配置: 设置一个对当前任务有意义的、全局唯一的前缀。例如，可以使用任务 ID、作业名或其他固定标识符。
      • 示例: my_project_user_table_sync_
    • 预期影响:
      1. 增强幂等性：系统生成的最终 Label 将是 [sink_label_prefix]_[checkpoint_id]_[subtask_id] 这样的结构。当任务发生 Checkpoint 级别的重试（Failover）时，它会使用相同的 checkpoint_id 和前缀来重新生成 Label。如果上一次的导入已经成功，Doris 会直接返回成功，任务可以继续，有效避免了 Label already used 导致的失败。
      2. 可观测性：在 Doris 的 SHOW LOAD 结果或 fe.log 中，可以根据这个固定的前缀快速筛选和定位到特定任务的导入记录，极大地方便了问题排查。

7.4. 参数联动

sink_label_prefix 与 sink_enable_2PC (两阶段提交) 紧密相关。

  • 当 sink_enable_2PC 启用时，配置一个固定的 sink_label_prefix 是强烈推荐的。这确保了从 Pre-commit 到 Commit 再到重试的整个过程中，事务的幂等性标识是稳定和可预测的。
  • 如果没有配置 sink_label_prefix，虽然 2PC 机制本身能保证事务的最终一致性，但在某些异常恢复场景下，日志中可能会出现与 Label 相关的告警或错误，增加排查难度。

7.5. FAQ（用户提问）

  1. 问：这个前缀是不是随便填什么都可以？
    • 答：可以，但强烈建议您使用对任务有识别意义的字符串，例如 [项目名]_[业务]_[表名] 的组合，并确保它在您的所有 Doris 写入任务中是唯一的。这样既能避免冲突，也方便后续运维。
  2. 问：配置了 sink_label_prefix 后，是不是就不会再有 Label already used 的错误了？
    • 答：在任务因 Checkpoint 恢复而重试的场景下，是的，这正是解决该问题的关键。但如果您手动克隆一个任务（包括其 sink_label_prefix）并同时运行，它们可能会因为生成完全相同的 Label 而产生冲突。因此，确保前缀的唯一性非常重要。
  3. 问：不配置这个参数，数据会重复吗？
    • 答：在启用了 2PC 的情况下，通常不会。Doris 的事务机制会保证最终的原子性。不配置的主要问题是，当发生需要重试的特定异常（如 Commit 请求超时）时，任务可能会因为 Label already used 错误而中断，尽管数据在 Doris 端实际已经成功。配置前缀能让任务在这种情况下更平滑地恢复。

7.6. 注意事项

  • 唯一性: sink_label_prefix 的核心价值在于其在多个任务之间的唯一性。请建立命名规范，确保不会在不同的并发任务中使用了相同的前缀写入同一个表。
  • 长度限制: Doris Label 本身有长度限制（通常为 128 字节），因此前缀不宜过长。
  • 不解决的问题: 无法解决非幂等性问题导致的写入失败，例如数据格式错误、权限问题等。它只专注于解决因重复提交相同导入请求而引发的问题。
  • 调整建议: 对于所有生产环境的、要求高可靠性的数据同步任务，都建议配置此参数。

7.7. 总结说明

job.writer.sink_label_prefix 用于为 Doris 导入任务设置一个固定的、唯一的 Label 前缀，以增强写入操作的幂等性（防止数据重复）。强烈建议在所有生产任务中，将此参数配置为任务的唯一标识（如任务ID或作业名），这能有效避免因网络重试导致的 Label already used 错误，并极大地方便问题排查。

8. 网络请求相关参数 (request_*)

这组参数控制着写入任务与 Doris FE（Frontend）节点进行 REST API 通信时的网络行为，包括建连超时、读取超时和内部重试。它们是应对网络不稳、FE 繁忙等问题的关键调节旋钮。

  • job.writer.request_connect_timeouts: 建立到 Doris FE HTTP 服务的连接时，允许等待的最长时间。
  • job.writer.request_read_timeouts: 连接建立后，等待 FE 返回响应数据的最长时间。
  • job.writer.request_retries: 当上述请求发生可重试的失败（如超时）时，内部执行的最大重试次数。

8.1. 参数概述

  • 参数名:
    • job.writer.request_connect_timeouts
    • job.writer.request_read_timeouts
    • job.writer.request_retries
  • 适用范围/模块: Doris 数据写入（与 FE 的 REST API 交互）
  • 单位:
    • *_timeouts: 毫秒 (ms)
    • *_retries: 次
  • 默认值:
    • request_connect_timeouts: 30,000 (30秒)
    • request_read_timeouts: 30,000 (30秒)
    • request_retries: 3
  • 核心作用: 增强与 Doris FE 通信的容错性和健壮性，防止因网络瞬时抖动或 FE 短暂繁忙导致整个写入任务失败。

8.2. 适用场景

典型现象

常见报错关键字

是否相关

建议调大/调小

跨机房/公网等高延迟网络环境下，任务因连接超时失败。

ConnectTimeoutException, connect timed out

是

调大 connect_timeouts

Doris FE 节点因元数据加载、大查询规划或 GC 暂停，导致 API 响应缓慢，任务读取超时。

ReadTimeoutException, read timed out

是

调大 read_timeouts

网络偶尔丢包或抖动，导致与 FE 的通信瞬间失败。

Connection refused, No route to host (瞬时)

是

调大 request_retries

希望在 FE 彻底无响应时能快速失败，不等太久。

是

调小全部三个参数

常见报错关键字

  • Failed to connected doris
  • Failed to get response from Doris FE
  • Failed to get response from Doris
  • Doris FE node
  • No Doris FE is available, please check configuration
  • Failed to get backend
  • Fe nodes not available

8.3. 调参建议 / 推荐配置

  • 默认推荐 (30秒超时, 3次重试): 对于部署在同一内网、网络质量良好的环境来说，这个配置足够应对大多数情况。
  • 高延迟或不稳定网络环境:
    • 起始值:
      • request_connect_timeouts: 建议调大至 60000 (60秒)。
      • request_read_timeouts: 建议调大至 60000 (60秒) 或更高。
      • request_retries: 建议调大至 5 次。
    • 安全方向: 调大。
    • 预期影响: 给予网络请求更长的宽限时间，并增加重试机会，能有效容忍网络的高延迟和瞬时故障，提升任务在恶劣网络环境下的成功率。
  • FE 节点负载高 / 响应慢场景:
    • 核心调整: 主要调大 request_read_timeouts。如果 FE 经常因为负载问题导致响应慢，可以大胆地将其设置为 120000 (2分钟) 甚至更长。
    • 预期影响: 防止因 FE 短暂的繁忙（例如，正在进行元数据的大规模加载或复杂的查询计划生成）而导致写入任务不必要地失败。
  • 快速失败 / 排障场景:
    • 起始值:
      • *_timeouts: 调小至 5000 (5秒)。
      • *_retries: 调小至 0 或 1。
    • 安全方向: 调小。
    • 预期影响: 使任务在无法与 FE 正常通信时能迅速失败，避免长时间等待，加快问题定位。

8.4. 参数联动

这三个参数紧密耦合，共同决定了单次 API 交互的最大容忍时间。

  • 最大等待时间 ≈ (request_connect_timeouts + request_read_timeouts) × (request_retries + 1)
  • 与 job.writer.sink_max_retries 的关系:
    • request_retries 是内部 HTTP 请求级别的重试。
    • sink_max_retries 是整个数据批次写入流程（Stream Load）级别的重试。
    • 一次批次写入的失败，可能其内部已经历了多次 HTTP 请求的失败和重试。如果两个重试次数都设置得很大，任务在最终失败前会等待非常长的时间。
    • 建议: 优先调整 request_* 系列参数来应对网络和 FE 的瞬时问题。sink_max_retries 作为更上一层的保障。

8.5. FAQ（用户提问）

  1. 问：connect_timeouts 和 read_timeouts 有什么区别？
    • 答：connect_timeouts 是指从发起连接请求到成功建立 TCP 连接的最长等待时间，主要受网络延迟影响。read_timeouts 是指连接成功后，发送数据到开始接收到第一个字节响应的最长等待时间，主要受对端服务器（这里是 Doris FE）处理请求的速度影响。
  2. 问：我应该把超时时间设置得越长越好吗？
    • 答：不一定。过长的超时时间会使任务在面对真正的、持续性的网络或服务问题时，表现为长时间“卡死”或无响应，难以被及时发现。合理的配置应该略大于正常情况下最慢一次请求的耗时，并为异常波动留出余量。
  3. 问：为什么我调大了 request_retries，任务还是因为超时失败了？
    • 答：request_retries 只在发生可重试的异常（如超时）后生效。如果您的超时时间设置得过短，每次重试都可能因为同样的原因再次超时，最终耗尽重试次数。在这种情况下，您应该首先考虑延长超时时间 (*_timeouts)。

8.6. 注意事项

  • 副作用: 过长的超时和过多的重试会掩盖潜在的系统性问题，并使得任务在异常情况下恢复缓慢。
  • 边界: 这组参数仅影响与 Doris FE 的 REST API 通信，不影响向 BE（Backend）节点进行 Stream Load 的数据传输本身的超时。数据传输的超时由 stream_load_properties 中的 timeout 参数控制。
  • 不解决的问题: 无法解决 FE 节点宕机、DNS 解析失败、防火墙阻断等持续性的连接问题。
  • 调整建议: 调整时应基于对网络状况和 FE 负载的实际评估。如果没有明确的证据表明存在超时问题，保持默认值是比较安全的选择。

8.7. 总结说明

request_connect_timeouts (连接超时), request_read_timeouts (读取超时) 和 request_retries (重试次数) 控制着与 Doris FE 节点的网络通信行为。当您的网络环境延迟高或 FE 节点负载重时，可适当调大这些值（如超时时间至 60 秒，重试次数至 5 次）以增强任务稳定性；反之，在排障时可调小以实现快速失败。

9. job.writer.stream_load_properties

9.1. 参数概述

  • 参数名: job.writer.stream_load_properties
  • 适用范围/模块: Doris 数据写入（Writer/Sink）
  • 单位: N/A (键值对 Map)
  • 默认值: {} (空 Map)
  • 核心作用: 提供一个灵活的“透传”通道，允许用户将 Doris Stream Load 支持的任何原生 Header 参数，以键值对的形式直接传递给导入任务。这使得用户可以使用一些 DTS 尚未直接封装的高级或新版 Doris 功能。

9.2. 适用场景

这个参数非常灵活，其适用场景取决于您想使用哪个具体的 Stream Load 原生参数。以下是一些常见的例子：

典型现象 / 需求

相关的 Stream Load 参数

是否相关

建议配置

数据传输本身耗时很长，导致写入因超时失败，尤其是在写入大批量数据或跨公网时。

timeout

是

增加 timeout 值

源数据中存在少量脏数据（如格式错误），不希望因此导致整个批次失败。

max_filter_ratio

是

设置合理的 max_filter_ratio

需要对写入的数据进行一些过滤或转换，例如使用 where 子句。

where

是

配置 where 表达式

希望关闭部分列的严格模式或进行时区转换等。

strict_mode, timezone

是

按需配置

需要指定写入特定的存储序列（Sequence Column），用于 UNIQUE KEY 模型的行序控制。

sequence_col

是

指定 sequence_col

常见报错关键字

  • stream load error:
  • StreamLoad error
  • Failed to load data into doris
  • ETIMEDOUT
  • timeout
  • max_filter_ratio

9.3. 调参建议 / 推荐配置

配置格式为 JSON Map 形式的字符串，例如: {"timeout":"600", "max_filter_ratio":"0.1"}

  • 通用场景 - 调整导入超时:
    • 参数: timeout (单位: 秒)
    • 建议配置: 如果您的批次很大（例如，超过 100MB）或网络延迟较高，Doris 默认的导入超时时间可能不够。建议根据 sink_record_size 估算传输和处理时间，并设置一个更长的超时。
      • 起始值: {"timeout": "600"} (10分钟)
      • 预期影响: 防止因数据导入过程耗时过长而导致的 ETIMEDOUT 或 gateway timeout 错误。
  • 容忍脏数据场景:
    • 参数: max_filter_ratio (0.0 到 1.0 之间的小数)
    • 建议配置: 如果您可以容忍一部分数据因质量问题被过滤掉，可以设置此参数。
      • 起始值: {"max_filter_ratio": "0.05"} (允许 5% 的数据被过滤)
      • 预期影响: 即使批次中存在少量不符合表结构或格式要求的数据行，导入任务也能成功，这些脏数据会被丢弃。这在处理半结构化或质量不佳的数据时非常有用。
  • 按条件写入场景:
    • 参数: where
    • 建议配置: 提供一个 SQL WHERE 子句中的表达式，用于在数据写入前进行过滤。
      • 示例: {"where": "age > 18 and city = 'Beijing'"}
      • 预期影响: 只有满足 where 条件的数据才会被最终写入 Doris，实现了在 Sink 端的行级过滤。

9.4. 参数联动

stream_load_properties 中的参数是直接透传给 Doris 的，因此它们的行为和联动关系遵循 Doris Stream Load 的官方文档。

  • timeout vs. request_read_timeouts:
    • request_read_timeouts 控制的是与 FE 的元数据交互超时。
    • stream_load_properties 中的 timeout 控制的是向 BE 传输和处理数据的整个 Stream Load 过程的超时。
    • 如果您遇到写入超时，首先要根据报错信息判断是哪个阶段超时，再决定调整哪个参数。

9.5. FAQ（用户提问）

  1. 问：我可以在这里配置哪些参数？
    • 答：理论上，Doris 官方文档中列出的所有 Stream Load Header 参数都可以通过这里配置。建议您在配置前，查阅您所使用的 Doris 版本对应的官方文档，以获取最准确的参数列表和说明。
  2. 问：配置了 max_filter_ratio 之后，在哪里能看到哪些数据被过滤了？
    • 答：在 Doris FE 的日志 fe.log 中，或通过 SHOW LOAD 命令查看特定 Label 的导入结果，其中会有一个 URL。访问该 URL 可以获取到详细的错误信息和被过滤的脏数据行。
  3. 问：这个参数和直接在作业配置页面上的其他参数是什么关系？
    • 答：DTS 提供的其他参数（如 sink_max_retries）是 DTS 引擎层面的封装。stream_load_properties 则是一个“逃生舱”或“高级通道”，它允许您使用那些 DTS 尚未直接封装的、更底层的 Doris 原生功能。如果同一个功能既有 DTS 参数，又可以在这里配置，通常 DTS 参数的优先级更高或两者会合并，具体行为可能因版本而异，建议避免重复配置。

9.6. 注意事项

  • 版本兼容性: 在此配置的参数必须是您当前连接的 Doris 版本所支持的。如果使用了新版才有的参数，在老版本 Doris 上会报错。
  • 语法正确性: 参数的键和值都必须是字符串。值的格式需要严格遵守 Doris 的要求（例如，布尔值是 "true" 或 "false"，数值也是字符串形式）。
  • 不解决的问题: 无法解决 DTS 引擎本身的问题，例如数据读取慢、Checkpoint 失败等。它只作用于最终递交给 Doris 的 Stream Load 请求。
  • 调整建议: 在使用不熟悉的参数前，强烈建议先在测试环境中用 curl 命令手动构造 Stream Load 请求进行验证，确保参数行为符合预期。

9.7. 总结说明

job.writer.stream_load_properties 是一个高级配置项，允许您直接向 Doris 写入任务透传其原生的导入参数（如 timeout, max_filter_ratio 等）。当您需要容忍少量脏数据、延长数据导入超时时间或使用其他 DTS 未直接提供的 Doris 高级功能时，可以通过这个参数灵活实现。使用前请参考您 Doris 版本的官方文档以确保参数的有效性。

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