Doris Stream Load 报错排查与导入调优基线

Stream Load 报 -235（[E-235] Failed to init rowset builder）、传输中途断开的 Broken Pipe、Routine Load 报 offset 获取失败，这三类报错对应的根因分别是 tablet 版本堆积、传输链路中断、消费位点异常，处置方式互不相同；数据质量校验不通过是另一类报错（[DATA_QUALITY_ERROR] Encountered unqualified data），要按错误明细处理，别和 -235 混为一谈。导入吞吐低与可见延迟大则大多与 compaction 堆积、导入并发超限、对象存储 QPS 限流有关。下文按"报错码 → 根因 → 处置"给出门诊式对照，并在最后给出参数与并发的量化调优基线。

报错 -235：版本堆积，rowset builder 初始化失败

现象：导入返回 -235，报错信息是 [E-235] Failed to init rowset builder，导入整体失败；同一时段往往伴随导入变慢、publish timeout，BE 的 compaction 指标异常。

根因：官方导入 FAQ 明确 -235 是 rowset builder 初始化失败，与数据质量校验无关。本质是导入频率过高、compaction 跟不上，tablet 的版本数持续攀升并超过上限（BE 配置 max_tablet_version_num），新导入无法再为 tablet 创建版本。高频小批量导入、导入并发过高都会加速版本堆积。

处置顺序：

• 先降低导入频率、加大单批量：把高频小批合并成低频大批，给 compaction 留出追赶时间，这是根治手段。
• 同步观察 tablet 版本数与 compaction 指标，确认版本数回落、compaction 追平后，再逐步恢复导入节奏。
• 必要时调大 be.conf 的 max_tablet_version_num 争取缓冲时间，但不要超过 5000；这只是兜底，导入节奏不改，版本数还会顶回来。

[DATA_QUALITY_ERROR]：质量校验不通过

现象：导入结果报 [DATA_QUALITY_ERROR] Encountered unqualified data，HTTP 返回体里有 ErrorURL，常见伴随"被过滤行数超过阈值"的提示。

根因：Stream Load 默认 max_filter_ratio = 0，只要有任何一行数据不合格导入就会失败。常见不合格来源是类型转换失败（非法日期字符串、非数字串转数字）、必填列出现 NULL、列长度超限、列数与 CSV/JSON 定义不匹配（columns、jsonpaths、preceding lines 配置错位）。

处置顺序：

• 先下载 ErrorURL 指向的错误行明细，确认是哪一列、什么转换失败，错误明细里的信息通常足够定位。
• 数据源问题就修数据源（日期格式、编码、列对齐）；确属可容忍脏数据时再调大 max_filter_ratio，同时核对 strict_mode 开关是否与预期一致，并在导入结果里核对 filtered rows 数量。
• 把质量校验阈值写进数据生产契约，避免"为了导入成功把容忍度一路调大"，那是把数据质量问题延迟到查询侧爆发。

Broken Pipe：传输链路断开

现象：客户端侧报 Broken pipe 或连接被重置，导入请求中途失败，服务端没有完整收到数据。

根因：Stream Load 的数据流要经过接入层转发到 BE 节点，任何一跳的超时或缓冲配置不匹配都会断链。常见组合是中间代理（Nginx/负载均衡）的读超时小于导入耗时、客户端生成数据速率过慢导致整体超时、单批数据量过大超过 HTTP 超时上限，以及网络抖动。Stream Load 默认超时为 600 秒，timeout 参数可调，但调大超时只是兜底不是修复。

处置顺序：

• 缩小单批数据量并提高发送速率（数据压缩后传输，服务端支持压缩格式），让单批在超时窗口内稳定完成。
• 检查并调大代理层的读写超时与缓冲区，或让导入流量直连 BE、绕过会超时的转发层。
• 确认客户端与服务端之间的网络稳定性，重试机制要配合幂等的 label 语义使用，避免重试造成重复导入。
• 最后才调大 timeout。失败模式是无限放大超时来掩盖单批过大，结果把断链问题变成了"导入很慢"的隐性故障。

Routine Load：offset 获取失败

现象：Routine Load 作业报"获取 offset 失败"或 OFFSET_OUT_OF_RANGE 一类错误，作业进入 PAUSED 或反复重试，消费停滞。

根因：多数与消费位点和数据源可用性有关。作业暂停时间过长、位点已滑出消息保留期，是最常见原因；其次是数据源元数据不可达（网络隔离、认证或 ACL 变更）、分区数发生变化导致位点映射失效。

处置顺序：

• 先恢复数据源连通性与权限，确认作业配置里的 broker 列表与认证信息仍然有效。
• 位点过期时，用 ALTER ROUTINE LOAD 重新指定各分区的消费位点（从业务可接受的位置续传），再 RESUME ROUTINE LOAD 恢复作业，恢复后核对作业延迟是否在收敛。
• 评估保留期与最大暂停时长的匹配关系：保留期必须显著大于"故障发现 + 人工处置"的最长时间，否则下次还会过期。
• 分区扩缩容后重新核对分区与位点配置，让消费并发跟随分区数变化。

导入调优的量化基线

吞吐与可见延迟问题，先按下面的基线校准，再谈扩容。

• 单批数据量：以攒批后每批百 MB 量级、单次 Stream Load 控制在 1GB 以内作为起始基线，更大的批量改用面向批的导入方式，避免长事务与超时。
• Routine Load 默认参数：最大批次间隔默认 10 秒、最大批次行数默认 20 万行、期望并发默认 3。吞吐不足时优先增加分区数与消费并发，而不是加大单批——单批变大直接推高可见延迟。
• Stream Load 参数：默认超时 600 秒、mem_limit 默认 2GB，宽表或大字段场景按需上调，但以监控为准，不要拍脑袋翻倍。
• 并发阈值：单 BE 的导入并发受 compaction 能力与对象存储 QPS 共同约束，用阶梯压测找拐点：并发每加一档，观察导入耗时、错误率与版本堆积，出现 publish timeout 或错误率抬头就回退一档，那个拐点就是当前配置下的并发上限。
• compaction 堆积判别："导入成功但查询可见延迟大"多半是版本堆积、compaction 跟不上。观察 tablet 的版本数与 BE 的 compaction 指标，版本数持续攀升时先降导入频率与并发，给 compaction 留出追赶时间，而不是继续加压。
• 对象存储限流：远端存储部署下，导入与查询共享对象存储的带宽与 QPS，限流会让导入排队、可见延迟拉长。对策是导入与查询错峰、给导入链路独立的带宽/QPS 配额，或在存储侧扩容吞吐。

压测与基线迭代

基线是起点不是终点，正确做法是小规模压测逐档逼近。数据形态要贴近真实（列数、行宽、乱序程度），从低并发开始逐档加压，每档记录导入吞吐、单批耗时、错误率、tablet 版本数四项指标：吞吐不再随并发上升，或者错误率与版本数开始抬头，就把前一档定为当前配置的并发基线。换数据形态或集群规模后重新压测。一次压测只改一个变量（并发、单批量或 mem_limit），否则无法归因。每轮压测的四项指标留档，导入变慢时先与基线对比：指标还在基线内，查外部因素（存储限流、网络）；明显偏离基线，再走根因排查。

排查顺序与失败模式

拿到一个导入故障，建议固定按这个顺序走：看报错码定类别（质量 / 传输 / 位点）→ 下载错误明细或看事件日志确认根因 → 修根因后再动参数。两个典型失败模式要避免：用调大 max_filter_ratio 掩盖数据质量问题，以及用调大超时和并发掩盖单批过大、compaction 堆积的问题。参数只是基线，根因不除，报错只会换一种形式回来。官方的 导入 FAQ 与 导入最佳实践给出了更细的错误项与参数说明，社区也有 Stream Load 报错排查讨论可以对照。

定位示例：一次 -235 的走查（示意）

一次高频小批量的日常导入持续返回 -235，报错信息是 [E-235] Failed to init rowset builder。按前文顺序走：先看监控，tablet 版本数在最近几小时持续攀升，BE 的 compaction 任务积压、合并速度低于版本产生速度；导入侧是每分钟一次的小批量写入，版本生成速率远超 compaction 的消化能力。根因是导入频率过高导致版本堆积顶到 max_tablet_version_num 上限，而不是数据本身有问题——同一批数据换到一张低频导入的表上立刻成功。处置是把导入节奏改为每几分钟一次的批量写、同步加大单批量，必要时临时调大 be.conf 的 max_tablet_version_num（不超过 5000）争取缓冲；max_filter_ratio 与本类报错无关，不做调整。调整后 tablet 版本数逐步回落、compaction 追平，导入恢复，并按"低频大批"的节奏稳定运行。