zhangshenghang opened a new pull request, #12932:
URL: https://github.com/apache/seatunnel/pull/12932
### Purpose of this pull request
Yes — this is a contribution to Apache SeaTunnel. This PR fixes
documentation that contradicts the source code in areas not covered by the
other open docs PRs: the Zeta REST API references, Zeta operations/deployment
pages, several transform pages, the FAQ and the schema-feature concept page.
Every change was verified against the implementation (option definitions, REST
servlets/services, CLI argument parser, YAML config parser and shipped config
templates); file/line references are given below so reviewers can re-check
quickly.
**Documentation issues found and fixed**
*Zeta REST API — `rest-api-v1.md`, `rest-api-v2.md`,
`rest-api-job-lifecycle.md`, `telemetry.md` (en + zh)*
| Doc said | Code does | Evidence |
|---|---|---|
| overview returns `"works"` | field is `workers`; v1 sample also omitted
`pendingJobs` | `resourcemanager/resource/OverviewInfo.java:33,35` |
| `/running-jobs` metrics keys `sourceReceivedCount` / `sinkWriteCount` |
keys are `SourceReceivedCount` / `SinkWriteCount` | `MetricNames.java:28,32` |
| finished job field `finishedTime`; no `startTime` | `finishTime`
(`RestConstant.FINISH_TIME`) and `startTime` are emitted |
`RestConstant.java:45,47`, `BaseService.java:449,576-581` |
| unknown job returns `{"jobId": ""}` | returns the requested id |
`JobInfoService.java:114` |
| `/submit-job`, `/submit-job/upload`, `/stop-job` return numeric `jobId` |
returned as a JSON string (only batch `/stop-jobs` is numeric) |
`BaseService.java:1373`, `JobInfoService.java:431,443` |
| v1 option-rules `type` supports only `source`/`sink`; stale response
sample | `transform` is accepted; response has `valueConstraints` and
`conditionOperator*` fields | `OptionRulesService.java`,
`OptionRuleResponse.java` (shared by v1/v2) |
| `/logs/:jobId` "add `jobId` in the request body `params`" | GET endpoint;
id is a path segment | `RestHttpGetCommandProcessor.java` `getAllNodeLog` |
| `logLink`/`node` samples on `:5801/hazelcast/rest/maps/logs/…`; v2 `/log`
examples on 5801 | links are built from the Jetty HTTP port (8080)
`…/logs/<file>` | `LogService.java:95-127` |
| `/running-jobs?page=` returns a bare array | wrapped as `{"data": [...],
"total": n}` when `page` is given | `PageBaseServlet.java:41-57` |
| `/metrics/realtime/jobs` sample lacks `collector` | always returned |
`RealtimeMetricsServlet.java`, `RealtimeMetricsService.getCollectorStatus()` |
| `/running-jobs/summary` undocumented | registered on v1 and v2, returns
`jobId`,`jobName`,`jobStatus`,`createTime` | `RestConstant.java:88`,
`JettyService.java:258`, `JobInfoService.java:254-303` |
| job status `CANCELLED` | enum is `CANCELED` | `JobStatus.java:62` |
| savepoint path "returned in job final state" as `savepointPath`; section
6.3 documents `restore.mode` / `savepoint.path` env options | no such field or
options exist; restore is driven only by `restoreMode`/`restoreSourceJobId` |
`BaseService.java:353-589`, `RestConstant.java:29-31` |
| `job_count` label list lacks `pending` | exported |
`JobMetricExports.java:57` |
*Zeta operations — `security.md`, `engine-jar-storage-mode.md`,
`hybrid-cluster-deployment.md`, `separated-cluster-deployment.md`,
`user-command.md`, `tcp.md` (en + zh)*
| Doc said | Code does | Evidence |
|---|---|---|
| `enable-http` default `true` | default `false` (shipped
`config/seatunnel.yaml` sets `true`) | `ServerConfigOptions.java:300-304`,
`config/seatunnel.yaml:44` |
| jar storage key `connector-jar-storage-enable`, `jar-storage` block at
YAML root | key is `enable`; `jar-storage` and `coordinator-service` are only
parsed under `seatunnel.engine` — a root-level block is silently ignored |
`ServerConfigOptions.java:423-424`,
`YamlSeaTunnelDomConfigProcessor.java:89-96,247-250,342-345`,
`seatunnel-engine-common/src/main/resources/seatunnel.yaml` |
| `max-thread-num` = "max job count executed at same time" | it is the
coordinator executor `maximumPoolSize` | `CoordinatorService.java:306-308`,
`ServerConfigOptions.java:493-496` |
| `seatunnel.sh -h` output | missing `--set-job-id`,
`--checkpoint-overview`, `--checkpoint-history`,
`--checkpoint-history-pipeline`, `--checkpoint-history-limit`,
`--checkpoint-history-status` | `ClientCommandArgs.java:115-148` |
| members without ports try `5701`, `5702`; `-m` example on `:5701` |
SeaTunnel ships `port: 5801` (`5802` worker), `auto-increment: false` |
`config/hazelcast.yaml:33-35`, `config/hazelcast-worker.yaml:27-29` |
*Transforms — `filter.md`, `transform-multi-table.md`, `data-validator.md`,
`multi-table-transform-and-join-boundary.md`, `recipes.md`,
`dynamic-compile.md` (en + zh)*
| Doc said | Code does | Evidence |
|---|---|---|
| `rule_match_mode` default `-` | `FIRST_MATCH` |
`TransformCommonOptions.java:51-53` |
| `field_rules` required = no | required (non-empty) in single-table mode |
`DataValidatorTransformFactory.java:53-60` |
| per-table type casting via `FieldMapper` `define_sink_type` option;
TableMerge example with `merge_by_field` and without `table` | no such options;
`TableMerge` requires `table` when `table_transform` is absent; real mechanism
is the `DefineSinkType` transform (`columns`) | `TableMergeConfig.java:38-54`,
`TableMergeTransformFactory.java:41-61`,
`DefineSinkTypeTransformConfig.java:43` |
| a sink can use `table_match_regex` to capture unmatched tables |
`table_match_regex` is transform-only; unmatched tables pass through via an
identity transform and a sink receives every table of its input stream |
`TransformCommonOptions.java:44-48`, `AbstractMultiCatalogTransform.java:106` |
| "no built-in explode-array-to-rows transform" | SQL transform `LATERAL
VIEW EXPLODE` | `ZetaSQLFunction.java` `explode(...)`, `sql-functions.md` |
| `absolute_path` is "Java or Groovy" only | Scala is also a
`compile_language` | `CompileLanguage.java` |
*Introduction / FAQ — `faq.md`, `introduction/concepts/schema-feature.md`
(en + zh), `zh/introduction/concepts/incompatible-changes.md`*
| Doc said | Code does | Evidence |
|---|---|---|
| CDC does not support tables without a primary key | unique-key fallback,
else single split; `exactly_once` needs a non-nullable key |
`AbstractJdbcSourceChunkSplitter.java:528-553`, `incompatible-changes.md` CDC
entry |
| CDC source list | missing DB2, OceanBase, Vitess CDC (all have doc
pages/modules) | `docs/en/connectors/source/*-CDC.md` |
| `primaryKey.columns` | parser requires `primaryKey.columnNames` and throws
otherwise | `PrimaryKeyOptions.java:43`, `ReadonlyConfigParser.java:278` |
| array elements limited to primitives; `"{a = int, b = string}"`
"equivalent to `{a = int, c = string}`" | `map` and nested `array` elements are
parsed; typo | `SeaTunnelDataTypeConvertorUtil.java:237-242` |
| zh `incompatible-changes.md` | missing the whole "Helm Chart: REST API v1
disabled by default" entry present in en |
`deploy/kubernetes/seatunnel/conf/hazelcast-master.yaml:21-23`,
`values.yaml:58-65` |
**Areas / files updated** — 37 files (18 en + 19 zh):
`docs/{en,zh}/engines/zeta/{rest-api-v1,rest-api-v2,rest-api-job-lifecycle,telemetry,security,engine-jar-storage-mode,hybrid-cluster-deployment,separated-cluster-deployment,user-command,tcp}.md`,
`docs/{en,zh}/transforms/{filter,transform-multi-table,data-validator,multi-table-transform-and-join-boundary,recipes,dynamic-compile}.md`,
`docs/{en,zh}/faq.md`, `docs/{en,zh}/introduction/concepts/schema-feature.md`,
`docs/zh/introduction/concepts/incompatible-changes.md`.
**English and Chinese docs** — both were audited; every fix is applied to
both languages where the counterpart has the same content. The only zh-only
change is the missing Helm Chart section in `incompatible-changes.md` (en
already has it).
**Duplicate check (PRs from the last 7 days)** — I listed every docs PR
opened since 2026-10-13 and compared file lists. The open docs PRs #12911,
#12865, #12813, #12771, #12730, #12709, #12693 cover
connector/getting-started/sql-transform pages and share **no files** with this
PR. #12856 (OpenAPI contract) touches `rest-api-v2.md` but only inserts one
introductory paragraph at the top of the API reference; none of the
field-name/sample/port fixes here overlap with it, so both can merge
independently. #12859 (Copy transform) and #12784 (`seatunnel-cli`) touch files
not modified here.
### Does this PR introduce _any_ user-facing change?
Documentation only. No code, configuration options or defaults are changed.
### How was this patch tested?
- `markdown-link-check -c .dlc.json` (the tool used by the `dead-link` CI
job, same version 3.8.7) run on all 37 changed files — 0 failures.
- A script resolved every relative `.md` link in the changed files — all
targets exist.
- All JSON code blocks touched by this change (48 blocks) were parsed with
`json.loads`; the only two non-parsing blocks are the pre-existing
`"transform": [...]` fragments in the multi-table boundary doc, which are
intentionally partial. All YAML blocks in the deployment / jar-storage pages
(76 blocks) were parsed with Ruby `YAML.safe_load`.
- Not run: `./mvnw spotless:apply` / `./mvnw -DskipTests verify` — this PR
contains no Java or build changes, so the Spotless and compile checks cannot be
affected; the Docusaurus site build was not run locally because the dead-link
and parse checks above cover the content of these markdown-only edits.
### Check list
* [x] If any new Jar binary package adding in your PR, please add License
Notice according [New License
Guide](https://github.com/apache/seatunnel/blob/dev/docs/en/developer/new-license.md)
— N/A
* [x] If necessary, please update the documentation to describe the new
feature. https://github.com/apache/seatunnel/tree/dev/docs
* [x] If necessary, please update `incompatible-changes.md` to describe the
incompatibility caused by this PR. — zh `incompatible-changes.md` synced with
en; no new incompatibility introduced
* [x] If you are contributing the connector code, please check that the
following files are updated — N/A
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
