This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] 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 c6a240c466 [Docs] Fix connector doc inaccuracies verified against
source code (#12615)
c6a240c466 is described below
commit c6a240c4666e750cd88d8e1d59cb5cc2b2134db3
Author: Jast <[email protected]>
AuthorDate: Sun Oct 25 14:33:48 2026 +0000
[Docs] Fix connector doc inaccuracies verified against source code (#12615)
Co-authored-by: jast <[email protected]>
---
docs/en/connectors/sink/FtpFile.md | 22 ++--------------------
docs/en/connectors/source/FtpFile.md | 31 ++++++-------------------------
docs/en/connectors/source/Hive.md | 14 +++++++-------
docs/en/transforms/dynamic-compile.md | 8 ++++----
docs/zh/connectors/sink/FtpFile.md | 22 ++--------------------
docs/zh/connectors/source/FtpFile.md | 31 ++++++-------------------------
docs/zh/connectors/source/Hive.md | 14 +++++++-------
docs/zh/transforms/dynamic-compile.md | 8 ++++----
8 files changed, 38 insertions(+), 112 deletions(-)
diff --git a/docs/en/connectors/sink/FtpFile.md
b/docs/en/connectors/sink/FtpFile.md
index f257992bf8..b0bc827ea4 100644
--- a/docs/en/connectors/sink/FtpFile.md
+++ b/docs/en/connectors/sink/FtpFile.md
@@ -410,27 +410,9 @@ FtpFile {
```
-### Writing via SFTP
+### Writing to an SFTP server
-The `FtpFile` sink supports `sftp://` URIs alongside `ftp://`. Authentication
and host-key trust are configured the same way as for the source — SSH key or
password plus a `known_hosts` file (the connector does not auto-trust unknown
hosts).
-
-```hocon
-sink {
- FtpFile {
- fs.defaultFS = "sftp://sftp.example.example.com:22";
- path = "/upload/landing/"
- user = "seatunnel"
- file_format_type = "parquet"
- ftp_properties = {
- "fs.sftp.user." = "seatunnel"
- "fs.sftp.keyfile" = "/etc/seatunnel/id_rsa"
- "fs.sftp.host" = "sftp.example.example.com"
- "fs.sftp.port" = "22"
- "fs.sftp.knownHosts" = "/etc/seatunnel/known_hosts"
- }
- }
-}
-```
+The `FtpFile` sink only speaks the plain FTP protocol — its connection is
always built as `ftp://<host>:<port>` from the `host`/`port` options, and
options such as `fs.defaultFS`, `ftp_properties`, or `known_hosts` are not
supported. To write files over SFTP (SSH File Transfer), use the
[SftpFile](SftpFile.md) sink instead.
## Changelog
diff --git a/docs/en/connectors/source/FtpFile.md
b/docs/en/connectors/source/FtpFile.md
index 49bbe38f39..ccc056e7cc 100644
--- a/docs/en/connectors/source/FtpFile.md
+++ b/docs/en/connectors/source/FtpFile.md
@@ -680,8 +680,10 @@ Source plugin common parameters, please refer to [Source
Common Options](../comm
password = tianchao
file_format_type = "text"
schema = {
- name = string
- age = int
+ fields {
+ name = string
+ age = int
+ }
}
field_delimiter = "#"
}
@@ -906,30 +908,9 @@ sink {
}
```
-### Reading via SFTP (SSH File Transfer)
-
-`FtpFile` reads from FTP and SFTP servers through the same Hadoop FileSystem
URI scheme; switch to `sftp://` to use SSH instead of plain FTP. SFTP requires
an SSH key (or a password) for authentication, and the host key must be trusted
by the running JVM (either via `~/.ssh/known_hosts` or a custom `known_hosts`
file passed through `ftp_properties`).
-
-```hocon
-source {
- FtpFile {
- fs.defaultFS = "sftp://sftp.example.example.com:22";
- path = "/upload/landing/"
- user = "seatunnel"
- file_format_type = "csv"
- delimiter = ","
- ftp_properties = {
- "fs.sftp.user." = "seatunnel"
- "fs.sftp.keyfile" = "/etc/seatunnel/id_rsa"
- "fs.sftp.host" = "sftp.example.example.com"
- "fs.sftp.port" = "22"
- "fs.sftp.knownHosts" = "/etc/seatunnel/known_hosts"
- }
- }
-}
-```
+### Reading from an SFTP server
-If the SFTP server uses a self-signed host key, add it to `known_hosts` ahead
of time — otherwise the first read throws a `SftpException` complaining about
host verification. The connector does not cache or refresh `known_hosts`
itself; updating the file and restarting the job is enough.
+The `FtpFile` connector only speaks the plain FTP protocol — its connection is
always built as `ftp://<host>:<port>` from the `host`/`port` options, and
options such as `fs.defaultFS`, `ftp_properties`, or `known_hosts` are not
supported. To read files over SFTP (SSH File Transfer), use the
[SftpFile](SftpFile.md) connector instead, which configures the server through
`host`/`port`/`user`/`password` (and optional SSH `keyfile`) options.
## Changelog
diff --git a/docs/en/connectors/source/Hive.md
b/docs/en/connectors/source/Hive.md
index f004b77b2f..9cd8fb2baa 100644
--- a/docs/en/connectors/source/Hive.md
+++ b/docs/en/connectors/source/Hive.md
@@ -42,8 +42,8 @@ Read all the data in a split in a pollNext call. What splits
are read will be sa
| name | type | required | default value | description |
|-----------------------|--------|----------|----------------|-------------|
| table_name | string | no | Required for single-table mode |
Target Hive table name in the form `db1.table1`. When `use_regex = true`, this
field uses `databasePattern.tablePattern` to match multiple tables. |
-| table_list | array | no | Deprecated, use `tables_configs`
instead | Deprecated multi-table configuration list. New jobs should use
`tables_configs`. Kept for backward compatibility; will be removed in a future
release. |
-| tables_configs | array | no | - | List of Hive
table configurations for multi-table reading. Each item can override any of the
root-level options. |
+| table_list | array | no | - | Multi-table
configuration list. Each item can override any of the root-level options. Takes
precedence if both `table_list` and `tables_configs` are set. |
+| tables_configs | array | no | Deprecated, use `table_list`
instead | Deprecated multi-table configuration list. Hive is a structured data
source, new jobs should use `table_list`. Kept for backward compatibility. |
| use_regex | boolean| no | false | Treat
`table_name` as a regular expression that matches multiple tables. Works at the
root level and inside each `table_list` / `tables_configs` entry. |
| metastore_uri | string | no | Required for single-table mode |
Hive metastore URI. Comma-separated values enable HA failover; whitespace is
ignored. |
| krb5_path | string | no | /etc/krb5.conf | Path of the
`krb5.conf` file used for Kerberos authentication. |
@@ -63,15 +63,15 @@ Read all the data in a split in a pollNext call. What
splits are read will be sa
Target Hive table name eg: `db1.table1`. When `use_regex = true`, this field
uses `databasePattern.tablePattern` (Hive has no schema) to match multiple
tables from Hive metastore.
-For a single-table source, configure `table_name` and `metastore_uri` at the
root level. For multi-table reading, configure `tables_configs`. `table_list`
is still accepted for backward compatibility, but `tables_configs` is the
current option.
+For a single-table source, configure `table_name` and `metastore_uri` at the
root level. For multi-table reading, configure `table_list`. `tables_configs`
is still accepted for backward compatibility, but `table_list` is the current
option.
### table_list [array]
-Deprecated multi-table configuration list. Kept for backward compatibility;
new jobs should use `tables_configs`.
+Multi-table configuration list. Each item can contain `table_name`,
`metastore_uri`, `use_regex`, `read_partitions`, `read_columns`, and the same
authentication/Hadoop options as the root connector block.
### tables_configs [array]
-List of Hive table configurations for multi-table reading. Each item can
contain `table_name`, `metastore_uri`, `use_regex`, `read_partitions`,
`read_columns`, and the same authentication/Hadoop options as the root
connector block.
+Deprecated multi-table configuration list, kept for backward compatibility;
new jobs should use `table_list`. Each item can contain `table_name`,
`metastore_uri`, `use_regex`, `read_partitions`, `read_columns`, and the same
authentication/Hadoop options as the root connector block.
### use_regex [boolean]
@@ -163,13 +163,13 @@ Source plugin common parameters, please refer to [Source
Common Options](../comm
```
### Example 3: Multiple tables
-> Note: Hive is a structured data source and should use 'tables_configs'; the
older 'table_list' key is deprecated and will be removed in a future release.
+> Note: Hive is a structured data source and `table_list` is the recommended
multi-table option; the older `tables_configs` key is deprecated but still
accepted for backward compatibility.
> You can also set `use_regex = true` in each table config to match multiple
> tables.
```hocon
Hive {
- tables_configs = [
+ table_list = [
{
table_name = "default.seatunnel_orc_1"
metastore_uri = "thrift://namenode001:9083"
diff --git a/docs/en/transforms/dynamic-compile.md
b/docs/en/transforms/dynamic-compile.md
index bddeee430f..72547259f2 100644
--- a/docs/en/transforms/dynamic-compile.md
+++ b/docs/en/transforms/dynamic-compile.md
@@ -81,7 +81,7 @@ Use this DynamicCompile to add a new column
`compile_language`, and update the `
- use groovy
-```hacon
+```hocon
transform {
DynamicCompile {
plugin_input = "fake"
@@ -139,7 +139,7 @@ transform {
```
- use java
-```hacon
+```hocon
transform {
DynamicCompile {
plugin_input = "fake"
@@ -194,7 +194,7 @@ transform {
}
```
- use absolute path to read code
-```hacon
+```hocon
transform {
DynamicCompile {
plugin_input = "fake"
@@ -226,7 +226,7 @@ Then the data in result table `java_out` will like this
| Joy Dom | 30 | 123 | JAVA |
- use scala
-```hacon
+```hocon
transform {
DynamicCompile {
plugin_input = "fake"
diff --git a/docs/zh/connectors/sink/FtpFile.md
b/docs/zh/connectors/sink/FtpFile.md
index 14a5da01c6..ceeb8af3b1 100644
--- a/docs/zh/connectors/sink/FtpFile.md
+++ b/docs/zh/connectors/sink/FtpFile.md
@@ -414,27 +414,9 @@ FtpFile {
```
-### 通过 SFTP 写入
+### 写入 SFTP 服务器
-`FtpFile` Sink 同时支持 `ftp://` 和 `sftp://` URI。认证方式与 source 一致：SSH 密钥或密码外加
`known_hosts` 文件——连接器不会自动信任未知 host。
-
-```hocon
-sink {
- FtpFile {
- fs.defaultFS = "sftp://sftp.example.example.com:22";
- path = "/upload/landing/"
- user = "seatunnel"
- file_format_type = "parquet"
- ftp_properties = {
- "fs.sftp.user." = "seatunnel"
- "fs.sftp.keyfile" = "/etc/seatunnel/id_rsa"
- "fs.sftp.host" = "sftp.example.example.com"
- "fs.sftp.port" = "22"
- "fs.sftp.knownHosts" = "/etc/seatunnel/known_hosts"
- }
- }
-}
-```
+`FtpFile` Sink 仅支持标准 FTP 协议——连接始终由 `host`/`port` 选项拼接为
`ftp://<host>:<port>`，不支持 `fs.defaultFS`、`ftp_properties`、`known_hosts`
等选项。如需通过 SFTP（SSH 文件传输协议）写入文件，请改用 [SftpFile](SftpFile.md) Sink。
## 变更日志
diff --git a/docs/zh/connectors/source/FtpFile.md
b/docs/zh/connectors/source/FtpFile.md
index afa3d0ff89..d15f3cf44c 100644
--- a/docs/zh/connectors/source/FtpFile.md
+++ b/docs/zh/connectors/source/FtpFile.md
@@ -652,8 +652,10 @@ compare_mode = "len_mtime"
password = tianchao
file_format_type = "text"
schema = {
- name = string
- age = int
+ fields {
+ name = string
+ age = int
+ }
}
field_delimiter = "#"
}
@@ -877,30 +879,9 @@ sink {
}
```
-### 通过 SFTP 读取（SSH 文件传输）
-
-`FtpFile` 通过统一的 Hadoop FileSystem URI 同时支持 FTP 和 SFTP；将 URI 协议改为 `sftp://`
即切换到 SSH 通道。SFTP 需要 SSH 密钥（或密码）认证，且 host key 必须被运行中的 JVM 信任（通过
`~/.ssh/known_hosts` 或通过 `ftp_properties` 显式指定的 `known_hosts` 文件）。
-
-```hocon
-source {
- FtpFile {
- fs.defaultFS = "sftp://sftp.example.example.com:22";
- path = "/upload/landing/"
- user = "seatunnel"
- file_format_type = "csv"
- delimiter = ","
- ftp_properties = {
- "fs.sftp.user." = "seatunnel"
- "fs.sftp.keyfile" = "/etc/seatunnel/id_rsa"
- "fs.sftp.host" = "sftp.example.example.com"
- "fs.sftp.port" = "22"
- "fs.sftp.knownHosts" = "/etc/seatunnel/known_hosts"
- }
- }
-}
-```
+### 从 SFTP 服务器读取
-如果 SFTP 服务器使用的是自签 host key，请提前把它加进 `known_hosts`——否则第一次读取会抛出 `SftpException`
并提示 host 校验未通过。连接器本身不缓存或刷新 `known_hosts`，更新文件后重启作业即可生效。
+`FtpFile` 连接器仅支持标准 FTP 协议——连接始终由 `host`/`port` 选项拼接为 `ftp://<host>:<port>`，不支持
`fs.defaultFS`、`ftp_properties`、`known_hosts` 等选项。如需通过 SFTP（SSH 文件传输协议）读取文件，请改用
[SftpFile](SftpFile.md) 连接器，它通过 `host`/`port`/`user`/`password`（以及可选的 SSH
`keyfile`）选项配置服务器。
## 变更日志
diff --git a/docs/zh/connectors/source/Hive.md
b/docs/zh/connectors/source/Hive.md
index a1d825691a..1cd61c0ab9 100644
--- a/docs/zh/connectors/source/Hive.md
+++ b/docs/zh/connectors/source/Hive.md
@@ -36,8 +36,8 @@ import ChangeLog from '../changelog/connector-hive.md';
| 名称 | 类型 | 必需 | 默认值 | 描述 |
|-----------------------|--------|------|---------|------|
| table_name | string | 否 | 单表模式必填 | 目标 Hive 表名，格式为
`db1.table1`。当 `use_regex = true` 时，该字段使用 `数据库正则.表正则` 匹配多张表。 |
-| table_list | array | 否 | - | 已废弃的多表配置列表。新作业请使用
`tables_configs`。仅为向后兼容保留，未来版本将移除。 |
-| tables_configs | array | 否 | - | 多表读取时使用的 Hive
表配置列表，每项可覆盖根配置中的任意选项。 |
+| table_list | array | 否 | - | 多表读取时使用的 Hive
表配置列表，每项可覆盖根配置中的任意选项。若两者同时设置，`table_list` 优先。 |
+| tables_configs | array | 否 | 已废弃，请使用 `table_list` |
已废弃的多表配置列表。Hive 是结构化数据源，新作业请使用 `table_list`。仅为向后兼容保留。 |
| use_regex | boolean| 否 | false | 将 `table_name`
视为正则表达式以匹配多张表。在根级别以及 `table_list` / `tables_configs` 的每一项中均可使用。 |
| metastore_uri | string | 否 | 单表模式必填 | Hive metastore
URI。多个以逗号分隔的值可启用 HA 故障转移，空白字符会被忽略。 |
| krb5_path | string | 否 | /etc/krb5.conf | Kerberos 认证使用的
`krb5.conf` 文件路径。 |
@@ -57,15 +57,15 @@ import ChangeLog from '../changelog/connector-hive.md';
目标 Hive 表名，例如：`db1.table1`。当 `use_regex = true` 时，该字段支持 `数据库正则.表正则`（Hive 没有
schema）来匹配 Hive 元存储中的多张表。
-单表读取时，在根配置中填写 `table_name` 和 `metastore_uri`。多表读取时，建议使用
`tables_configs`。`table_list` 仍可作为向后兼容的旧配置，但新作业建议使用 `tables_configs`。
+单表读取时，在根配置中填写 `table_name` 和 `metastore_uri`。多表读取时，请配置
`table_list`。`tables_configs` 仍可向后兼容使用，但 `table_list` 是当前选项。
### table_list [array]
-已废弃的多表读取配置列表，仅为向后兼容保留。新作业请使用 `tables_configs`。
+多表读取配置列表。每个元素可以包含
`table_name`、`metastore_uri`、`use_regex`、`read_partitions`、`read_columns`，以及与根配置相同的认证和
Hadoop 配置。
### tables_configs [array]
-Hive 多表读取配置列表。每个元素可以包含
`table_name`、`metastore_uri`、`use_regex`、`read_partitions`、`read_columns`，以及与根配置相同的认证和
Hadoop 配置。
+已废弃的多表配置列表，仅为向后兼容保留；新作业请使用 `table_list`。每个元素可以包含
`table_name`、`metastore_uri`、`use_regex`、`read_partitions`、`read_columns`，以及与根配置相同的认证和
Hadoop 配置。
### use_regex [boolean]
@@ -155,12 +155,12 @@ Kerberos 认证的 keytab 文件路径
```
### 示例 3：多表
-> 注意：Hive 是结构化数据源，应使用 `tables_configs`，`table_list` 已在新的 API 中废弃，并将在未来移除。
+> 注意：Hive 是结构化数据源，多表读取请使用 `table_list`；`tables_configs` 已废弃，目前仍向后兼容可用。
> 也支持在每个表配置中设置 `use_regex = true` 来按正则匹配多表。
```bash
Hive {
- tables_configs = [
+ table_list = [
{
table_name = "default.seatunnel_orc_1"
metastore_uri = "thrift://namenode001:9083"
diff --git a/docs/zh/transforms/dynamic-compile.md
b/docs/zh/transforms/dynamic-compile.md
index 34adc73930..a5fb41a646 100644
--- a/docs/zh/transforms/dynamic-compile.md
+++ b/docs/zh/transforms/dynamic-compile.md
@@ -78,7 +78,7 @@ SOURCE_CODE,ABSOLUTE_PATH
我们将使用`DynamicCompile`对数据进行修改，添加一列`compile_language`字段，并且将`age`字段更新，当`age=20`时将其更新为`40`
- 使用groovy
-```hacon
+```hocon
transform {
DynamicCompile {
plugin_input = "fake"
@@ -136,7 +136,7 @@ transform {
```
- 使用java
-```hacon
+```hocon
transform {
DynamicCompile {
plugin_input = "fake"
@@ -191,7 +191,7 @@ transform {
}
```
- 指定源码文件路径
-```hacon
+```hocon
transform {
DynamicCompile {
plugin_input = "fake"
@@ -226,7 +226,7 @@ transform {
下面的 Scala 示例演示如何新增 `compile_language` 字段。
-```hacon
+```hocon
transform {
DynamicCompile {
plugin_input = "fake"
