SeaTunnel IoTDB Sink 连接器实战指南:配置、数据类型映射与写入原理

原创2026-09-18 13:41:051,836 阅读
文章标签:数据集成ETL大数据数据同步变更数据捕获流处理批处理

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 便于逐行验证写入结果,可作为真实作业配置的参照。

底层写入与重试机制

理解底层写入链路有助于调优参数。整体流程如下:

  1. 序列化:IoTDBSinkWriter.write 将每条 SeaTunnelRow 交给 DefaultSeaTunnelRowSerializer,转换为 IoTDBRecord(设备、时间戳、测点名、测点类型与值),见 IoTDBSinkWriter.java。
  2. 缓冲:IoTDBSinkClient.write 将记录加入内存 batchList,当行数达到 batch_size 时触发 flush,见 IoTDBSinkClient.java。
  3. 批量写入:flush 将整批记录通过 Session#insertRecords 一次性写入 IoTDB;若某条记录只有字符串类型测点(无类型列表),则走 stringValues 重载(L124-L140)。
  4. checkpoint 联动:IoTDBSinkWriter.prepareCommit 会在快照状态前强制 flush,保证 checkpoint 时刻的数据已落库(IoTDBSinkWriter.java),这也解释了「缓冲行数达到 batch_size 或 checkpoint 完成时刷新缓冲」的行为。
  5. 重试退避:写入失败时按 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 三种类型等约束。文中四个案例覆盖了从最小配置到流式高吞吐写入的典型场景,可直接迁移到实际作业。

登录后查看全文
seatunnel