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 9aeb282b2d [Docs] Fix option and config inaccuracies across transform,
Zeta engine and connector docs (#12423)
9aeb282b2d is described below
commit 9aeb282b2d20052db523c5b0cfe54fa8d397ce5e
Author: Jast <[email protected]>
AuthorDate: Sun Oct 25 14:33:43 2026 +0000
[Docs] Fix option and config inaccuracies across transform, Zeta engine and
connector docs (#12423)
Co-authored-by: jast <[email protected]>
Co-authored-by: David Zollo <[email protected]>
Co-authored-by: Claude Sonnet 5.5 <[email protected]>
---
docs/en/connectors/sink/AmazonDynamoDB.md | 2 +-
docs/en/engines/zeta/stain-trace.md | 4 +-
docs/en/engines/zeta/telemetry.md | 13 ++-
docs/en/transforms/embedding.md | 4 +-
docs/en/transforms/filter-rowkind.md | 2 +-
docs/en/transforms/llm.md | 31 +++---
docs/zh/connectors/sink/AmazonDynamoDB.md | 2 +-
docs/zh/connectors/sink/Doris.md | 176 ++++++++++++++++++++++++++++++
docs/zh/engines/zeta/rest-api-v2.md | 7 ++
docs/zh/engines/zeta/stain-trace.md | 4 +-
docs/zh/engines/zeta/telemetry.md | 11 ++
docs/zh/transforms/embedding.md | 2 +
docs/zh/transforms/filter-rowkind.md | 2 +-
docs/zh/transforms/llm.md | 7 +-
14 files changed, 239 insertions(+), 28 deletions(-)
diff --git a/docs/en/connectors/sink/AmazonDynamoDB.md
b/docs/en/connectors/sink/AmazonDynamoDB.md
index 93261bedb5..c4721790f6 100644
--- a/docs/en/connectors/sink/AmazonDynamoDB.md
+++ b/docs/en/connectors/sink/AmazonDynamoDB.md
@@ -32,7 +32,7 @@ The target table must already exist. The connector writes
each row as a DynamoDB
| secret_access_key | string | yes | - | AWS secret access
key. |
| table | string | yes | - | DynamoDB table
name to write to. |
| batch_size | int | no | 25 | Records buffered
for one batch write request. |
-| multi_table_sink_replica | int | no | - | Sink writer
replicas for each table. |
+| multi_table_sink_replica | int | no | 1 | Sink writer
replicas for each table. |
| max_retries | int | no | 10 | Retries for
unprocessed items. Must be at least `0`. |
| retry_base_delay_ms | long | no | 100 | Initial retry
backoff delay in milliseconds. |
| retry_max_delay_ms | long | no | 5000 | Maximum retry
backoff delay in milliseconds. |
diff --git a/docs/en/engines/zeta/stain-trace.md
b/docs/en/engines/zeta/stain-trace.md
index 8474064d7d..91686b9be2 100644
--- a/docs/en/engines/zeta/stain-trace.md
+++ b/docs/en/engines/zeta/stain-trace.md
@@ -69,7 +69,7 @@ Edit `seatunnel.yaml`:
seatunnel:
engine:
stain-trace-enabled: true
- stain-trace-sample-interval: 100000 # Sample 1 out of 100k records
+ stain-trace-sample-rate: 100000 # Sample 1 out of 100k records
stain-trace-file-base-path: /data/seatunnel/traces # Required for local
trace files; no default
```
@@ -119,7 +119,7 @@ open report.html
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| stain-trace-enabled | boolean | false | Master switch to enable tracing |
-| stain-trace-sample-interval | int | 100000 | Sample 1 out of every N records
|
+| stain-trace-sample-rate | int | 100000 | Sample 1 out of every N records.
The legacy name `stain-trace-sample-interval` is still accepted as a
backward-compatible alias |
| stain-trace-max-traces-per-second-per-worker | int | 50 | Max traces per
worker per second |
| stain-trace-max-entries-per-trace | int | 32 | Max stage entries per trace |
| stain-trace-propagate-to-all-splits | boolean | false | Propagate to all
split outputs |
diff --git a/docs/en/engines/zeta/telemetry.md
b/docs/en/engines/zeta/telemetry.md
index 1048758360..a1323de696 100644
--- a/docs/en/engines/zeta/telemetry.md
+++ b/docs/en/engines/zeta/telemetry.md
@@ -21,6 +21,17 @@ seatunnel:
## Metrics
+> [!NOTE]
+> The metrics endpoints are served through the Hazelcast REST API, which is
**disabled by default** in the shipped
+> `config/hazelcast.yaml`. Before scraping, enable it in `hazelcast.yaml` on
every node:
+>
+> ```yaml
+> hazelcast:
+> network:
+> rest-api:
+> enabled: true
+> ```
+
The metric text of prometheus can be obtained from
`http://{instanceHost}:5801/hazelcast/rest/instance/metrics`.
The metric text of openMetrics can be obtained from
`http://{instanceHost}:5801/hazelcast/rest/instance/openmetrics`.
@@ -146,7 +157,7 @@ These metrics are exported by the active master only;
scraping a worker node's e
| job_thread_pool_queueTaskCount | Gauge | **address**, server instance
address,for example: "127.0.0.1:5801" | The queueTaskCount of seatunnel
coordinator job's executor cached thread pool |
| job_thread_pool_completedTask_total | Counter | **address**, server instance
address,for example: "127.0.0.1:5801" | The completedTask of seatunnel
coordinator job's executor cached thread pool |
| job_thread_pool_task_total | Counter | **address**, server instance
address,for example: "127.0.0.1:5801" | The taskCount of seatunnel coordinator
job's executor cached thread pool |
-| job_thread_pool_rejection_total | Counter | **address**, server instance
address,for example: "127.0.0.1:5801" | The rejectionCount of seatunnel
coordinator job's executor cached thread pool |
|
+| job_thread_pool_rejection_total | Counter | **address**, server instance
address,for example: "127.0.0.1:5801" | The rejectionCount of seatunnel
coordinator job's executor cached thread pool |
### Report Metrics Operation
diff --git a/docs/en/transforms/embedding.md b/docs/en/transforms/embedding.md
index 206d78161f..7b2b27b15b 100644
--- a/docs/en/transforms/embedding.md
+++ b/docs/en/transforms/embedding.md
@@ -48,11 +48,13 @@ you can choose `CUSTOM` to implement requests and
retrievals for custom embeddin
### api_key
The API key for authenticating requests to the embedding service. This is
typically provided by the model provider when
-you register for their service.
+you register for their service. For `AMAZON` this is the IAM access key. This
option is required when `model_provider`
+is `AMAZON`, `OPENAI`, `DOUBAO` or `QIANFAN`, and not required for other
providers.
### secret_key
The secret key used for additional authentication. Some providers may require
this for secure API requests.
+This option is required when `model_provider` is `AMAZON` or `QIANFAN`.
### single_vectorized_input_number
diff --git a/docs/en/transforms/filter-rowkind.md
b/docs/en/transforms/filter-rowkind.md
index d372e8a28f..14946b2a1b 100644
--- a/docs/en/transforms/filter-rowkind.md
+++ b/docs/en/transforms/filter-rowkind.md
@@ -23,7 +23,7 @@ The row kinds to include
The row kinds to exclude.
-You can only config one of `include_kinds` and `exclude_kinds`.
+You must configure exactly one of `include_kinds` and `exclude_kinds`;
configuring both is not allowed.
### common options [string]
diff --git a/docs/en/transforms/llm.md b/docs/en/transforms/llm.md
index 8609e54d02..1b7f169092 100644
--- a/docs/en/transforms/llm.md
+++ b/docs/en/transforms/llm.md
@@ -10,21 +10,21 @@ more.
## Options
-| name | type | required | default value |
-|------------------------|--------|----------|---------------|
-| model_provider | enum | yes | |
-| output_data_type | enum | no | String |
+| name | type | required
| default value |
+|----------------------------|--------|---------------------------------------|---------------|
+| model_provider | enum | yes
| |
+| output_data_type | enum | no
| String |
| strict_boolean_output | boolean | no | false |
-| output_column_name | string | no | llm_output |
-| prompt | string | yes | |
-| inference_columns | list | no | |
-| model | string | yes | |
-| api_key | string | yes | |
-| api_path | string | no | |
-| custom_config | map | no | |
-| custom_response_parse | string | no | |
-| custom_request_headers | map | no | |
-| custom_request_body | map | no | |
+| output_column_name | string | no
| llm_output |
+| prompt | string | yes
| |
+| inference_columns | list | no
| |
+| model | string | yes
| |
+| api_key | string | yes | |
+| api_path | string | no
| |
+| custom_config | map | no
| |
+| custom_response_parse | string | no
| |
+| custom_request_headers | map | no
| |
+| custom_request_body | map | no
| |
### model_provider
@@ -32,7 +32,6 @@ The model provider to use. The available options are:
OPENAI, DOUBAO, DEEPSEEK, KIMIAI, MICROSOFT, ZHIPU, CUSTOM
> tips: If you use Microsoft, please make sure api_path cannot be empty
-
### output_data_type
The data type of the output data. The available options are:
@@ -116,6 +115,8 @@ If you use an OpenAI model, please refer to
https://developers.openai.com/api/do
The API key to use for the model provider.
If you use OpenAI model, please refer
https://help.openai.com/en/articles/4936850-how-to-create-and-use-an-api-key
for how to get the API key.
+This option is required when `model_provider` is `OPENAI`, `DOUBAO` or
`MICROSOFT`.
+
This option is not used when `model_provider` is `CUSTOM`; in that case the
request is fully described by `custom_config`.
### api_path
diff --git a/docs/zh/connectors/sink/AmazonDynamoDB.md
b/docs/zh/connectors/sink/AmazonDynamoDB.md
index 8d0fde0d4d..21e32a9c3e 100644
--- a/docs/zh/connectors/sink/AmazonDynamoDB.md
+++ b/docs/zh/connectors/sink/AmazonDynamoDB.md
@@ -32,7 +32,7 @@ Amazon DynamoDB 写入连接器用于将 SeaTunnel 数据行写入 DynamoDB 表
| secret_access_key | string | 是 | - | AWS secret access key。 |
| table | string | 是 | - | 要写入的 DynamoDB 表名。 |
| batch_size | int | 否 | 25 | 一次批量写入请求缓存的记录数。 |
-| multi_table_sink_replica | int | 否 | - | 每张表对应的 Sink Writer 副本数。 |
+| multi_table_sink_replica | int | 否 | 1 | 每张表对应的 Sink Writer 副本数。 |
| max_retries | int | 否 | 10 | 未处理 item 的最大重试次数，必须大于等于 `0`。 |
| retry_base_delay_ms | long | 否 | 100 | 初始重试等待时间，单位毫秒。 |
| retry_max_delay_ms | long | 否 | 5000 | 最大重试等待时间，单位毫秒。 |
diff --git a/docs/zh/connectors/sink/Doris.md b/docs/zh/connectors/sink/Doris.md
index 65fa3fad23..b85c4feddc 100644
--- a/docs/zh/connectors/sink/Doris.md
+++ b/docs/zh/connectors/sink/Doris.md
@@ -478,6 +478,182 @@ sink {
}
```
+### 自定义 SQL 预处理
+
+当 `data_save_mode = "CUSTOM_PROCESSING"` 时，`custom_sql` 中配置的 SQL
会在同步任务读取数据之前在目标
+Doris 集群上执行。这样可以在连接器常规写入路径之外准备、清理或初始化目标表。此后连接器仍通过
+Stream Load 写入数据。
+
+```hocon
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ FakeSource {
+ row.num = 100
+ schema = {
+ fields {
+ F_ID = bigint
+ F_INT = int
+ F_BIGINT = bigint
+ }
+ }
+ }
+}
+
+sink {
+ Doris {
+ fenodes = "doris_e2e:8030"
+ username = root
+ password = ""
+ database = "e2e_sink"
+ table = "doris_e2e_unique_table"
+ data_save_mode = "CUSTOM_PROCESSING"
+ custom_sql = "INSERT INTO e2e_sink.doris_e2e_unique_table (F_ID, F_INT,
F_BIGINT) VALUES (1, 123, 1234567890123);"
+ sink.enable-2pc = true
+ sink.label-prefix = "test_custom_sql"
+ save_mode_create_template = """CREATE TABLE IF NOT EXISTS
`${database}`.`${table}` (${rowtype_fields}) ENGINE=OLAP UNIQUE KEY (`F_ID`)
DISTRIBUTED BY HASH (`F_ID`) PROPERTIES ("replication_allocation" =
"tag.location.default: 1")"""
+ doris.config = {
+ format = "json"
+ read_json_by_line = "true"
+ }
+ }
+}
+```
+
+### CDC 与 Schema 变更
+
+该示例展示 MySQL-CDC 以 `schema-changes.enabled = true` 流式写入 Doris，使上游 MySQL 源的加列、
+类型扩宽等 DDL 变更能同步应用到目标 Doris 表。
+
+```hocon
+env {
+ parallelism = 1
+ job.mode = "STREAMING"
+ checkpoint.interval = 2000
+}
+
+source {
+ MySQL-CDC {
+ server-id = 5652-5657
+ username = "st_user_source"
+ password = "mysqlpw"
+ table-names = ["shop.products"]
+ url = "jdbc:mysql://mysql_cdc_e2e:3306/shop"
+
+ schema-changes.enabled = true
+ }
+}
+
+sink {
+ Doris {
+ fenodes = "doris_cdc_e2e:8030"
+ username = "root"
+ password = ""
+ database = "shop"
+ table = "products"
+ sink.label-prefix = "test-cdc"
+ sink.enable-2pc = true
+ sink.enable-delete = true
+ doris.config {
+ format = "json"
+ read_json_by_line = "true"
+ }
+ }
+}
+```
+
+### 多表
+
+#### 示例 1
+
+```hocon
+env {
+ parallelism = 1
+ job.mode = "STREAMING"
+ checkpoint.interval = 5000
+}
+
+source {
+ Mysql-CDC {
+ url = "jdbc:mysql://127.0.0.1:3306/seatunnel"
+ username = "root"
+ password = "******"
+
+ table-names = ["seatunnel.role","seatunnel.user","galileo.Bucket"]
+ }
+}
+
+transform {
+}
+
+sink {
+ Doris {
+ fenodes = "doris_cdc_e2e:8030"
+ username = root
+ password = ""
+ database = "${database_name}_test"
+ table = "${table_name}_test"
+ sink.label-prefix = "test-cdc"
+ sink.enable-2pc = "true"
+ sink.enable-delete = "true"
+ doris.config {
+ format = "json"
+ read_json_by_line = "true"
+ }
+ }
+}
+```
+
+#### 示例 2
+
+```hocon
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ Jdbc {
+ driver = oracle.jdbc.driver.OracleDriver
+ url = "jdbc:oracle:thin:@localhost:1521/XE"
+ user = testUser
+ password = testPassword
+
+ table_list = [
+ {
+ table_path = "TESTSCHEMA.TABLE_1"
+ },
+ {
+ table_path = "TESTSCHEMA.TABLE_2"
+ }
+ ]
+ }
+}
+
+transform {
+}
+
+sink {
+ Doris {
+ fenodes = "doris_cdc_e2e:8030"
+ username = root
+ password = ""
+ database = "${schema_name}_test"
+ table = "${table_name}_test"
+ sink.label-prefix = "test-cdc"
+ sink.enable-2pc = "true"
+ sink.enable-delete = "true"
+ doris.config {
+ format = "json"
+ read_json_by_line = "true"
+ }
+ }
+}
+```
+
## 常见问题
### Doris Sink 支持自动建表吗？
diff --git a/docs/zh/engines/zeta/rest-api-v2.md
b/docs/zh/engines/zeta/rest-api-v2.md
index d4f8406e61..404db94d8d 100644
--- a/docs/zh/engines/zeta/rest-api-v2.md
+++ b/docs/zh/engines/zeta/rest-api-v2.md
@@ -1851,6 +1851,13 @@ Checkpoint 信息字段：
</details>
+#### 字段说明
+
+| 字段 | 说明 |
+| --- | --- |
+| `pipelineId` | 该记录所属的 pipeline ID。 |
+| `checkpoint` | 上文所述的 Checkpoint 元数据。 |
+
------------------------------------------------------------------------------------------
### 获取作业实时可观测性指标（内存时序，realtime）
diff --git a/docs/zh/engines/zeta/stain-trace.md
b/docs/zh/engines/zeta/stain-trace.md
index fd1b607d14..8e940fda0f 100644
--- a/docs/zh/engines/zeta/stain-trace.md
+++ b/docs/zh/engines/zeta/stain-trace.md
@@ -69,7 +69,7 @@ StainTrace 是 SeaTunnel 的数据血缘与端到端性能追踪系统，用于
seatunnel:
engine:
stain-trace-enabled: true
- stain-trace-sample-interval: 100000 # 每 10 万条采样 1 条
+ stain-trace-sample-rate: 100000 # 每 10 万条采样 1 条
stain-trace-file-base-path: /data/seatunnel/traces # 本地追踪文件目录，必须显式配置，默认不启用
```
@@ -117,7 +117,7 @@ open report.html
| 参数 | 类型 | 默认值 | 说明 |
|-----|------|--------|------|
| stain-trace-enabled | boolean | false | 启用追踪的主开关 |
-| stain-trace-sample-interval | int | 100000 | 每 N 条记录采样 1 条 |
+| stain-trace-sample-rate | int | 100000 | 每 N 条记录采样 1 条。旧名称
`stain-trace-sample-interval` 仍作为兼容别名被接受 |
| stain-trace-max-traces-per-second-per-worker | int | 50 | 每个 Worker 每秒最大追踪数 |
| stain-trace-max-entries-per-trace | int | 32 | 每条追踪最大阶段条目数 |
| stain-trace-propagate-to-all-splits | boolean | false | 是否传播到所有分裂输出 |
diff --git a/docs/zh/engines/zeta/telemetry.md
b/docs/zh/engines/zeta/telemetry.md
index 25a56b430a..e27b2afa91 100644
--- a/docs/zh/engines/zeta/telemetry.md
+++ b/docs/zh/engines/zeta/telemetry.md
@@ -22,6 +22,17 @@ seatunnel:
## 指标
+> [!NOTE]
+> 指标接口通过 Hazelcast REST API 提供，而发行包中 `config/hazelcast.yaml` 默认**关闭**了 REST
API。
+> 抓取指标前，需要在每个节点的 `hazelcast.yaml` 中启用它：
+>
+> ```yaml
+> hazelcast:
+> network:
+> rest-api:
+> enabled: true
+> ```
+
Prometheus 的指标文本可通过
`http://{instanceHost}:5801/hazelcast/rest/instance/metrics` 获取。
OpenMetrics 的指标文本可通过
`http://{instanceHost}:5801/hazelcast/rest/instance/openmetrics` 获取。
diff --git a/docs/zh/transforms/embedding.md b/docs/zh/transforms/embedding.md
index 5e7cd95e18..c0cd0d6991 100644
--- a/docs/zh/transforms/embedding.md
+++ b/docs/zh/transforms/embedding.md
@@ -46,10 +46,12 @@ Embedding 转换插件利用 embedding 模型将文本和多模态数据转换
### api_key
用于验证 embedding 服务请求的API密钥。通常由模型提供商在你注册他们的服务时提供，对于使用`AMAZON` 模型则对应IAM access
key。
+当 `model_provider` 为 `AMAZON`、`OPENAI`、`DOUBAO` 或 `QIANFAN` 时该选项必填，其他提供商无需配置。
### secret_key
用于额外验证的密钥。一些提供商可能要求此密钥以确保API请求的安全性。
+当 `model_provider` 为 `AMAZON` 或 `QIANFAN` 时该选项必填。
### single_vectorized_input_number
diff --git a/docs/zh/transforms/filter-rowkind.md
b/docs/zh/transforms/filter-rowkind.md
index bea844a544..47ef0ded08 100644
--- a/docs/zh/transforms/filter-rowkind.md
+++ b/docs/zh/transforms/filter-rowkind.md
@@ -23,7 +23,7 @@ FilterRowKind 转换插件用于按 RowKind 过滤数据。
要排除的行类型。
-您只能配置 `include_kinds` 和 `exclude_kinds` 中的一个。
+您必须且只能配置 `include_kinds` 和 `exclude_kinds` 中的一个，不能同时配置。
### common options [string]
diff --git a/docs/zh/transforms/llm.md b/docs/zh/transforms/llm.md
index b342a83f08..7853d72eff 100644
--- a/docs/zh/transforms/llm.md
+++ b/docs/zh/transforms/llm.md
@@ -8,7 +8,7 @@ LLM 转换插件利用大型语言模型（LLM）的能力处理数据，将输
## 属性
-| 名称 | 类型 | 是否必须 | 默认值 |
+| 名称 | 类型 | 是否必须 | 默认值 |
|------------------------| ------ | -------- |-------------|
| model_provider | enum | yes | |
| output_data_type | enum | no | String |
@@ -17,7 +17,7 @@ LLM 转换插件利用大型语言模型（LLM）的能力处理数据，将输
| prompt | string | yes | |
| inference_columns | list | no | |
| model | string | yes | |
-| api_key | string | yes | |
+| api_key | string | yes | |
| api_path | string | no | |
| custom_config | map | no | |
| custom_response_parse | string | no | |
@@ -30,7 +30,6 @@ LLM 转换插件利用大型语言模型（LLM）的能力处理数据，将输
OPENAI,DOUBAO,DEEPSEEK,KIMIAI,MICROSOFT, ZHIPU, CUSTOM
> tips: 如果使用 Microsoft, 请确保 api_path 配置不能为空
-
### output_data_type
输出数据的数据类型。可用选项为:
@@ -111,6 +110,8 @@ transform {
用于模型提供者的 API 密钥。
如果使用 OpenAI 模型，请参考
https://help.openai.com/en/articles/4936850-how-to-create-and-use-an-api-key
文档了解如何获取 API 密钥。
+当 `model_provider` 为 `OPENAI`、`DOUBAO` 或 `MICROSOFT` 时该选项必填。
+
当 `model_provider` 为 `CUSTOM` 时，不会使用此选项，此时请求完全由 `custom_config` 描述。
### api_path
