This is an automated email from the ASF dual-hosted git repository.
zhangshenghang 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 9e8c7447f4 [Docs] Document gaps surfaced by support-bot uncertainty
analytics (#11748)
9e8c7447f4 is described below
commit 9e8c7447f4901579ff7a6531d28306e3f3236e6c
Author: David Zollo <[email protected]>
AuthorDate: Tue Aug 11 20:44:38 2026 +0800
[Docs] Document gaps surfaced by support-bot uncertainty analytics (#11748)
Co-authored-by: Claude Sonnet 5 <[email protected]>
---
docs/en/connectors/formats/avro.md | 6 ++++++
docs/en/connectors/formats/debezium-json.md | 8 ++++++++
docs/en/connectors/source/Jdbc.md | 12 ++++++++++++
docs/en/engines/zeta/rest-api-job-lifecycle.md | 9 +++++++++
docs/en/engines/zeta/rest-api-v2.md | 7 +++++++
docs/en/engines/zeta/telemetry.md | 4 ++++
docs/en/introduction/configuration/JobEnvConfig.md | 2 ++
docs/zh/connectors/formats/avro.md | 6 ++++++
docs/zh/connectors/formats/debezium-json.md | 8 ++++++++
docs/zh/connectors/source/Jdbc.md | 12 ++++++++++++
docs/zh/engines/zeta/rest-api-job-lifecycle.md | 8 ++++++++
docs/zh/engines/zeta/rest-api-v2.md | 9 ++++++++-
docs/zh/engines/zeta/telemetry.md | 4 ++++
docs/zh/introduction/configuration/JobEnvConfig.md | 2 ++
14 files changed, 96 insertions(+), 1 deletion(-)
diff --git a/docs/en/connectors/formats/avro.md
b/docs/en/connectors/formats/avro.md
index 62cb19b95d..f8222a1e21 100644
--- a/docs/en/connectors/formats/avro.md
+++ b/docs/en/connectors/formats/avro.md
@@ -2,6 +2,12 @@
Avro is very popular in streaming data pipeline. Now seatunnel supports Avro
format in kafka connector.
+:::note Confluent Schema Registry is not supported
+
+This format decodes plain Avro binary directly using the `schema` you
configure; it does not talk to a schema registry. Messages produced by a
Confluent Schema Registry-aware serializer carry a 5-byte wire-format header (a
magic byte followed by a 4-byte schema ID) before the Avro payload, and this
format does not strip that header, so registry-produced messages cannot be read
as-is. To consume Confluent-style Avro from Kafka, either write a custom
deserialization schema that strips the [...]
+
+:::
+
# How To Use
## Kafka uses example
diff --git a/docs/en/connectors/formats/debezium-json.md
b/docs/en/connectors/formats/debezium-json.md
index e296d2404e..4618ac3d80 100644
--- a/docs/en/connectors/formats/debezium-json.md
+++ b/docs/en/connectors/formats/debezium-json.md
@@ -112,3 +112,11 @@ sink {
}
```
+# See Also
+
+SeaTunnel supports several other CDC changelog formats with the same
INSERT/UPDATE/DELETE interpretation:
+
+- [Canal JSON](canal-json.md)
+- [Maxwell JSON](maxwell-json.md)
+- [OGG JSON](ogg-json.md)
+
diff --git a/docs/en/connectors/source/Jdbc.md
b/docs/en/connectors/source/Jdbc.md
index 6c4335f510..326134aac9 100644
--- a/docs/en/connectors/source/Jdbc.md
+++ b/docs/en/connectors/source/Jdbc.md
@@ -214,6 +214,18 @@ In HOCON strings, a regular-expression backslash must be
escaped, so `\d+` is wr
Many JDBC drivers treat schema and table arguments passed to
`DatabaseMetaData` as SQL `LIKE` patterns. SeaTunnel performs an exact
identifier check after metadata discovery, but you should still use the exact
case for case-sensitive database identifiers.
+:::note Views and table matching
+
+Whether `table_path` (with or without `use_regex`) also matches database
views, not only base tables, depends on the dialect's internal table-listing
query. There is no option to explicitly include or exclude views:
+
+- MySQL and PostgreSQL list views alongside base tables, so a broad pattern
like `db.*` also matches views.
+- SQL Server filters to `TABLE_TYPE = 'BASE TABLE'` and excludes views.
+- Oracle and Dameng query `ALL_TABLES`, which excludes views as a side effect
of that view not listing them.
+
+To read only specific base tables regardless of dialect, list them explicitly
in `table_list` instead of relying on a broad regular expression.
+
+:::
+
### decimal_type_narrowing
Decimal type narrowing, if true, the decimal type will be narrowed to the int
or long type if without loss of precision. Only support for Oracle at now.
diff --git a/docs/en/engines/zeta/rest-api-job-lifecycle.md
b/docs/en/engines/zeta/rest-api-job-lifecycle.md
index c3312eee5e..915b9764b6 100644
--- a/docs/en/engines/zeta/rest-api-job-lifecycle.md
+++ b/docs/en/engines/zeta/rest-api-job-lifecycle.md
@@ -264,6 +264,15 @@ curl -X POST
"http://<master>:8080/submit-job?restoreMode=CHECKPOINT&restoreSour
}'
```
+The same `restoreMode` and `restoreSourceJobId` query parameters work with the
+[upload endpoint](rest-api-v2.md#submit-a-job-by-upload-config-file) when
submitting a config file
+instead of a JSON body -- both endpoints share the same restore handling:
+
+```bash
+curl --location
'http://<master>:8080/submit-job/upload?restoreMode=CHECKPOINT&restoreSourceJobId=733584788375093248'
\
+ --form 'config_file=@"/temp/my-cdc-job.conf"'
+```
+
If the checkpoint data for `restoreSourceJobId` is missing, already cleaned
up, or incompatible,
the submission fails fast.
diff --git a/docs/en/engines/zeta/rest-api-v2.md
b/docs/en/engines/zeta/rest-api-v2.md
index c0caceaf52..2b0bab3245 100644
--- a/docs/en/engines/zeta/rest-api-v2.md
+++ b/docs/en/engines/zeta/rest-api-v2.md
@@ -773,6 +773,8 @@ When we can't get the job info, the response will be:
> | jobId | optional | string | job id
> |
> | jobName | optional | string | job name
> |
> | isStartWithSavePoint | optional | string | if job is started with save
> point |
+> | restoreMode | optional | string | Restore source for job
recovery: `CHECKPOINT` or `SAVEPOINT`. Used together with `restoreSourceJobId`.
See [Job Recovery and
Restart](rest-api-job-lifecycle.md#6-job-recovery-and-restart). |
+> | restoreSourceJobId | optional | string | The job id to restore from
when `restoreMode` is set. When only `isStartWithSavePoint` is set (no
`restoreMode`), this falls back to `jobId`. |
> | format | optional | string | config format, support json,
> hocon and sql, default json |
**Note:** The dry-run feature is intentionally not supported via the REST API.
It is exclusively available through the SeaTunnel CLI.
@@ -907,6 +909,8 @@ INSERT INTO console_sink SELECT * FROM fake_source;
> | jobId | optional | string | job id
> |
> | jobName | optional | string | job name
> |
> | isStartWithSavePoint | optional | string | if job is started with save
> point |
+> | restoreMode | optional | string | Restore source for job
recovery: `CHECKPOINT` or `SAVEPOINT`. Used together with `restoreSourceJobId`.
See [Job Recovery and
Restart](rest-api-job-lifecycle.md#6-job-recovery-and-restart). |
+> | restoreSourceJobId | optional | string | The job id to restore from
when `restoreMode` is set. When only `isStartWithSavePoint` is set (no
`restoreMode`), this falls back to `jobId`. |
#### Request Body
The name of the uploaded file key is config_file, and supports the following
formats:
@@ -921,6 +925,9 @@ curl --location 'http://127.0.0.1:8080/submit-job/upload'
--form 'config_file=@"
# Upload SQL config file
curl --location 'http://127.0.0.1:8080/submit-job/upload' --form
'config_file=@"/temp/job.sql"'
+
+# Upload a config file and restore from the latest checkpoint of a previous job
+curl --location
'http://127.0.0.1:8080/submit-job/upload?restoreMode=CHECKPOINT&restoreSourceJobId=733584788375666689'
--form 'config_file=@"/temp/fake_to_console.conf"'
```
#### Responses
diff --git a/docs/en/engines/zeta/telemetry.md
b/docs/en/engines/zeta/telemetry.md
index 1ccdf0ff16..e8f8af28cf 100644
--- a/docs/en/engines/zeta/telemetry.md
+++ b/docs/en/engines/zeta/telemetry.md
@@ -135,6 +135,8 @@
engine_state_store_connector_jar_total_references{backend="hazelcast"}
### Thread Pool Status
+These metrics are exported by the active master only; scraping a worker node's
endpoint will not return them.
+
| MetricName | Type | Labels
| DESCRIPTION
|
|-------------------------------------|---------|--------------------------------------------------------------------|--------------------------------------------------------------------------------|
| job_thread_pool_activeCount | Gauge | **address**, server instance
address,for example: "127.0.0.1:5801" | The activeCount of seatunnel
coordinator job's executor cached thread pool |
@@ -182,6 +184,8 @@ The `result` label has the following meanings:
### Job info detail
+This metric is exported by the active master only. It reports only an
aggregate count per status and has no per-job label, so it cannot be used to
alert on a specific job by ID or name -- only on cluster-wide totals such as
`job_count{type="failed"}`.
+
| MetricName | Type | Labels
|
DESCRIPTION |
|------------|-------|-----------------------------------------------------------------------------------------------------------------------------|-------------------------------------|
| job_count | Gauge | **type**, the type of job, including: "canceled"
"cancelling" "created" "failed" "failing" "finished" "running" "scheduled" |
All job counts of seatunnel cluster |
diff --git a/docs/en/introduction/configuration/JobEnvConfig.md
b/docs/en/introduction/configuration/JobEnvConfig.md
index 40a23cad86..af0767c793 100644
--- a/docs/en/introduction/configuration/JobEnvConfig.md
+++ b/docs/en/introduction/configuration/JobEnvConfig.md
@@ -45,6 +45,8 @@ For more details, you can refer to the documentation [Config
Encryption Decrypti
Used to control the default retry times when a job fails. The default value is
3, and it only works in the Zeta engine.
+This counter accumulates for the life of the pipeline; an intermediate
successful recovery does not reset it. For example, with `job.retry.times = 5`:
if the pipeline fails, retries, and recovers on attempt #3, then later fails
again, only 2 retries remain (attempts #4 and #5) before the job is marked
permanently failed — the budget does not refresh back to 5. The one exception
is an active-master failover in a Zeta cluster, which rebuilds the pipeline
execution plan (and its retry count [...]
+
### job.retry.interval.seconds
Used to control the default retry interval when a job fails. The default value
is 3 seconds, and it only works in the Zeta engine.
diff --git a/docs/zh/connectors/formats/avro.md
b/docs/zh/connectors/formats/avro.md
index 826fc27b44..dc3cf512f5 100644
--- a/docs/zh/connectors/formats/avro.md
+++ b/docs/zh/connectors/formats/avro.md
@@ -2,6 +2,12 @@
Avro 在流式数据处理管道中非常流行。现在seatunnel在kafka连接器中支持Avro格式
+:::note 不支持 Confluent Schema Registry
+
+该格式直接使用你配置的 `schema` 解码原始 Avro 二进制数据，不会与 schema registry 交互。经过 Confluent
Schema Registry 序列化的消息，会在 Avro 数据前带有 5 字节的线上格式头（1 字节 magic byte + 4 字节 schema
ID），该格式不会剥离这部分头信息，因此无法直接读取 registry 生成的消息。如果需要消费 Confluent 风格的 Avro
数据，可以自行实现一个在解码前剥离头信息的反序列化 schema，或者改用不添加 registry 头的生产者写入普通 Avro 数据。Protobuf
格式提供了类似的 [`strip_schema_registry_header`](../source/Kafka.md) 选项；Avro
目前还没有对应的选项。
+
+:::
+
# 怎样用
## Kafka 使用示例
diff --git a/docs/zh/connectors/formats/debezium-json.md
b/docs/zh/connectors/formats/debezium-json.md
index 88b3254039..ab638d2563 100644
--- a/docs/zh/connectors/formats/debezium-json.md
+++ b/docs/zh/connectors/formats/debezium-json.md
@@ -113,3 +113,11 @@ sink {
}
```
+# 参考
+
+SeaTunnel 还支持以下几种 CDC 变更日志格式，它们同样会被解释为 INSERT/UPDATE/DELETE 消息：
+
+- [Canal JSON](canal-json.md)
+- [Maxwell JSON](maxwell-json.md)
+- [OGG JSON](ogg-json.md)
+
diff --git a/docs/zh/connectors/source/Jdbc.md
b/docs/zh/connectors/source/Jdbc.md
index 621858b971..0e41c8fb64 100644
--- a/docs/zh/connectors/source/Jdbc.md
+++ b/docs/zh/connectors/source/Jdbc.md
@@ -214,6 +214,18 @@ HOCON 字符串中的正则反斜杠需要转义，因此正则中的 `\d+` 在
许多 JDBC 驱动会把传给 `DatabaseMetaData` 的 schema 和表名参数当作 SQL `LIKE` 模式。SeaTunnel
会在发现元数据后再次精确核对标识符；对于大小写敏感的数据库，仍应确保配置与数据库中的真实标识符大小写完全一致。
+:::note 视图与表匹配
+
+`table_path`（无论是否启用
`use_regex`）是否会连带匹配到数据库视图（而不仅仅是基础表），取决于各方言内部列举表所使用的查询方式，目前没有可以显式包含或排除视图的配置项：
+
+- MySQL 和 PostgreSQL 会把视图和基础表列在一起，因此像 `db.*` 这样宽泛的匹配模式也会匹配到视图。
+- SQL Server 通过 `TABLE_TYPE = 'BASE TABLE'` 过滤，会排除视图。
+- Oracle 和 Dameng 查询的是 `ALL_TABLES`，视图不在其中，因此会被间接排除。
+
+如果需要在任意方言下都只读取指定的基础表，建议直接在 `table_list` 中显式列出表名，而不要依赖宽泛的正则表达式。
+
+:::
+
### decimal_type_narrowing
十进制类型缩小，如果为 true，十进制类型将缩小为 int 或 long 类型（如果没有精度损失）。目前仅支持 Oracle。
diff --git a/docs/zh/engines/zeta/rest-api-job-lifecycle.md
b/docs/zh/engines/zeta/rest-api-job-lifecycle.md
index b77b0299ae..29e872be4e 100644
--- a/docs/zh/engines/zeta/rest-api-job-lifecycle.md
+++ b/docs/zh/engines/zeta/rest-api-job-lifecycle.md
@@ -262,6 +262,14 @@ curl -X POST
"http://<master>:8080/submit-job?restoreMode=CHECKPOINT&restoreSour
}'
```
+同样的 `restoreMode` 和 `restoreSourceJobId`
查询参数也适用于[上传配置文件的接口](rest-api-v2.md#提交作业来源上传配置文件)——
+如果提交的是配置文件而不是 JSON 请求体，两个接口共享同一套恢复处理逻辑：
+
+```bash
+curl --location
'http://<master>:8080/submit-job/upload?restoreMode=CHECKPOINT&restoreSourceJobId=733584788375093248'
\
+ --form 'config_file=@"/temp/my-cdc-job.conf"'
+```
+
如果 `restoreSourceJobId` 对应的 Checkpoint 数据不存在、已被清理或不兼容，提交会直接失败。
如果希望已取消(Canceled)作业仍可从 Checkpoint 恢复，需要通过以下两种方式之一保留作业执行时的Checkpoint 数据。
diff --git a/docs/zh/engines/zeta/rest-api-v2.md
b/docs/zh/engines/zeta/rest-api-v2.md
index 24c9e6a0aa..56438798a1 100644
--- a/docs/zh/engines/zeta/rest-api-v2.md
+++ b/docs/zh/engines/zeta/rest-api-v2.md
@@ -750,6 +750,8 @@ seatunnel:
> | jobId | optional | string | job id
> |
> | jobName | optional | string | job name
> |
> | isStartWithSavePoint | optional | string | if job is started with save
> point |
+> | restoreMode | optional | string | 作业恢复的数据来源：`CHECKPOINT` 或
`SAVEPOINT`，需与 `restoreSourceJobId` 搭配使用。详见
[作业恢复与重启](rest-api-job-lifecycle.md#6-作业恢复与重启)。 |
+> | restoreSourceJobId | optional | string | 设置了 `restoreMode` 时，用于指定需要恢复的作业
ID。若只设置了 `isStartWithSavePoint`（未设置 `restoreMode`），则回退使用 `jobId`。 |
> | format | optional | string | 配置风格,支持json、hocon 和 sql,默认
> json |
**注意:** REST API 不支持 dry-run 功能。该功能仅通过 CLI 提供。
@@ -875,7 +877,7 @@ INSERT INTO console_sink SELECT * FROM fake_source;
### 提交作业来源上传配置文件
<details>
-<summary><code>POST</code> <code><b>/submit-job</b></code>
<code>(如果作业提交成功，返回jobId和jobName。)</code></summary>
+<summary><code>POST</code> <code><b>/submit-job/upload</b></code>
<code>(如果作业提交成功，返回jobId和jobName。)</code></summary>
#### 参数
@@ -884,6 +886,8 @@ INSERT INTO console_sink SELECT * FROM fake_source;
> | jobId | optional | string | job id
> |
> | jobName | optional | string | job name
> |
> | isStartWithSavePoint | optional | string | if job is started with save
> point |
+> | restoreMode | optional | string | 作业恢复的数据来源：`CHECKPOINT` 或
`SAVEPOINT`，需与 `restoreSourceJobId` 搭配使用。详见
[作业恢复与重启](rest-api-job-lifecycle.md#6-作业恢复与重启)。 |
+> | restoreSourceJobId | optional | string | 设置了 `restoreMode` 时，用于指定需要恢复的作业
ID。若只设置了 `isStartWithSavePoint`（未设置 `restoreMode`），则回退使用 `jobId`。 |
#### 请求体
上传文件key的名称是config_file，支持以下格式：
@@ -899,6 +903,9 @@ curl --location 'http://127.0.0.1:8080/submit-job/upload'
--form 'config_file=@"
# 上传 SQL 配置文件
curl --location 'http://127.0.0.1:8080/submit-job/upload' --form
'config_file=@"/temp/job.sql"'
+
+# 上传配置文件，并从上一个作业最新的 checkpoint 恢复
+curl --location
'http://127.0.0.1:8080/submit-job/upload?restoreMode=CHECKPOINT&restoreSourceJobId=733584788375666689'
--form 'config_file=@"/temp/fake_to_console.conf"'
```
#### 响应
diff --git a/docs/zh/engines/zeta/telemetry.md
b/docs/zh/engines/zeta/telemetry.md
index 44802d2b7c..af9f83a02f 100644
--- a/docs/zh/engines/zeta/telemetry.md
+++ b/docs/zh/engines/zeta/telemetry.md
@@ -134,6 +134,8 @@
engine_state_store_connector_jar_total_references{backend="hazelcast"}
### 线程池状态
+以下指标仅由 active master 输出；采集 worker 节点的接口不会返回这些指标。
+
| MetricName | Type | Labels
| 描述 |
|-------------------------------------|---------|-----------------------------------------|--------------------------------|
| job_thread_pool_activeCount | Gauge |
**address**，服务器实例地址，例如："127.0.0.1:5801" | seatunnel 协调器作业执行器缓存线程池的活动线程数 |
@@ -176,6 +178,8 @@ worker 发送 `RequestSlotOperation` 请求以预留 slot。这些指标用于
### 作业信息详细
+该指标仅由 active master 输出，且只能按状态统计聚合数量，不带按作业区分的标签，因此无法用于针对某个具体作业（按 ID
或名称）的告警，只能用于类似 `job_count{type="failed"}` 这种集群级别的总量告警。
+
| MetricName | Type | Labels
| 描述 |
|------------|-------|---------------------------------------------------------------------------------------------------------|---------------------|
| job_count | Gauge | **type**，作业的类型，包括："canceled" "cancelling" "created"
"failed" "failing" "finished" "running" "scheduled" | seatunnel 集群的所有作业计数 |
diff --git a/docs/zh/introduction/configuration/JobEnvConfig.md
b/docs/zh/introduction/configuration/JobEnvConfig.md
index a90c15dd8b..adfe815ea4 100644
--- a/docs/zh/introduction/configuration/JobEnvConfig.md
+++ b/docs/zh/introduction/configuration/JobEnvConfig.md
@@ -45,6 +45,8 @@
用于控制作业失败时的默认重试次数。默认值为3，并且仅适用于Zeta引擎。
+该计数器会在整个 pipeline 生命周期内持续累加，中途一次成功恢复并不会将其重置。例如设置 `job.retry.times = 5` 时：如果
pipeline 失败后经过重试，在第 3 次尝试时恢复成功，之后又再次失败，此时只剩下 2 次重试机会（第 4、5
次尝试），用完后作业会被标记为永久失败，重试额度不会恢复到 5 次。唯一的例外是 Zeta 集群发生 active master 切换时，pipeline
执行计划（以及其重试计数器）会被重新构建。
+
### job.retry.interval.seconds
用于控制作业失败时的默认重试间隔。默认值为3秒，并且仅适用于Zeta引擎。
