【StarRocks系列】事务

[SQL 事务](#SQL 事务)

[Stream Load 事务接口](#Stream Load 事务接口)

一、接口原理

二、使用流程

SQL 事务

从 v3.5.0 开始，StarRocks 支持 SQL 事务，用于在将数据导入到多个表时，确保更新操作的原子性。

目前，StarRocks 的 SQL 事务仅支持 INSERT 和 SELECT 语句。update语句不支持事务

SQL 事务 | StarRocks

Stream Load 事务接口

为了支持和 Apache Flink®、Apache Kafka® 等其他系统之间实现跨系统的两阶段提交，并提升高并发 Stream Load 导入场景下的性能，StarRocks 自 2.4 版本起提供 Stream Load 事务接口。

以下是针对 StarRocks Stream Load 事务接口的原理和使用流程整理，结合官方文档内容提炼核心要点：

使用 Stream Load 事务接口导入 | StarRocks

一、接口原理（两阶段提交）

两阶段提交（2PC）机制
• 预提交 (/prepare): 临时持久化变更，事务状态可恢复（若此时 StarRocks 宕机，恢复后可继续提交或回滚）。 • 正式提交 (/commit): 持久化变更并对外可见。 • 回滚 (/rollback): 丢弃未提交的数据。
事务标签（Label）去重
• 每个事务通过唯一 Label 绑定，实现 "At-Most-Once"（至多一次）语义。 • 相同 Label 重复开启事务时，前一个事务会被强制回滚。
超时管理
• 通过 timeout 参数设置事务总超时时间。 • 通过 idle_transaction_timeout 设置空闲超时（无数据写入时自动回滚）。

二、使用流程

前提条件

权限: 用户需具备目标表的 INSERT 权限。
网络: 确保客户端可访问 FE（端口 8030）和 BE（端口 8040）。
数据限制:
• 仅支持 CSV/JSON 格式（单文件 ≤ 10GB）。 • CSV 需包含行分隔符（默认 \n），列分隔符若非 \t 需显式指定。

操作步骤

复制代码

# 1. 开启事务 (Begin)
curl --location-trusted -u <user>:<pwd> \
  -H "label:<label>" \                  # 唯一事务标签
  -H "db:<database>" -H "table:<table>" \
  -XPOST http://<fe_host>:8030/api/transaction/begin

# 2. 写入数据 (Load，可多次调用)
curl --location-trusted -u <user>:<pwd> \
  -H "label:<label>" \                  # 与 begin 相同标签
  -H "db:<database>" -H "table:<table>" \
  -T /path/to/data.csv \                # 数据文件路径
  -H "column_separator:," \             # 非默认分隔符时需指定
  -XPUT http://<fe_host>:8030/api/transaction/load

# 3. 预提交 (Prepare，可选)
curl --location-trusted -u <user>:<pwd> \
  -H "label:<label>" \
  -H "db:<database>" \
  -XPOST http://<fe_host>:8030/api/transaction/prepare

# 4. 提交事务 (Commit)
curl --location-trusted -u <user>:<pwd> \
  -H "label:<label>" \
  -H "db:<database>" \
  -XPOST http://<fe_host>:8030/api/transaction/commit

# 若需回滚 (Rollback)
curl --location-trusted -u <user>:<pwd> \
  -H "label:<label>" \
  -H "db:<database>" \
  -XPOST http://<fe_host>:8030/api/transaction/rollback

三、关键注意事项

一致性要求
• 同一事务中所有 /load 请求的参数必须完全一致（如分隔符、列映射）。 • 预提交后禁止继续写入数据。
接口约束
• 仅支持单表事务（跨表事务未来支持）。 • 仅支持单客户端写入（多客户端并发写入未来支持）。 • 若 begin/load/prepare 接口报错，事务自动回滚。
错误处理
• 事务不存在: 操作已超时或未初始化。 • 超时: 检查 FE 配置 stream_load_default_timeout_second。 • 标签重复: 更换 Label 或回滚旧事务。

四、接口优势

• Exactly-Once 语义

通过预提交 + 提交机制，与 Flink/Kafka 等系统实现跨系统两阶段提交。

• 提升导入性能

支持单事务内合并多次小批量写入，减少数据版本数，提升吞吐。

相关文档

• Stream Load 基础导入

• STREAM LOAD 命令详解

提示：事务接口适用于高并发小批量数据写入或需与外部系统协同保证精确一次语义的场景。

回滚是全局性的

StarRocks Stream Load 事务接口的回滚操作是针对事务涉及的所有 BE（Backend）节点的。这是由 StarRocks 的分布式架构和事务管理机制决定的。

具体原理如下：

分布式写入：
◦ 当你通过 /api/transaction/load 接口写入数据时，数据会被拆分成多个分片（根据表的分桶规则）。◦ 这些分片会被并行地发送到多个 BE 节点上进行写入和存储（写入的是事务临时缓冲区）。
事务协调（FE）：
◦ FE（Frontend）节点是事务的协调者。它负责管理整个事务的生命周期（Begin, Load, Prepare, Commit/Rollback）。◦ 当调用 /api/transaction/begin 开启一个事务时，FE 会生成一个全局唯一的 TxnId 并记录事务元信息。◦ 当调用 /api/transaction/load 时，FE 负责将数据分派到相关的 BE，并管理这些 BE 上的子任务状态。◦ 当调用 /api/transaction/rollback 时，FE 会向所有参与该事务（即接收了该事务数据分片的）BE 节点发送回滚指令。
BE 执行回滚：
◦ 收到 FE 发送的回滚指令 (TxnId) 后，每个相关的 BE 节点会：

▪ 清理掉属于这个 TxnId 的所有临时数据（这些数据在提交之前是存储在特殊的事务缓冲区或临时区域的，对用户查询不可见）。

▪ 释放该事务占用的资源（如内存）。

◦ 回滚操作是在所有参与该事务的 BE 上原子性地完成的。要么所有 BE 都成功清理了临时数据，要么整个回滚操作被视为失败（虽然这种失败非常罕见，通常由网络分区或BE节点宕机导致，此时需要依赖超时机制或人工介入）。

总结关键点：

• 全局性：回滚操作不是局部的，它作用于整个分布式事务。

• FE 协调：FE 是回滚命令的发起者和协调者。

• BE 执行：所有承载了该事务数据的 BE 节点都会执行清理临时数据的操作。

• 原子性目标：设计目标是确保所有参与事务的 BE 节点上的临时数据都被清除，保证事务的原子性（要么全做，要么全不做）。如果回滚过程中部分节点失败，系统状态可能不一致，需要依赖后续的超时机制或人工处理（这是分布式事务的常见挑战）。

因此，当你调用 /api/transaction/rollback 接口时，本质上是在请求 FE 去通知所有相关的 BE 节点，让它们丢弃掉该特定事务（TxnId）写入的所有临时数据，从而在整个集群范围内撤销该事务的所有数据写入操作。

参考文档

Apache InLong 实时同步数据到 StarRocks 原理与实践

StarRocks官网

使用 Stream Load 事务接口导入 | StarRocks

SQL 事务 | StarRocks