This is an automated email from the ASF dual-hosted git repository.
davidzollo pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/seatunnel.git
The following commit(s) were added to refs/heads/dev by this push:
new 0a1d49eff4 [Docs][Connector-V2] Improve IoTDBv2 connector docs (#11368)
0a1d49eff4 is described below
commit 0a1d49eff4af7fb9a65a62050e2285a3821bfd90
Author: Daniel Carter <[email protected]>
AuthorDate: Tue Jul 7 17:50:56 2026 +0800
[Docs][Connector-V2] Improve IoTDBv2 connector docs (#11368)
---
docs/en/connectors/sink/IoTDBv2.md | 42 ++++++++++++++++++----------------
docs/en/connectors/source/IoTDBv2.md | 29 ++++++++++++------------
docs/zh/connectors/sink/IoTDBv2.md | 44 ++++++++++++++++++++----------------
docs/zh/connectors/source/IoTDBv2.md | 22 +++++++++---------
4 files changed, 72 insertions(+), 65 deletions(-)
diff --git a/docs/en/connectors/sink/IoTDBv2.md
b/docs/en/connectors/sink/IoTDBv2.md
index 7eab0a025c..9f4ecc595b 100644
--- a/docs/en/connectors/sink/IoTDBv2.md
+++ b/docs/en/connectors/sink/IoTDBv2.md
@@ -1,8 +1,8 @@
import ChangeLog from '../changelog/connector-iotdb.md';
-# IoTDB
+# IoTDBv2
-> IoTDB sink connector
+> IoTDBv2 sink connector
## Support Those Engines
@@ -12,7 +12,7 @@ import ChangeLog from '../changelog/connector-iotdb.md';
## Description
-Used to write data to IoTDB.
+Used to write data to IoTDB 2.x. The connector name in job configuration is
`IoTDBv2`.
## Key Features
@@ -49,23 +49,27 @@ Used to write data to IoTDB.
| node_urls | Array | Yes | - |
IoTDB cluster address, the format is `["host1:port"]` or
`["host1:port","host2:port"]`
|
| username | String | Yes | - |
IoTDB username
|
| password | String | Yes | - |
IoTDB user password
|
-| sql_dialect | String | No | tree |
the sql dialect of IoTDB, options available is `"tree"` or `"table"`
|
-| storage_group | String | Yes | - |
IoTDB-tree: Specify the device storage group(path prefix) <br/> example:
deviceId = \${storage_group} + "." + \${key_device} <br/> IoTDB-table: Specify
the database
|
+| sql_dialect | String | No | tree |
The SQL dialect of IoTDB. Available values are `"tree"` and `"table"`.
|
+| storage_group | String | Yes | - |
IoTDB tree model: device path prefix. For example, the device path is
`storage_group + "." + key_device`. Set it to an empty string when `key_device`
already contains the full device path. <br/> IoTDB table model: database name.
|
| key_device | String | Yes | - |
IoTDB-tree: Specify the field name in SeaTunnelRow to be used as device id
<br/> IoTDB-table: Specify the field name in SeaTunnelRow to be used as table
name
|
| key_timestamp | String | No | processing time |
IoTDB-tree: Specify the field name in SeaTunnelRow to be used as timestamp
(processing time will be used by default) <br/> IoTDB-table: Specify the field
name in SeaTunnelRow to be used as time column (processing time will be used by
default)
|
| key_measurement_fields | Array | No | refer to description |
IoTDB-tree: Specify the field names in SeaTunnelRow to be used as measurement
(all fields excluding `key_device`&`key_timestamp` will be used by default)
<br/> IoTDB-table: Specify the field names in SeaTunnelRow to be used as FIELD
columns (all fields excluding `key_device`, `key_timestamp`, `key_tag_fields`
and `key_attribute_fields` will be used by default) |
| key_tag_fields | Array | No | - |
IoTDB-tree: invalid <br/> IoTDB-table: Specify the field names in SeaTunnelRow
to be used as TAG columns
|
| key_attribute_fields | Array | No | - |
IoTDB-tree: invalid <br/> IoTDB-table: Specify the field names in SeaTunnelRow
to be used as ATTRIBUTE columns
|
-| batch_size | Integer | No | 1024 | In
batch writing, the data will be flushed into the IoTDB either when the number
of buffers reaches the number of `batch_size` or the time reaches
`batch_interval_ms`
|
-| max_retries | Integer | No | - |
The number of times retrying to flush
|
-| retry_backoff_multiplier_ms | Integer | No | - |
Used as a multiplier for generating the next delay for backoff
|
-| max_retry_backoff_ms | Integer | No | - |
The amount of time to wait before attempting to retry a request to IoTDB
|
+| batch_size | Integer | No | 1024 |
The connector flushes buffered records to IoTDB when the number of buffered
records reaches `batch_size`. It also flushes before checkpoint commit and when
the writer is closed.
|
+| max_retries | Integer | No | 0 |
The maximum number of retries when flushing records fails.
|
+| retry_backoff_multiplier_ms | Integer | No | 0 |
The multiplier used to calculate the retry backoff delay.
|
+| max_retry_backoff_ms | Integer | No | 0 |
The maximum retry backoff delay in milliseconds.
|
| default_thrift_buffer_size | Integer | No | - |
Thrift init buffer size in IoTDB client
|
| max_thrift_frame_size | Integer | No | - |
Thrift max frame size in IoTDB client
|
| zone_id | String | No | - |
java.time.ZoneId in IoTDB client
|
| enable_rpc_compression | Boolean | No | - |
Enable rpc compression in IoTDB client, only valid in IoTDB-tree
|
| connection_timeout_in_ms | Integer | No | - |
The maximum time (in ms) to wait when connecting to IoTDB
|
-| common-options | | no | - |
Sink plugin common parameters, please refer to [Sink Common
Options](../common-options/sink-common-options.md) for details
|
+| common-options | | no | - |
Sink plugin common parameters, please refer to [Sink Common
Options](../common-options/sink-common-options.md) for details
|
+
+For the tree model, `key_device` is used as the IoTDB device path, and
`key_measurement_fields` controls which fields become measurements. If
`key_measurement_fields` is not set, all fields except `key_device` and
`key_timestamp` are written as measurements.
+
+For the table model, `storage_group` is the database, `key_device` is the
target table name field, `key_tag_fields` are TAG columns,
`key_attribute_fields` are ATTRIBUTE columns, and `key_measurement_fields` are
FIELD columns. If `key_measurement_fields` is not set, all fields except the
table name, time, TAG, and ATTRIBUTE fields are written as FIELD columns.
## Examples
@@ -117,8 +121,8 @@ Only required options used:
```hocon
sink {
- IoTDB {
- node_urls = "localhost:6667"
+ IoTDBv2 {
+ node_urls = ["localhost:6667"]
username = "root"
password = "root"
key_device = "device_name" # specify the `deviceId` use device_name field
@@ -147,8 +151,8 @@ Use source event's time:
```hocon
sink {
- IoTDB {
- node_urls = "localhost:6667"
+ IoTDBv2 {
+ node_urls = ["localhost:6667"]
username = "root"
password = "root"
key_device = "device_name" # specify the `deviceId` use device_name field
@@ -178,8 +182,8 @@ Use source event's time and limit measurement fields:
```hocon
sink {
- IoTDB {
- node_urls = "localhost:6667"
+ IoTDBv2 {
+ node_urls = ["localhost:6667"]
username = "root"
password = "root"
key_device = "device_name"
@@ -244,7 +248,7 @@ Only required options used:
```hocon
sink {
- IoTDB {
+ IoTDBv2 {
node_urls = ["localhost:6667"]
username = "root"
password = "root"
@@ -291,7 +295,7 @@ Use source event's time and limit TAG and ATTRIBUTE columns:
```hocon
sink {
- IoTDB {
+ IoTDBv2 {
node_urls = ["localhost:6667"]
username = "root"
password = "root"
@@ -339,7 +343,7 @@ Use source event's time and limit FIELD columns:
```hocon
sink {
- IoTDB {
+ IoTDBv2 {
node_urls = ["localhost:6667"]
username = "root"
password = "root"
diff --git a/docs/en/connectors/source/IoTDBv2.md
b/docs/en/connectors/source/IoTDBv2.md
index 08da5dd8f5..2ae17edc1c 100644
--- a/docs/en/connectors/source/IoTDBv2.md
+++ b/docs/en/connectors/source/IoTDBv2.md
@@ -1,8 +1,8 @@
import ChangeLog from '../changelog/connector-iotdb.md';
-# IoTDB
+# IoTDBv2
-> IoTDB source connector
+> IoTDBv2 source connector
## Support Those Engines
@@ -12,7 +12,7 @@ import ChangeLog from '../changelog/connector-iotdb.md';
## Description
-Used to read data from IoTDB.
+Used to read data from IoTDB 2.x. The connector name in job configuration is
`IoTDBv2`.
## Key features
@@ -55,20 +55,20 @@ Used to read data from IoTDB.
| node_urls | Array | Yes | - | IoTDB
cluster address, the format is `["host1:port"]` or
`["host1:port","host2:port"]` |
| username | String | Yes | - | IoTDB
username
|
| password | String | Yes | - | IoTDB user
password
|
-| sql_dialect | String | No | tree | The sql
dialect of IoTDB, options available is `"tree"` or `"table"`
|
-| database | String | No | - | The
database selected (only valid when `sql_dielct` is `"table"`)
|
+| sql_dialect | String | No | tree | The SQL
dialect of IoTDB. Available values are `"tree"` and `"table"`.
|
+| database | String | No | - | The
selected database. This option is only valid when `sql_dialect` is `"table"`.
|
| sql | String | Yes | - | The sql
statement to be executed
|
| schema | Config | Yes | - | The data
schema. For more details, please refer to [Schema
Feature](../../introduction/concepts/schema-feature.md).
|
-| fetch_size | Integer | No | - | The
fetch_size of the IoTDB when you select
|
-| lower_bound | Long | No | - | The
lower_bound of the IoTDB when you select
|
-| upper_bound | Long | No | - | The
upper_bound of the IoTDB when you select
|
-| num_partitions | Integer | No | - | The
num_partitions of the IoTDB when you select
|
-| default_thrift_buffer_size | Integer | No | - | The
thrift_default_buffer_size of the IoTDB when you select
|
+| fetch_size | Integer | No | - | The number
of rows fetched from IoTDB in one request.
|
+| lower_bound | Long | No | - | The lower
bound of the time range used for source partition splitting.
|
+| upper_bound | Long | No | - | The upper
bound of the time range used for source partition splitting.
|
+| num_partitions | Integer | No | - | The number
of partitions used to split the time range.
|
+| default_thrift_buffer_size | Integer | No | - | The
default Thrift buffer size used by the IoTDB client.
|
| max_thrift_frame_size | Integer | No | - | The thrift
max frame size
|
-| enable_cache_leader | Boolean | No | - |
Enable_cache_leader of the IoTDB when you select
|
+| enable_cache_leader | Boolean | No | - | Whether to
enable leader cache in the IoTDB client.
|
| common-options | | no | - | Source
plugin common parameters, please refer to [Source Common
Options](../common-options/source-common-options.md) for details |
-We can use time column as a partition key in SQL queries.
+You can use the time column to split a source query into multiple partitions.
To enable this, set `lower_bound`, `upper_bound`, and `num_partitions` together.
#### num_partitions [int]
@@ -106,7 +106,7 @@ env {
}
source {
- IoTDB {
+ IoTDBv2 {
node_urls = ["localhost:6667"]
username = "root"
password = "root"
@@ -164,7 +164,7 @@ env {
}
source {
- IoTDB {
+ IoTDBv2 {
node_urls = ["localhost:6667"]
username = "root"
password = "root"
@@ -219,4 +219,3 @@ The data format loaded to SeaTunnelRow is as follows:
## Changelog
<ChangeLog />
-
diff --git a/docs/zh/connectors/sink/IoTDBv2.md
b/docs/zh/connectors/sink/IoTDBv2.md
index 4f28ad1139..c529c20550 100644
--- a/docs/zh/connectors/sink/IoTDBv2.md
+++ b/docs/zh/connectors/sink/IoTDBv2.md
@@ -1,8 +1,8 @@
import ChangeLog from '../changelog/connector-iotdb.md';
-# IoTDB
+# IoTDBv2
-> IoTDB 数据接收器
+> IoTDBv2 数据接收器
## 支持引擎
@@ -12,14 +12,14 @@ import ChangeLog from '../changelog/connector-iotdb.md';
## 描述
-用于将数据写入 IoTDB。
+用于将数据写入 IoTDB 2.x。作业配置中的连接器名称为 `IoTDBv2`。
## 主要特性
- [x] [精确一次](../../introduction/concepts/connector-v2-features.md)
> IoTDB 通过幂等写支持`精确一次`功能。如果两条数据使用相同的`key`和`timestamp`，新数据将覆盖旧数据。
-- [ ] [timer flush](../../introduction/concepts/connector-v2-features.md)
+- [ ] [定时刷新](../../introduction/concepts/connector-v2-features.md)
## 支持的数据源信息
@@ -49,23 +49,27 @@ import ChangeLog from '../changelog/connector-iotdb.md';
| node_urls | Array | 是 | - | IoTDB 集群地址，格式为
`["host1:port"]` 或 `["host1:port","host2:port"]`
|
| username | String | 是 | - | IoTDB 用户名
|
| password | String | 是 | - | IoTDB 用户密码
|
-| sql_dialect | String | 否 | tree | IoTDB
模型，tree：树模型；table：表模型
|
-| storage_group | String | 是 | - | IoTDB
树模型：指定设备存储组（路径前缀） <br/> 例如: deviceId = \${storage_group} + "." +
\${key_device} <br/> IoTDB 表模型：指定数据库
|
+| sql_dialect | String | 否 | tree | IoTDB 模型，可选值为 `tree`
和 `table`。`tree` 表示树模型，`table` 表示表模型。
|
+| storage_group | String | 是 | - | IoTDB
树模型：指定设备路径前缀。例如设备路径为 `storage_group + "." + key_device`。如果 `key_device`
已经是完整设备路径，可以设置为空字符串。<br/> IoTDB 表模型：指定数据库。
|
| key_device | String | 是 | - | IoTDB 树模型：在
SeaTunnelRow 中指定 IoTDB 设备 ID 的字段名；<br/> IoTDB 表模型：在 SeaTunnelRow 中指定 IoTDB
表名的字段名
|
| key_timestamp | String | 否 | 数据处理时间 | IoTDB 树模型：在
SeaTunnelRow 中指定 IoTDB 时间戳的字段名（如未指定，则使用处理时间作为时间戳）；<br/> IoTDB 表模型：在
SeaTunnelRow 中指定 IoTDB 时间列的字段名（如未指定，则使用处理时间作为时间戳）
|
| key_measurement_fields | Array | 否 | 见描述 | IoTDB 树模型：在
SeaTunnelRow 中指定 IoTDB
测量列表的字段名（如未指定，则包括排除`key_device`&`key_timestamp`后的其余字段）；<br/> IoTDB 表模型：在
SeaTunnelRow 中指定 IoTDB
测点列（FIELD）的字段名（如未指定，则包括排除`key_device`&`key_timestamp`&`key_tag_fields`&`key_attribute_fields`后的其余字段）
|
| key_tag_fields | Array | 否 | - | IoTDB 树模型：不生效；<br/>
IoTDB 表模型：在 SeaTunnelRow 中指定 IoTDB 标签列（TAG）的字段名
|
| key_attribute_fields | Array | 否 | - | IoTDB 树模型：不生效；<br/>
IoTDB 表模型：在 SeaTunnelRow 中指定 IoTDB 属性列（ATTRIBUTE）的字段名
|
-| batch_size | Integer | 否 | 1024 |
对于批写入，当缓冲区的数量达到`batch_size`的数量或时间达到`batch_interval_ms`时，数据将被刷新到 IoTDB 中
|
-| max_retries | Integer | 否 | - | 刷新的重试次数
|
-| retry_backoff_multiplier_ms | Integer | 否 | - | 用作生成下一个退避延迟的乘数
|
-| max_retry_backoff_ms | Integer | 否 | - | 尝试重试对 IoTDB
的请求之前等待的时间量
|
-| default_thrift_buffer_size | Integer | 否 | - | 在 IoTDB
客户端中节省初始化缓冲区大小
|
-| max_thrift_frame_size | Integer | 否 | - | 在 IoTDB 客户端中节约最大帧大小
|
-| zone_id | String | 否 | - | IoTDB
java.time.ZoneId client
|
+| batch_size | Integer | 否 | 1024 | 缓存的记录数达到
`batch_size` 时，连接器会把数据刷新到 IoTDB；在 checkpoint 提交前和写入器关闭时也会刷新。
|
+| max_retries | Integer | 否 | 0 | 刷新失败时的最大重试次数。
|
+| retry_backoff_multiplier_ms | Integer | 否 | 0 | 计算重试等待时间的退避倍数，单位为毫秒。
|
+| max_retry_backoff_ms | Integer | 否 | 0 | 最大重试等待时间，单位为毫秒。
|
+| 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
common Options](../common-options/sink-common-options.md)
|
+| common-options | | 否 | - | Sink 插件常用参数，详见 [Sink
常用选项](../common-options/sink-common-options.md)
|
+
+树模型下，`key_device` 用作 IoTDB 设备路径，`key_measurement_fields` 决定哪些字段写成测点。未配置
`key_measurement_fields` 时，除 `key_device` 和 `key_timestamp` 之外的所有字段都会写成测点。
+
+表模型下，`storage_group` 表示数据库，`key_device` 表示目标表名字段，`key_tag_fields` 表示 TAG
列，`key_attribute_fields` 表示 ATTRIBUTE 列，`key_measurement_fields` 表示 FIELD 列。未配置
`key_measurement_fields` 时，除表名、时间、TAG 和 ATTRIBUTE 字段之外的所有字段都会写成 FIELD 列。
## 示例
@@ -118,7 +122,7 @@ source {
```hocon
sink {
- IoTDB {
+ IoTDBv2 {
node_urls = ["localhost:6667"]
username = "root"
password = "root"
@@ -148,7 +152,7 @@ IoTDB> SELECT * FROM root.test_group.* align by device;
```hocon
sink {
- IoTDB {
+ IoTDBv2 {
node_urls = ["localhost:6667"]
username = "root"
password = "root"
@@ -179,7 +183,7 @@ IoTDB> SELECT * FROM root.test_group.* align by device;
```hocon
sink {
- IoTDB {
+ IoTDBv2 {
node_urls = ["localhost:6667"]
username = "root"
password = "root"
@@ -245,7 +249,7 @@ source {
```hocon
sink {
- IoTDB {
+ IoTDBv2 {
node_urls = ["localhost:6667"]
username = "root"
password = "root"
@@ -292,7 +296,7 @@ IoTDB> DESC "test_database"."0700HK";
```hocon
sink {
- IoTDB {
+ IoTDBv2 {
node_urls = ["localhost:6667"]
username = "root"
password = "root"
@@ -340,7 +344,7 @@ IoTDB> DESC "test_database"."0700HK";
```hocon
sink {
- IoTDB {
+ IoTDBv2 {
node_urls = ["localhost:6667"]
username = "root"
password = "root"
diff --git a/docs/zh/connectors/source/IoTDBv2.md
b/docs/zh/connectors/source/IoTDBv2.md
index 36f32ee5e0..9c13bec33b 100644
--- a/docs/zh/connectors/source/IoTDBv2.md
+++ b/docs/zh/connectors/source/IoTDBv2.md
@@ -1,8 +1,8 @@
import ChangeLog from '../changelog/connector-iotdb.md';
-# IoTDB
+# IoTDBv2
-> IoTDB 数据读取器
+> IoTDBv2 数据读取器
## 支持引擎
@@ -12,7 +12,7 @@ import ChangeLog from '../changelog/connector-iotdb.md';
## 描述
-用于从 IoTDB 中读取数据。
+用于从 IoTDB 2.x 中读取数据。作业配置中的连接器名称为 `IoTDBv2`。
## 主要特性
@@ -55,20 +55,20 @@ import ChangeLog from '../changelog/connector-iotdb.md';
| node_urls | Array | 是 | - | IoTDB 集群地址，格式为
`["host1:port"]` 或 `["host1:port","host2:port"]` |
| username | String | 是 | - | IoTDB 用户名
|
| password | String | 是 | - | IoTDB 用户密码
|
-| sql_dialect | String | 否 | tree | IoTDB
模型，tree：树模型；table：表模型 |
+| sql_dialect | String | 否 | tree | IoTDB 模型，可选值为 `tree` 和
`table`。`tree` 表示树模型，`table` 表示表模型。 |
| database | String | 否 | - | 要查询的数据库名，只在表模型中生效
|
| sql | String | 是 | - | 要执行的 SQL 查询语句
|
| schema | Config | 是 | - | 数据模式定义。更多详情请参考 [Schema
特性](../../introduction/concepts/schema-feature.md)。
|
-| fetch_size | Integer | 否 | - | 单次获取数据量：查询时每次从 IoTDB
获取的数据量 |
+| fetch_size | Integer | 否 | - | 单次请求从 IoTDB 获取的行数。
|
| lower_bound | Long | 否 | - | 时间范围下界（通过时间列进行数据分片时使用）
|
| upper_bound | Long | 否 | - | 时间范围上界（通过时间列进行数据分片时使用）
|
| num_partitions | Integer | 否 | - |
分区数量（通过时间列进行数据分片时使用）：<br/> - 1 个分区：使用完整时间范围 <br/> - 若分区数 < (上界
-下界)，则使用差值作为实际分区数 |
-| default_thrift_buffer_size | Integer | 否 | - | Thrift 协议缓冲区大小
|
+| default_thrift_buffer_size | Integer | 否 | - | IoTDB 客户端使用的默认 Thrift
缓冲区大小。 |
| max_thrift_frame_size | Integer | 否 | - | Thrift 最大帧尺寸
|
-| enable_cache_leader | Boolean | 否 | - | 是否启用 Leader 节点缓存
|
-| common-options | | 否 | - | Source 插件常用参数，详见
[Source common Options](../common-options/source-common-options.md) |
+| enable_cache_leader | Boolean | 否 | - | 是否在 IoTDB 客户端启用 Leader
节点缓存。 |
+| common-options | | 否 | - | Source 插件常用参数，详见
[Source 常用选项](../common-options/source-common-options.md) |
-我们可以使用时间列进行分区查询。
+可以使用时间列把一次查询拆成多个分片执行。启用分片读取时，需要同时配置 `lower_bound`、`upper_bound` 和
`num_partitions`。
### num_partitions [int]
@@ -107,7 +107,7 @@ env {
}
source {
- IoTDB {
+ IoTDBv2 {
node_urls = ["localhost:6667"]
username = "root"
password = "root"
@@ -165,7 +165,7 @@ env {
}
source {
- IoTDB {
+ IoTDBv2 {
node_urls = ["localhost:6667"]
username = "root"
password = "root"
