SeaTunnel IoTDB Sink 连接器实战指南:配置、数据类型映射与写入原理
SeaTunnel IoTDB Sink 连接器实战指南:配置、数据类型映射与写入原理
SeaTunnel 的 IoTDB Sink 连接器用于将 SeaTunnel 任务处理后的数据批量写入 Apache IoTDB(时序数据库),适用于设备数据上云、传感器数据落库、工业时序指标归档等场景。本文以 IoTDB Sink 官方文档 为主体,结合连接器源码(connector-iotdb)与 E2E 测试配置,完整讲解支持引擎、数据类型映射、全部 Sink 选项、四种典型写入配置示例,以及底层写入链路与重试机制,帮助读者在真实作业中正确、高效地使用该连接器。
支持引擎
IoTDB Sink 连接器可运行于以下引擎:
- Spark
- Flink
- SeaTunnel Zeta
描述与核心特性
该连接器用于将数据写入 IoTDB,通过调用 IoTDB 的 insert RPC 完成写入,并具备以下能力边界:
- 精确一次(Exactly-Once):已支持。IoTDB 通过幂等写实现该语义——当两条数据携带相同的
key(设备路径)和timestamp(时间戳)时,新数据会覆盖旧数据,因此上游重复投递不会产生重复数据行。 - CDC:不支持。Sink 不会把行类型
UPDATE/DELETE当作 CDC 操作处理,所有行均按 insert 写入。
需要说明的是,当一行携带非唯一的 (device, timestamp) 组合时,写入按 upsert 语义处理——最新值覆盖之前的值。从源码看,这一语义由 IoTDBSinkClient.java 直接调用 IoTDB 官方 Session#insertRecords 批量接口实现,幂等性由 IoTDB 服务端依据 (device, timestamp) 主键特性保证。
支持的数据源信息
| 数据源 | 支持的版本 | 默认地址 |
|---|---|---|
| IoTDB | 0.13.0 <= version <= 1.3.X |
localhost:6667 |
连接器模块 pom.xml 中声明的 iotdb-session 客户端依赖版本为 0.13.1,与文档给出的版本范围一致;6667 是 IoTDB 默认的 RPC 服务端口。
数据类型映射
写入 IoTDB 前,SeaTunnel 行类型会被转换为 IoTDB 的 TSDataType,映射关系如下:
| IoTDB 数据类型 | SeaTunnel 数据类型 |
|---|---|
| BOOLEAN | BOOLEAN |
| INT32 | TINYINT |
| INT32 | SMALLINT |
| INT32 | INT |
| INT64 | BIGINT |
| FLOAT | FLOAT |
| DOUBLE | DOUBLE |
| TEXT | STRING |
该映射与序列化器源码 DefaultSeaTunnelRowSerializer.java 中的 convert(SeaTunnelDataType) 分支完全一致:TINYINT、SMALLINT、INT 统一转为 INT32,BIGINT 转 INT64,STRING 转 TEXT。在值转换阶段(同一文件 L191-L214),数值类型会进一步做窄化处理(如 intValue()、longValue()),因此上游字段的数值取值范围需要与目标测点类型匹配。
Sink 选项详解
下表完整列出 IoTDB Sink 支持的全部配置项(与 IoTDBSinkOptions.java 中的定义一一对应):
| 名称 | 类型 | 是否必传 | 默认值 | 描述 |
|---|---|---|---|---|
| node_urls | Array | 是 | - | IoTDB 集群地址,格式为 ["host1:port"] 或 ["host1:port","host2:port"] |
| username | String | 是 | - | IoTDB 用户的用户名 |
| password | String | 是 | - | IoTDB 用户的密码 |
| key_device | String | 是 | - | 在 SeaTunnelRow 中指定 IoTDB 设备 ID 的字段名 |
| key_timestamp | String | 否 | processing time | 在 SeaTunnelRow 中指定 IoTDB 时间戳的字段名。如果未指定,则使用处理时间作为时间戳 |
| key_measurement_fields | Array | 否 | 排除设备和时间字段 | 在 SeaTunnelRow 中指定 IoTDB 测点字段列表。未配置时,会写入除 key_device 和 key_timestamp 对应字段外的其他字段 |
| storage_group | String | 否 | - | 指定设备存储组(路径前缀)。例如:deviceId = ${storage_group} + "." + ${key_device} |
| batch_size | Integer | 否 | 1024 | 批量写入时,当缓存行数达到 batch_size,数据会刷新到 IoTDB 中 |
| max_retries | Integer | 否 | - | 写入失败后的最大重试次数 |
| retry_backoff_multiplier_ms | Integer | 否 | - | 用作生成下一个退避延迟的乘数 |
| max_retry_backoff_ms | Integer | 否 | - | 尝试重试对 IoTDB 的请求之前等待的时间量 |
| default_thrift_buffer_size | Integer | 否 | - | IoTDB 客户端的初始化 Thrift 缓冲区大小 |
| max_thrift_frame_size | Integer | 否 | - | IoTDB 客户端的最大 Thrift 帧大小 |
| zone_id | string | 否 | - | IoTDB 客户端使用的 java.time.ZoneId |
| enable_rpc_compression | Boolean | 否 | - | 在 IoTDB 客户端中启用 RPC 压缩 |
| connection_timeout_in_ms | Integer | 否 | - | 连接到 IoTDB 时等待的最长时间(毫秒) |
| common-options | 否 | - | Sink 插件通用参数,详见 Sink 通用选项 |
注意:配置
connection_timeout_in_ms前,必须同时配置enable_rpc_compression。这一约束在 SinkConfig.java 的loadConfig中以checkNotNull(sinkConfig.getEnableRPCCompression())强制校验,因为Session#open(enableRPCCompression, connectionTimeoutInMs)重载要求同时传入两个参数。
必传项与可选项的划分,与工厂类 IoTDBSinkFactory.java 中 OptionRule 的 required(...) 与 optional(...) 声明一致:node_urls、username、password、key_device 为必传,其余均为可选。
客户端连接类参数说明
default_thrift_buffer_size、max_thrift_frame_size、zone_id 三项会被透传给 IoTDB Session.Builder(见 IoTDBSinkClient.java);enable_rpc_compression 与 connection_timeout_in_ms 则用于控制 Session#open 的行为。zone_id 通过 ZoneId.of(...) 解析(SinkConfig.java),需填写合法的 java.time.ZoneId 名称。
写入规则
key_device必须指定 SeaTunnel 中保存 IoTDB 设备路径的字段名。storage_group是字符串前缀。配置后,最终设备路径由storage_group和key_device对应字段值拼接而成。key_timestamp可以指定STRING、BIGINT或TIMESTAMP类型字段。未配置时,连接器使用当前处理时间。- 未配置
key_measurement_fields时,会把除key_device和key_timestamp之外的所有字段写为测点。 - Sink 支持写入
STRING、BOOLEAN、TINYINT、SMALLINT、INT、BIGINT、FLOAT和DOUBLE类型测点。
写入规则在源码中的落地
上述规则在序列化器 DefaultSeaTunnelRowSerializer.java 中有精确实现:
- 时间戳提取(L71-L101):未配置
key_timestamp或字段值为null时返回System.currentTimeMillis()(即处理时间);STRING类型按Long.parseLong解析毫秒时间戳;TIMESTAMP类型按 UTC 时区转为 epoch 毫秒;BIGINT直接作为毫秒时间戳使用;其他类型会抛出UNSUPPORTED_DATA_TYPE异常。 - 设备路径拼接(L103-L116):未配置
storage_group时直接返回设备字段值;配置后若storage_group以.结尾或设备值以.开头则直接拼接,否则以.连接。 - 测点集合(L118-L130):未配置
key_measurement_fields时,取全部字段并排除设备字段与时间戳字段;配置后仅使用显式列出的字段。
示例:完整作业配置
以下 HOCON 配置演示了使用 FakeSource 生成数据并写入 IoTDB 的完整作业。env 与 source 部分定义了并行度、批处理模式与行结构:
env {
parallelism = 2
job.mode = "BATCH"
}
source {
FakeSource {
row.num = 16
bigint.template = [1664035200001]
schema = {
fields {
device_name = "string"
temperature = "float"
moisture = "int"
event_ts = "bigint"
c_string = "string"
c_boolean = "boolean"
c_tinyint = "tinyint"
c_smallint = "smallint"
c_int = "int"
c_bigint = "bigint"
c_float = "float"
c_double = "double"
}
}
}
}
上游 SeaTunnelRow 数据格式如下:
| device_name | temperature | moisture | event_ts | c_string | c_boolean | c_tinyint | c_smallint | c_int | c_bigint | c_float | c_double |
|---|---|---|---|---|---|---|---|---|---|---|---|
| root.test_group.device_a | 36.1 | 100 | 1664035200001 | abc1 | true | 1 | 1 | 1 | 2147483648 | 1.0 | 1.0 |
| root.test_group.device_b | 36.2 | 101 | 1664035200001 | abc2 | false | 2 | 2 | 2 | 2147483649 | 2.0 | 2.0 |
| root.test_group.device_c | 36.3 | 102 | 1664035200001 | abc3 | false | 3 | 3 | 3 | 2147483649 | 3.0 | 3.0 |
案例 1:只填写所需配置
仅配置必传项,使用当前处理时间作为时间戳,测点包含排除了 key_device 后的其余字段:
sink {
IoTDB {
node_urls = ["localhost:6667"]
username = "root"
password = "root"
key_device = "device_name" # 使用 device_name 字段作为 deviceId
}
}
写入后 IoTDB 查询结果如下(Time 列体现为处理时间):
IoTDB> SELECT * FROM root.test_group.* align by device;
+------------------------+------------------------+--------------+-----------+--------------+---------+----------+----------+-----------+------+-----------+--------+---------+
| Time| Device| temperature| moisture| event_ts| c_string| c_boolean| c_tinyint| c_smallint| c_int| c_bigint| c_float| c_double|
+------------------------+------------------------+--------------+-----------+--------------+---------+----------+----------+-----------+------+-----------+--------+---------+
|2023-09-01T00:00:00.001Z|root.test_group.device_a| 36.1| 100| 1664035200001| abc1| true| 1| 1| 1| 2147483648| 1.0| 1.0|
|2023-09-01T00:00:00.001Z|root.test_group.device_b| 36.2| 101| 1664035200001| abc2| false| 2| 2| 2| 2147483649| 2.0| 2.0|
|2023-09-01T00:00:00.001Z|root.test_group.device_c| 36.3| 102| 1664035200001| abc2| false| 3| 3| 3| 2147483649| 3.0| 3.0|
+------------------------+------------------------+--------------+-----------+--------------+---------+---------+-----------+-----------+------+-----------+--------+---------+
案例 2:使用源事件的时间
通过 key_timestamp 指定 event_ts 字段作为写入时间戳,测点自动排除设备字段与时间戳字段:
sink {
IoTDB {
node_urls = ["localhost:6667"]
username = "root"
password = "root"
key_device = "device_name" # 使用 device_name 字段作为 deviceId
key_timestamp = "event_ts" # 使用 event_ts 字段作为 timestamp
}
}
写入后 Time 列变为事件时间:
IoTDB> SELECT * FROM root.test_group.* align by device;
+------------------------+------------------------+--------------+-----------+--------------+---------+----------+----------+-----------+------+-----------+--------+---------+
| Time| Device| temperature| moisture| event_ts| c_string| c_boolean| c_tinyint| c_smallint| c_int| c_bigint| c_float| c_double|
+------------------------+------------------------+--------------+-----------+--------------+---------+----------+----------+-----------+------+-----------+--------+---------+
|2022-09-25T00:00:00.001Z|root.test_group.device_a| 36.1| 100| 1664035200001| abc1| true| 1| 1| 1| 2147483648| 1.0| 1.0|
|2022-09-25T00:00:00.001Z|root.test_group.device_b| 36.2| 101| 1664035200001| abc2| false| 2| 2| 2| 2147483649| 2.0| 2.0|
|2022-09-25T00:00:00.001Z|root.test_group.device_c| 36.3| 102| 1664035200001| abc2| false| 3| 3| 3| 2147483649| 3.0| 3.0|
+------------------------+------------------------+--------------+-----------+--------------+---------+---------+-----------+-----------+------+-----------+--------+---------+
案例 3:使用源事件时间并限制测点字段
通过 key_measurement_fields 仅写入指定的 temperature 与 moisture 两个测点:
sink {
IoTDB {
node_urls = ["localhost:6667"]
username = "root"
password = "root"
key_device = "device_name"
key_timestamp = "event_ts"
key_measurement_fields = ["temperature", "moisture"]
}
}
写入后 IoTDB 仅保存指定测点:
IoTDB> SELECT * FROM root.test_group.* align by device;
+------------------------+------------------------+--------------+-----------+
| Time| Device| temperature| moisture|
+------------------------+------------------------+--------------+-----------+
|2022-09-25T00:00:00.001Z|root.test_group.device_a| 36.1| 100|
|2022-09-25T00:00:00.001Z|root.test_group.device_b| 36.2| 101|
|2022-09-25T00:00:00.001Z|root.test_group.device_c| 36.3| 102|
+------------------------+------------------------+--------------+-----------+
案例 4:显式批量刷写的流式写入
对于长时间运行的流式作业,可以调大 batch_size 减少单行 RPC 开销。连接器在缓冲行数达到 batch_size 或 checkpoint 完成时刷新缓冲。配合 max_retries 和 max_retry_backoff_ms 可以让任务在 RPC 抖动时保持稳定:
env {
parallelism = 2
job.mode = "STREAMING"
checkpoint.interval = 10000
}
sink {
IoTDB {
node_urls = ["localhost:6667", "localhost:6668"]
username = "root"
password = "root"
key_device = "device_name"
key_timestamp = "event_ts"
batch_size = 2048
max_retries = 3
retry_backoff_multiplier_ms = 100
max_retry_backoff_ms = 5000
}
}
node_urls 支持传入多个 IoTDB 节点。Sink 会为每个任务选择一个活跃写入节点,并在活跃节点失败时切换到其它节点。
提示:E2E 测试配置 iotdb_source_to_sink.conf 给出了一个完整的「IoTDB Source → Replace 转换 → IoTDB Sink」示例,其中 Sink 部分通过
key_measurement_fields显式列出全部测点,并设置batch_size = 1便于逐行验证写入结果,可作为真实作业配置的参照。
底层写入与重试机制
理解底层写入链路有助于调优参数。整体流程如下:
- 序列化:
IoTDBSinkWriter.write将每条SeaTunnelRow交给DefaultSeaTunnelRowSerializer,转换为IoTDBRecord(设备、时间戳、测点名、测点类型与值),见 IoTDBSinkWriter.java。 - 缓冲:
IoTDBSinkClient.write将记录加入内存batchList,当行数达到batch_size时触发flush,见 IoTDBSinkClient.java。 - 批量写入:
flush将整批记录通过Session#insertRecords一次性写入 IoTDB;若某条记录只有字符串类型测点(无类型列表),则走stringValues重载(L124-L140)。 - checkpoint 联动:
IoTDBSinkWriter.prepareCommit会在快照状态前强制flush,保证 checkpoint 时刻的数据已落库(IoTDBSinkWriter.java),这也解释了「缓冲行数达到batch_size或 checkpoint 完成时刷新缓冲」的行为。 - 重试退避:写入失败时按
retry_backoff_multiplier_ms * i计算退避时间,并以max_retry_backoff_ms为上限(Math.min(multiplier * i, maxBackoff)),最多重试max_retries次,超出后抛出FLUSH_DATA_FAILED异常(L150-L162)。注意退避时间随重试次数线性增长,而非指数增长。
变更日志
IoTDB 连接器(含 Sink)的演进历史记录在 connector-iotdb 变更日志 中。值得关注的节点包括:2.2.0-beta 首次支持 IoTDB Sink;2.3.0 起暴露可配置选项(expose configurable options in IoTDB)并统一了连接器异常处理;2.3.4 移除了 Sink 内部调度器(Remove scheduler in IoTDB sink),改为纯批量刷写模型;2.3.10 重构了连接器公共选项;2.3.11 增加了 Sink 状态类 serialVersionUID 的检查脚本,保障 checkpoint 状态的可序列化兼容性。升级 SeaTunnel 版本时,可据此了解行为变化。
总结
SeaTunnel 的 IoTDB Sink 连接器提供了从批处理/流处理管道向 IoTDB 落库的完整能力:通过 key_device、key_timestamp、key_measurement_fields 三个字段灵活控制设备路径、写入时间与测点集合,借助 batch_size 与 checkpoint 联动实现高效批量写入,并通过幂等写天然获得精确一次语义。配置时需重点关注必传的四项参数、connection_timeout_in_ms 对 enable_rpc_compression 的依赖,以及 key_timestamp 字段仅支持 STRING/BIGINT/TIMESTAMP 三种类型等约束。文中四个案例覆盖了从最小配置到流式高吞吐写入的典型场景,可直接迁移到实际作业。