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 2e2a8e18dc [Docs][Connector-V2] Clarify connector option requirements
(#11411)
2e2a8e18dc is described below
commit 2e2a8e18dcb782e9572dc9b8d64966940ea11213
Author: Jast <[email protected]>
AuthorDate: Sun Jul 12 17:49:06 2026 +0800
[Docs][Connector-V2] Clarify connector option requirements (#11411)
Co-authored-by: zhangshenghang <[email protected]>
---
docs/en/connectors/sink/Iceberg.md | 6 +++++-
docs/en/connectors/sink/Paimon.md | 2 +-
docs/en/connectors/source/Paimon.md | 12 ++++++------
docs/en/connectors/source/Pulsar.md | 5 +++++
docs/en/connectors/source/Redis.md | 6 +++---
docs/zh/connectors/sink/Iceberg.md | 6 +++++-
docs/zh/connectors/sink/Paimon.md | 2 +-
docs/zh/connectors/source/Paimon.md | 12 ++++++------
docs/zh/connectors/source/Pulsar.md | 5 +++++
docs/zh/connectors/source/Redis.md | 5 ++---
10 files changed, 39 insertions(+), 22 deletions(-)
diff --git a/docs/en/connectors/sink/Iceberg.md
b/docs/en/connectors/sink/Iceberg.md
index 759d3f247c..10ce5bc050 100644
--- a/docs/en/connectors/sink/Iceberg.md
+++ b/docs/en/connectors/sink/Iceberg.md
@@ -79,7 +79,7 @@ libfb303-xxx.jar
| iceberg.table.upsert-mode-enabled | boolean | no | false
| Set to `true` to enable upsert mode, default is `false`
|
| schema_save_mode | Enum | no |
CREATE_SCHEMA_WHEN_NOT_EXIST | the schema save mode, please refer to
`schema_save_mode` below
|
| data_save_mode | Enum | no | APPEND_DATA
| the data save mode, please refer to `data_save_mode` below
|
-| custom_sql | string | no | -
| Custom `delete` data sql for data save mode. e.g: `delete from
... where ...`
|
+| custom_sql | string | Required when
`data_save_mode` is `CUSTOM_PROCESSING` | - | Custom
`delete` SQL for `CUSTOM_PROCESSING` data save mode, for example `delete from
... where ...`.
|
| iceberg.table.commit-branch | string | no | -
| Default branch for commits
|
| multi_table_sink_replica | int | no | -
| Replica number for every table writer in multi-table sink mode.
Use this when one upstream job writes to multiple Iceberg tables and each table
needs more than one sink writer.
|
| krb5_path | string | no | /etc/krb5.conf
| The path of `krb5.conf`, used for Kerberos authentication.
|
@@ -100,6 +100,10 @@ Use a comma-separated list, for example `dt,region` or
Iceberg transforms such a
Write commits to the specified Iceberg branch. Leave it empty to commit to the
table's default branch.
+### custom_sql [string]
+
+When `data_save_mode = CUSTOM_PROCESSING`, configure the `delete` SQL that
removes the target data before the sink writes. This option is required in that
mode.
+
### krb5_path [string]
The path of `krb5.conf`, used for Kerberos authentication.
diff --git a/docs/en/connectors/sink/Paimon.md
b/docs/en/connectors/sink/Paimon.md
index 7147f3660c..ea7aba6b31 100644
--- a/docs/en/connectors/sink/Paimon.md
+++ b/docs/en/connectors/sink/Paimon.md
@@ -67,7 +67,7 @@ libfb303-xxx.jar
| warehouse | String | Yes | -
| Paimon warehouse path
|
| catalog_name | String | No | paimon
| The name of Paimon catalog
|
| catalog_type | String | No | filesystem
| Catalog type of Paimon, support filesystem and hive
|
-| catalog_uri | String | No | -
| Catalog uri of Paimon, only needed when catalog_type is hive
|
+| catalog_uri | String | Yes when `catalog_type` is `hive` |
- | Catalog URI of Paimon. Required when
`catalog_type` is `hive`.
|
| database | String | Yes | -
| The database you want to access
|
| table | String | Yes | -
| The table you want to access
|
| user | String | No | -
| Paimon user to access table
|
diff --git a/docs/en/connectors/source/Paimon.md
b/docs/en/connectors/source/Paimon.md
index 195165741f..5d95b88404 100644
--- a/docs/en/connectors/source/Paimon.md
+++ b/docs/en/connectors/source/Paimon.md
@@ -51,10 +51,10 @@ Read data from Apache Paimon.
| warehouse | String | Yes | - |
| catalog_name | String | No | paimon |
| catalog_type | String | No | filesystem |
-| catalog_uri | String | No | - |
+| catalog_uri | String | Yes when `catalog_type` is `hive` | -
|
| database | String | Yes | - |
-| table | String | no | - |
-| table_list | array | no | - |
+| table | String | Yes when `table_list` is absent | -
|
+| table_list | array | Yes when `table` is absent | -
|
| user | String | No | - |
| password | String | No | - |
| hdfs_site_path | String | No | - |
@@ -72,7 +72,7 @@ Catalog type of Paimon, support filesystem and hive
### catalog_uri [string]
-Catalog uri of Paimon, only needed when catalog_type is hive
+Catalog URI of Paimon. This option is required when `catalog_type` is `hive`.
### database [string]
@@ -80,11 +80,11 @@ The database you want to access
### table [string]
-The table you want to access
+The table you want to access. Configure exactly one of `table` and
`table_list`.
### table_list [array]
-The list of tables to be read. Use this configuration instead of `table` when
one source needs to read multiple Paimon tables. Each item must contain
`table`, and can contain its own `query`.
+The list of tables to read. Configure exactly one of `table` and `table_list`.
Each item must contain `table`, and can contain its own `query`.
### hdfs_site_path [string]
diff --git a/docs/en/connectors/source/Pulsar.md
b/docs/en/connectors/source/Pulsar.md
index 750e4ae44f..90bb263765 100644
--- a/docs/en/connectors/source/Pulsar.md
+++ b/docs/en/connectors/source/Pulsar.md
@@ -42,6 +42,7 @@ Source connector for Apache Pulsar.
| cursor.stop.timestamp | Long | No | - | Stop
timestamp (ms) when `cursor.stop.mode=TIMESTAMP`
|
| schema | Config | No | - | Data
structure including field names and types
|
| format | String | No | json | Data format.
Default is json. Supported formats: json, canal_json and avro. **Multi-table
mode only supports JSON, CANAL_JSON and AVRO** |
+| field_delimiter | String | No | , | Field
delimiter for `text` format.
|
| common-options | | No | - | Source
plugin common parameters. See [Source Common
Options](../common-options/source-common-options.md) for details |
### topic [String]
@@ -164,6 +165,10 @@ reference to
[Schema-Feature](../../introduction/concepts/schema-feature.md)
Data format. The default format is json. Supported formats are json,
canal_json and avro. The `schema` option is required when using avro format.
See [formats](../formats) for more details.
+### field_delimiter [String]
+
+Field delimiter for `text` format. The default value is `,`.
+
### common options
Source plugin common parameters, please refer to [Source Common
Options](../common-options/source-common-options.md) for details.
diff --git a/docs/en/connectors/source/Redis.md
b/docs/en/connectors/source/Redis.md
index 477ceb0a61..77a203d473 100644
--- a/docs/en/connectors/source/Redis.md
+++ b/docs/en/connectors/source/Redis.md
@@ -157,10 +157,10 @@ When set to `true`, both the key and its associated value
are included in the re
By default (`false`), only the value is read and included.
-If you are using a single-value Redis data type (such as `string`, `int`,
etc.) with `read_key_enabled = true`,
-you must also specify `single_field_name` to map the value to a schema column,
and `key_field_name` to map the Redis key.
+If you are using a single-value Redis data type (such as `string`, `list`,
`set`, or `zset`) with `read_key_enabled = true`,
+you must specify `single_field_name` to map the value to a schema column.
`key_field_name` is optional and defaults to `key`.
-Note: When `read_key_enabled = true`, the schema configuration must explicitly
include the key field to correctly map the deserialized data.
+When you configure a schema, include the actual output field names, including
the default `key` field or the name set by `key_field_name`.
Example :
```hocon
diff --git a/docs/zh/connectors/sink/Iceberg.md
b/docs/zh/connectors/sink/Iceberg.md
index 585bba1f7b..e98a0b4ca4 100644
--- a/docs/zh/connectors/sink/Iceberg.md
+++ b/docs/zh/connectors/sink/Iceberg.md
@@ -79,7 +79,7 @@ libfb303-xxx.jar
| iceberg.table.upsert-mode-enabled | boolean | no | false
| 设置为 `true` 以启用 upsert 模式，默认值为 `false`
|
| schema_save_mode | Enum | no |
CREATE_SCHEMA_WHEN_NOT_EXIST | schema 变更方式, 请参考下面的 `schema_save_mode`
|
| data_save_mode | Enum | no | APPEND_DATA
| 数据写入方式, 请参考下面的 `data_save_mode`
|
-| custom_sql | string | no | -
| 自定义 `delete` 数据的 SQL 语句，用于数据写入方式。例如： `delete from ... where ...`
|
+| custom_sql | string | 当 `data_save_mode` 为
`CUSTOM_PROCESSING` 时是 | - | `CUSTOM_PROCESSING`
数据写入方式使用的自定义 `delete` SQL，例如 `delete from ... where ...`。
|
| iceberg.table.commit-branch | string | no | -
| 提交的默认分支
|
| multi_table_sink_replica | int | no | -
| 多表写入模式下每张表对应的 Sink 写入并发数。一个作业写入多张 Iceberg 表，并且每张表都需要多个写入器时使用。
|
| krb5_path | string | no | /etc/krb5.conf
| `krb5.conf` 文件的路径，用于 Kerberos 认证。
|
@@ -100,6 +100,10 @@ libfb303-xxx.jar
将提交写入指定的 Iceberg 分支。不配置时写入表的默认分支。
+### custom_sql [string]
+
+当 `data_save_mode = CUSTOM_PROCESSING` 时，配置在 Sink 写入前删除目标数据的 `delete`
SQL。该模式下必须配置此选项。
+
### krb5_path [string]
`krb5.conf` 文件的路径，用于 Kerberos 认证。
diff --git a/docs/zh/connectors/sink/Paimon.md
b/docs/zh/connectors/sink/Paimon.md
index a46228cb28..bdfc37da79 100644
--- a/docs/zh/connectors/sink/Paimon.md
+++ b/docs/zh/connectors/sink/Paimon.md
@@ -67,7 +67,7 @@ libfb303-xxx.jar
| warehouse | 字符串 | 是 | - |
Paimon warehouse路径
|
| catalog_name | 字符串 | 否 | paimon |
Paimon catalog名称
|
| catalog_type | 字符串 | 否 | filesystem |
Paimon的catalog类型，目前支持filesystem和hive
|
-| catalog_uri | 字符串 | 否 | - |
Paimon catalog的uri，仅当catalog_type为hive时需要配置
|
+| catalog_uri | 字符串 | 当 `catalog_type` 为 `hive` 时是 | -
| Paimon catalog 的 URI。当 `catalog_type` 为 `hive` 时必须配置。
|
| database | 字符串 | 是 | - |
数据库名称
|
| table | 字符串 | 是 | - |
表名
|
| user | 字符串 | 否 | - |
paimon开启权限后，用户名
|
diff --git a/docs/zh/connectors/source/Paimon.md
b/docs/zh/connectors/source/Paimon.md
index 5c0b6fc854..934299aaa5 100644
--- a/docs/zh/connectors/source/Paimon.md
+++ b/docs/zh/connectors/source/Paimon.md
@@ -51,10 +51,10 @@ import ChangeLog from '../changelog/connector-paimon.md';
| warehouse | String | 是 | - |
| catalog_name | String | 否 | paimon |
| catalog_type | String | 否 | filesystem |
-| catalog_uri | String | 否 | - |
+| catalog_uri | String | 当 `catalog_type` 为 `hive` 时是 | -
|
| database | String | 是 | - |
-| table | String | 否 | - |
-| table_list | array | 否 | - |
+| table | String | 未配置 `table_list` 时是 | - |
+| table_list | array | 未配置 `table` 时是 | - |
| user | String | 否 | - |
| password | String | 否 | - |
| hdfs_site_path | String | 否 | - |
@@ -72,7 +72,7 @@ Paimon Catalog 类型，支持 filesystem 和 hive
### catalog_uri [string]
-Paimon 的 catalog uri，仅当 catalog_type 为 hive 时需要
+Paimon 的 catalog URI。当 `catalog_type` 为 `hive` 时必须配置。
### database [string]
@@ -80,11 +80,11 @@ Paimon 的 catalog uri，仅当 catalog_type 为 hive 时需要
### table [string]
-需要访问的表
+需要访问的表。`table` 和 `table_list` 必须二选一配置。
### table_list [array]
-`Paimon` 表名列表。当一个 Source 需要读取多张 Paimon 表时，使用此配置代替 `table`。每个配置项必须包含
`table`，也可以配置该表自己的 `query`。
+`Paimon` 表名列表。当一个 Source 需要读取多张 Paimon 表时，使用此配置代替 `table`。`table` 和
`table_list` 必须二选一配置。每个配置项必须包含 `table`，也可以配置该表自己的 `query`。
### hdfs_site_path [string]
diff --git a/docs/zh/connectors/source/Pulsar.md
b/docs/zh/connectors/source/Pulsar.md
index f905aa562b..055f72a92b 100644
--- a/docs/zh/connectors/source/Pulsar.md
+++ b/docs/zh/connectors/source/Pulsar.md
@@ -42,6 +42,7 @@ Apache Pulsar 的源连接器。
| cursor.stop.timestamp | Long | 否 | - | 当
`cursor.stop.mode=TIMESTAMP` 时的停止时间戳(毫秒)
|
| schema | Config | 否 | - | 数据结构,包括字段名称和字段类型
|
| format | String | 否 | json | 数据格式。默认为 json。支持
json、canal_json 和 avro 格式。**多表模式仅支持 JSON、CANAL_JSON 和 AVRO**
|
+| field_delimiter | String | 否 | , | `text` 格式使用的字段分隔符。
|
| common-options | | 否 | - | Source 插件通用参数,请参考
[Source Common Options](../common-options/source-common-options.md) 了解详情
|
### topic [String]
@@ -157,6 +158,10 @@ Pulsar 消费者的启动模式，有效值为 `'EARLIEST'`、`'LATEST'`、`'SUB
数据格式。默认值为 `json`。支持 json、canal_json 和 avro 格式。使用 avro 格式时需要配置
`schema`。更多格式说明参考 [formats](../formats)。
+### field_delimiter [String]
+
+`text` 格式使用的字段分隔符。默认值为 `,`。
+
### 通用参数
Source 插件通用参数请参考 [Source Common
Options](../common-options/source-common-options.md)。
diff --git a/docs/zh/connectors/source/Redis.md
b/docs/zh/connectors/source/Redis.md
index c0bd14cc19..b930d1c824 100644
--- a/docs/zh/connectors/source/Redis.md
+++ b/docs/zh/connectors/source/Redis.md
@@ -154,10 +154,9 @@ keys 模式
默认值为 `false`，也就是只读取 value。
-如果读取的是 `string`、`list`、`set`、`zset` 这类单值类型，并且开启了 `read_key_enabled`，需要同时配置：
+如果读取的是 `string`、`list`、`set`、`zset` 这类单值类型，并且开启了 `read_key_enabled`，必须配置
`single_field_name`，指定 Redis value 写入哪一列。`key_field_name` 是可选项，默认字段名为 `key`。
-- `key_field_name`：Redis key 写入哪一列。
-- `single_field_name`：Redis value 写入哪一列。
+配置 schema 时，需要包含实际输出的字段名，包括默认的 `key` 字段或 `key_field_name` 指定的字段名。
示例：
