zhangshenghang opened a new pull request, #12459:
URL: https://github.com/apache/seatunnel/pull/12459
## Purpose of this PR
This PR fixes a batch of real documentation defects found by auditing the
docs against the Java source code on `dev`. It covers connector option tables,
connector type-mapping tables, Zeta engine guides, REST API docs,
getting-started content and the docs sidebar navigation. All fixes are backed
by code evidence; no cosmetic-only or reformat-only changes are included.
## Issues found and changes made
### Connector option tables vs code
- **DataHub sink (en+zh)**: docs told users to use a `${table}` placeholder
in `topic` and described `${table_name}` as a deprecated alias — inverted and
wrong. The engine only replaces `${table_name}` (`TablePlaceholder` has no
`table` key), so `${table}` would be written literally. Fixed all occurrences
(descriptions, examples, FAQ).
- **Kafka source (en+zh)**: `format` row omitted
`compatible_kafka_connect_json`, although the same page's
`value_converter_schema_enabled` row only makes sense with it
(`MessageFormat.COMPATIBLE_KAFKA_CONNECT_JSON`).
- **Kafka sink (en+zh)**: FAQ format list omitted `maxwell_json` and
`compatible_debezium_json`, both supported by `DefaultSeaTunnelRowSerializer`
and already listed in the same page's `format` row.
- **Pulsar source (en+zh)**: FAQ claimed only `EARLIEST`/`LATEST` startup
modes; the code (`StartMode` enum) and the page's own table support `EARLIEST`,
`LATEST`, `SUBSCRIPTION`, `TIMESTAMP`.
- **RocketMQ source (en+zh)**: FAQ listed only 3 of the 5 `start.mode`
values and omitted the default `CONSUME_FROM_GROUP_OFFSETS`.
- **JDBC-family sources** (Mysql, Oracle, OceanBase, Vertica, HiveJdbc,
SqlServer, en+zh): `partition_lower_bound`/`partition_upper_bound` documented
as `BigDecimal` (SqlServer: `Long`); the options are `stringType()` in
`JdbcSourceOptions`. `partition_num` documented default "job parallelism" on
pages whose siblings say `10`; runtime default is `DEFAULT_PARTITION_NUMBER =
10` (`JdbcSourceTableConfig`).
- **PostgreSQL-CDC (en+zh)**: `server-time-zone` default shown as `UTC`; the
code default is `ZoneId.systemDefault()` (the row's own description already
said so).
- **DB2 source (en+zh)**: `query` marked unconditionally required, but
`table_path`/`table_list` reads are supported (generic `JdbcSourceFactory`
option rule + registered DB2 catalog).
- **Jdbc source & sink (en+zh)**: dialect lists missing registered dialects
`OpenGauss`, `Presto`, `Dsql`, `DuckDB` (`DatabaseIdentifier` + dialect
factories); missing entries actively mislead because unsupported dialects fall
back to `GenericDialect`.
- **Sls sink (en+zh)**: `log_group_size` option (int, default 100,
`SlsSinkOptions.LOG_GROUP_SIZE`) missing from the option table.
- **Prometheus sink (en+zh)**: `retry` documented default `3`; the HTTP
`retry` option has no default and the writer performs a single attempt when
unset.
- **Hudi sink (en+zh)**: `op_type` section used lowercase values that fail
enum parsing; corrected to `INSERT`/`UPSERT`/`BULK_INSERT` (consistent with the
same page's table).
- **Databend sink (en+zh)**: `database` row referenced a non-existent
`generate_sink_sql` option (grep in connector-databend returns nothing).
- **DuckDB source & sink, Snowflake source & sink, SqlServer sink (en+zh)**:
data-type mapping tables corrected against `DuckDBTypeConverter`,
`SnowflakeTypeConverter` and `SqlServerTypeConverter` (e.g. DuckDB
`UTINYINT→TINYINT`, `UBIGINT→BIGINT`, `TIMESTAMP WITH TIME ZONE→TIMESTAMP_TZ`,
`ARRAY/STRUCT/MAP→STRING` on read and unsupported on write; Snowflake
`GEOGRAPHY/GEOMETRY→STRING` unconditionally, `TIMESTAMP_LTZ/TZ→TIMESTAMP_TZ`;
SqlServer `DATETIMEOFFSET→OFFSET_DATE_TIME`, rowversion `TIMESTAMP→BYTES`), and
`query` no longer marked unconditionally required on DuckDB/Snowflake source
pages.
### Zeta engine / general docs
- **state-storage-and-recovery (en+zh)**: this page documented configuration
that does not exist (`checkpoint.max-concurrent`,
`checkpoint.tolerable-failure`, `hazelcast.fs.base-dir`,
`hazelcast.fs.write-behind-delay-seconds`, `hazelcast.fs.compaction-threshold`,
a `wal/` directory layout, IMap names
`running-job-state`/`running-job-metrics`/`running-pipeline-state`, a
`<namespace>/savepoint/` layout) and invalid CLI (`--stop-job ... --savepoint`,
`-r <jobId> --savepoint`). Rewritten against the real mechanism: real
checkpoint keys (`interval`/`timeout`/`storage`/`retain-after-job-cancelled`),
savepoint via `seatunnel.sh --savepoint <jobId>`, real IMap names
(`engine_runningJobInfo`, `engine_runningJobState`, `engine_finishedJobState`,
`engine_finishedJobMetrics`, ... from `Constant.java`), and the real MapStore
persistence config from `FileMapStoreFactory` (cross-linked to
`separated-cluster-deployment.md`). The non-existent WAL section is replaced by
a MapStore file maintenance
section.
- **rest-api-job-lifecycle (en+zh)**: `CANCELLED` → `CANCELED` (`JobStatus`
enum); removed the fabricated `savepointPath` field from `/job-info` responses;
replaced the invented `restore.mode`/`savepoint.path` env keys (section 6.3)
with the real restore behavior (`restoreMode`/`restoreSourceJobId`).
- **security (en+zh)**: `enable-http` code default is `false`, doc said
`true` (`ServerConfigOptions.ENABLE_HTTP`).
- **log-analysis-with-ai (en+zh)** and **rest-api-v2 (en+zh)**: `/log` is a
Jetty v2 endpoint on the HTTP port (8080), not on the Hazelcast port 5801
(`JettyService` + `RestConstant`); also fixed a broken in-page anchor and the
non-existent `seatunnel-engine-server.log` file name.
- **hybrid-cluster-deployment (en+zh)**: real log files are
`logs/seatunnel-engine-master.log` / `seatunnel-engine-worker.log`
(`seatunnel-cluster.sh` sets `-Dseatunnel.logs.file_name`), not
`seatunnel-engine-server.log`.
- **tuning-guide (en+zh)**: text said `jcmd` while showing `jmap`; replaced
non-existent `logs/seatunnel-server.log` with
`logs/seatunnel-engine-master.log`.
- **logging (en+zh)**: `seatunnel.yml` → `seatunnel.yaml` (shipped file
name).
- **checkpoint-storage (en)**: invalid `//` comments inside a YAML example →
`#`.
- **resource-isolation (en+zh)**: invalid code fence language `hacon` →
`hocon`.
- **getting-started/submit-job-to-remote-zeta-cluster (en+zh)**: `--master
seatunnel://host:5801` does not run — `-m/--master` only accepts
`local`/`cluster` (`ClientCommandArgs.MasterType`); example rewritten to `-m
cluster` with the cluster address in `config/hazelcast-client.yaml`. Removed
the wrong "8090 Web UI" port row (Web UI is served on the Jetty HTTP port 8080).
- **introduction/concepts/schema-feature (en+zh)**: primaryKey field key is
`columnNames` (`PrimaryKeyOptions`), not `columns`; fixed a `{a = int, c =
string}` example typo.
- **docs/sidebars.js**: registered existing but unreachable pages: recipe
`getting-started/recipes/jdbc-to-jdbc` and Zeta pages
`engines/zeta/stain-trace` + `engines/zeta/stain-trace-quickstart`.
## Languages
English and Chinese docs were audited and fixed together; every fix above
was applied to both languages where both exist (a few items are en-only or
zh-only because the defect only exists there, e.g. the `//` YAML comments, the
missing zh Aerospike example, the broken en anchor).
## Duplicate check
Before opening this PR I checked all PRs opened in the last 7 days (and all
still-open docs PRs): #12452 (RDS links in MySQL-CDC/TiDB-CDC), #12447 (merged;
connector option rows), #12423, #12409, #12378, #12347 (earlier doc batches by
the same author), #12427 (Postgres/Kingbase sharding), #12359 (PostgreSQL CDC
audit). None of the issues fixed here were covered by them. Two files have a
partial overlap by file path only, with disjoint content:
`docs/zh/engines/zeta/rest-api-v2.md` and
`docs/en/engines/zeta/hybrid-cluster-deployment.md` are also touched by #12423,
but in unrelated sections (checkpoint field tables / feature checklists); the
log-endpoint and log-file-name fixes here do not touch those hunks. The
`docs/en|zh/connector-v2/source/*` pages left in the wrong directory are
intentionally **not** moved here because #12378/#12409 already cover that
relocation.
## Verification
- Relative-link check across all 73 changed files: 0 broken links; the one
in-page anchor touched (`rest-api-v2.md#get-log-content-from-a-single-node`)
resolves to a real heading.
- Markdown table structural check (pipe-count consistency per table block)
on all changed files: 0 inconsistencies.
- `docs/sidebars.js` loads without errors (`node -e
"require('./docs/sidebars.js')"`).
- Every option/default/type/enum claim was verified against the
connector/engine source on this branch before editing (option classes,
factories, type converters, `ClientCommandArgs`, `ServerConfigOptions`,
`JettyService`/`RestConstant`, `seatunnel-cluster.sh`, `log4j2.properties`).
- No Java code is changed, so no build/test run is required; `./mvnw verify`
was not run for this docs-only change.
--
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]
