聊聊Starrocks的数据导入与避坑实践

一、引言

StarRocks 的导入能力不是单一入口，而是一组面向不同数据源、频率、规模和一致性目标的工程工具箱。StarRocks导入方案分为内置导入方式、生态连接器和 Stream Load 事务接口，其中内置方式包括 Insert、Stream Load、Broker Load、Pipe、Routine Load 和 Spark Load，生态工具包括 Kafka、Spark、Flink Connector 以及 SMT、DataX、CloudCanal 等。

不同导入方案在数据源、数据量、文件格式和导入频率上各有边界。Stream Load 面向本地 CSV/JSON 且单次建议 10 GB 以内；Broker Load 面向 HDFS、对象存储、本地或 NAS 的批量导入，支持 CSV、Parquet、ORC 和从 3.2.3 开始支持的 JSON；Pipe 从 3.2 起支持 HDFS 或 AWS S3 的批量或实时导入，单次规模可到 100 GB 到 TB 级；Routine Load 面向 Kafka 实时导入，微批规模为 MB 到 GB。

二、不同场景导入选型

面向不同的数据源，Starrocks数据导入都有对应的合适选择：对象存储可用 INSERT INTO SELECT FROM FILES、Broker Load 和部分场景下的 Pipe；本地文件系统和 NAS 可用 Stream Load 或 Broker Load；Kafka 可用 Kafka Connector、Routine Load 和 Stream Load 事务接口；复杂 ETL 预处理时，建议先用 Flink 读取 Kafka 并处理，再通过 Flink Connector 写入 StarRocks。

场景	优先方案	关键依据	落地提醒
开发测试、临时补数、小规模本地文件	Stream Load	HTTP PUT 同步导入，完成后直接返回结果；官方建议少量文件且每个文件不超过 10 GB 使用。	给每次导入设置唯一 label，根据返回 JSON 判断成功与否。
历史数据迁移、HDFS/对象存储大批文件	Broker Load	异步导入，支持多文件、通配符和单次多文件事务原子性；官方定位为数十到数百 GB。	用 information_schema.loads 查看作业结果，控制并发和文件切分。
S3/HDFS 目录持续落文件	Pipe	Pipe 定义 INSERT INTO SELECT FROM FILES，AUTO_INGEST 默认开启自动增量导入，默认轮询间隔 300 秒。	适合"文件到达即入仓"，但文件格式主要围绕 Parquet/ORC。
Kafka 简单实时流	Routine Load	常驻作业持续消费 Kafka Topic，支持 Exactly-Once，支持 CSV、JSON、Avro。	并行度受 Topic 分区、存活 BE、desired_concurrent_number 等共同限制。
Kafka Connect 生态和 Debezium CDC	Kafka Connector	相比 Routine Load，Kafka Connector 可借助 Kafka Connect converter 支持更丰富格式、支持自定义 transform、多 Topic 和 Confluent Cloud。	官方说明 Sink 保证 at-least-once；下游主键表需设计幂等。
复杂实时计算、维表关联、端到端一致性	Flink Connector	Flink Connector 在内存攒批后通过 Stream Load 写入，支持 DataStream、Table API & SQL、Python API；sink.version=V2 使用事务接口并推荐用于更稳定的 exactly-once。	配置 checkpoint、sink.semantic=exactly-once 和唯一 sink.label-prefix。

三、典型实施路径

• 本地文件到 StarRocks

Stream Load 适合导入脚本、离线产物或小批量补数。它基于 HTTP PUT 提交请求，FE 会通过 HTTP 重定向把请求转给 BE 或 CN，协调节点解析并分发数据，完成后向客户端返回导入结果；官方建议把请求发给 FE，以便通过轮询机制在集群内做负载均衡。

curl --location-trusted -u user:pwd \
  -H "label:ods_user_20260808_001" \
  -H "Expect:100-continue" \
  -H "column_separator:," \
  -H "columns:id,name,score" \
  -T user_score.csv -XPUT \
  http://fe:8030/api/ods/table_user_score/_stream_load

工程上要避免把 Stream Load 当成"无限大文件通道"， streaming_load_max_mb 默认最大 10 GB，并建议一次不要加载超过 10 GB；如果文件超过该大小，优先拆分为小文件，或调整参数但要承担性能下降和失败重试成本上升的风险。

• 对象存储和 HDFS 到 StarRocks

远端文件批量导入通常有三种工程形态：INSERT INTO SELECT FROM FILES() 适合用 SQL 直接读取 Parquet/ORC；Broker Load 适合异步大批导入；Pipe 适合持续扫描新增文件。

CREATE PIPE user_behavior_pipe
PROPERTIES ("AUTO_INGEST" = "TRUE", "POLL_INTERVAL" = "300")
AS
INSERT INTO user_behavior
SELECT * FROM FILES(
  "path" = "s3://bucket/path/*.parquet",
  "format" = "parquet",
  "aws.s3.region" = "ap-southeast-1"
);

Broker Load 的优势在于异步执行、多文件输入、通配符路径和单次导入事务原子性。Broker Load 支持一个作业内多个数据文件都成功或都失败，不会出现部分成功、部分失败；标签在数据库内唯一，可用于查看执行情况并防止重复导入。

• Kafka 到 StarRocks

Routine Load 更像 StarRocks 内部托管的 Kafka 消费作业。FE 创建常驻导入作业，并按期望并行度、Kafka Topic 分区数和存活 BE 数计算实际并行度，多个导入任务并行消费不同分区并通过 Stream Load 机制写入 StarRocks。

CREATE ROUTINE LOAD example_db.order_load ON order_tbl
COLUMNS TERMINATED BY ",",
COLUMNS(order_id, pay_dt, customer_name, nationality, price)
PROPERTIES ("desired_concurrent_number" = "5")
FROM KAFKA (
  "kafka_broker_list" = "broker1:9092,broker2:9092",
  "kafka_topic" = "order_topic",
  "property.kafka_default_offsets" = "OFFSET_BEGINNING"
);

Kafka Connector 则更适合已经标准化在 Kafka Connect 上的团队，Kafka Connector 相比 Routine Load 的优势包括更丰富的数据格式、可做自定义 transform、支持多个 Kafka Topic、支持 Confluent Cloud，并能更细地控制批次大小和并行度。

• Flink CDC 到 StarRocks

在实时加工计算场景下，Flink Connector 是最常见的生产主链路。它在 Flink 内部攒小批数据，再通过 Stream Load 一次性导入 StarRocks；sink.version=V2 会使用 Stream Load transaction 接口，官方推荐该模式，因为它优化内存使用并提供更稳定的 exactly-once 实现。

对于 MySQL CDC 场景，推荐把 StarRocks 表设计为主键表，并根据业务事件顺序、Flink 并行度和主键更新语义设计写入顺序。在多并行度情况下，用户需要保证数据以正确顺序写入；如果忽略这一点，乱序更新会比导入失败更难排查。

四、一致性与事务

StarRocks 的 label 不是可有可无的备注字段，而是导入幂等和排障的核心线索。每个导入作业都有数据库内唯一标签；FINISHED 状态的标签不可复用，CANCELLED 状态的标签可以复用，通常用于重试同一个作业以实现 Exactly-Once 语义。

Stream Load 事务接口从 2.4 起支持，提供 begin、load、prepare、commit、rollback 等 HTTP 接口，用于跨系统两阶段提交；从 4.0 起支持同一数据库内多表事务。该接口可帮助 Flink 等外部系统实现 Exactly-Once，并能通过一个导入作业合并多次小批写入以减少数据版本。

begin              prepare                commit
  |                  |                      |
  v                  v                      v
+---------+     +----------+           +-----------+
| PREPARE | --> | PREPARED | --------> | COMMITTED |
+---------+     +----------+           +-----------+
     |               |
     | rollback      | rollback
     v               v
  +---------+     +---------+
  | ABORTED |     | ABORTED |
  +---------+     +---------+

五、数据质量与变更语义

• 严格模式（Strict Mode）

严格模式用于控制字段类型不匹配、字段超长等转换失败时的数据行处理策略。开启严格模式时，StarRocks 会过滤错误数据行并返回错误详情；关闭严格模式时，转换失败字段会变为 NULL，错误行与正确行一起导入，但如果目标列不允许 NULL，仍会报错并过滤。

生产链路建议把 strict_mode 与 max_filter_ratio 成对设计。对于核心事实表、资金流水、库存扣减这类高价值数据，strict_mode=true 且 max_filter_ratio 接近 0 更安全；对于日志埋点和半结构化行为流，可以允许有限比例错误行，但必须把错误 URL、错误样例和导入标签接入监控。

• 导入时转换

StarRocks 支持在 Stream Load、Broker Load 和 Routine Load 中做导入时转换，包括跳过列、过滤行、生成衍生列，以及从文件路径中获取分区字段。

# Stream Load 中生成衍生列示例
-H "columns:date,year=year(date),month=month(date),day=day(date)"

这类能力适合轻量转换，例如列重排、日期派生、过滤脏行。复杂 ETL 仍建议放在 Flink、Spark 或湖仓计算层，因为导入阶段的表达式难以承载复杂关联、维表补全和长链路状态计算。

• 主键表变更

StarRocks 主键表支持通过 Stream Load、Broker Load 或 Routine Load 对表做 INSERT、UPDATE、DELETE 语义的数据变更，但不支持通过 Spark Load 或 INSERT 语句对表做这种导入变更；其内部支持 UPSERT 和 DELETE，不区分 INSERT 与 UPDATE。

如果数据文件只包含 UPSERT，可不添加 __op 字段；如果只包含 DELETE，必须添加 __op 并指定 DELETE；如果同时包含 UPSERT 和 DELETE，数据文件必须包含操作类型列，取值 0 表示 UPSERT、1 表示 DELETE。

六、避坑指南与最佳实践

坑点	表现	原因	建议
用 Stream Load 导入超大文件	超时、失败重试成本高、内存压力大	官方默认单文件最大 10 GB，并建议一次不要超过 10 GB。	拆分文件；超大批量走 Broker Load 或 Pipe。
高并发小批 Stream Load 产生过多版本	查询变慢、Compaction 压力上升、可能出现 too many versions	每个请求生成事务和版本；官方从 3.4 起提供 Merge Commit Beta 缓解。	小批高并发开启 Merge Commit 前先压测；并发为 1 时不建议使用。
Kafka JSON 消息被拆分	Routine Load 报 JSON 解析错误	官方示例说明每行一个 JSON 对象必须在一个 Kafka 消息中。	在生产者侧保证一条业务事件对应一条 Kafka message。
Flink 多并行度乱序写主键表	旧事件覆盖新事件	官方提醒多并行度下用户需要保证正确顺序写入。	按主键分区、控制 sink 并行度或引入条件更新。
错误理解 Kafka Connector 语义	重启后重复写入，指标短暂抖动	官方说明 Kafka Connector Sink 保证 at-least-once。	使用主键表幂等写入；对非幂等聚合谨慎。
忽略 CSV 空值约定	空字符串和 NULL 混淆	官方文档说明 CSV 中 \N 表示 NULL，a,,b 表示第二列为空字符串。	同步上游导出规范，把 NULL 和空串显式区分。
部分更新缺失主键列	导入失败或更新异常	官方说明所更新的列必须包含主键列。	CDC 和部分列更新链路中始终带上完整主键。

• 用标签治理导入生命周期:标签应包含业务域、表名、时间窗口、批次号或 checkpoint 信息，例如 dwd_order_20260808_0001。
• 按延迟预算设计批次:实时链路不是批次越小越好。Kafka Connector 的 Flush 会在缓存字节达到 bufferflush.maxbytes、距离上次落盘达到 bufferflush.intervalms，或达到 Kafka Connect offset 提交间隔时触发,频繁 Flush 会增加 CPU 和 I/O 使用。
• 主键表优先考虑幂等:实时 OLAP 的 CDC 写入通常不是"只追加"，而是包含更新、删除和乱序到达。主键表配合 UPSERT、DELETE、部分更新和条件更新，能把上游变更折叠为最新查询态。
• 把错误行纳入可观测性:导入监控至少要覆盖标签、状态、输入行数、成功行数、过滤行数、错误 URL、耗时、导入字节数和提交耗时。