zhangshenghang opened a new pull request, #12730:
URL: https://github.com/apache/seatunnel/pull/12730
## Purpose of this PR
This PR fixes a batch of real documentation bugs found by auditing the docs
against the Java source code on the current `dev` branch. All fixes are backed
by code evidence; no formatting-only or cosmetic churn is included.
## Documentation issues found and what was changed
### Clickhouse connector (wrong type mappings)
- `docs/{en,zh}/connectors/source/Clickhouse.md`: the doc claimed `DateTime
-> TIME`. The source converter (`TypeConvertUtil`) maps ClickHouse `DateTime`
(object class `LocalDateTime`) to `LOCAL_DATE_TIME_TYPE`, i.e. `TIMESTAMP`;
`LOCAL_TIME_TYPE` is never produced. Also split the over-lumped integer row to
match the actual object-class mapping (`Int8` -> `TINYINT`, `Int16`/`UInt8` ->
`SMALLINT`, `Int32`/`UInt16` -> `INT`, `Int64`/`UInt32`/`UInt64` -> `BIGINT`),
verified against the clickhouse-client 0.3.2-patch11 `ClickHouseDataType`
object classes.
- `docs/{en,zh}/connectors/sink/Clickhouse.md`: the doc claimed `TIME ->
DateTime`. `ClickhouseTypeConverter.reconvert` maps `TIME` to `STRING` (this
converter generates the `${rowtype_fields}` DDL used by
`save_mode_create_template`). Added the missing `TIMESTAMP -> DateTime64` and
`BOOLEAN -> Bool` rows, split `TINYINT -> Int8`, `SMALLINT -> Int16`, `INT ->
Int32` per the converter, and fixed the example that used Kafka's port `9092`
for a ClickHouse HTTP host (everything else in the doc uses `8123`).
### File connectors
- `docs/{en,zh}/connectors/source/ObsFile.md`: the STS example used
`hadoop_obs_properties`, an option that does not exist anywhere in the codebase
(`ObsFileBaseOptions` defines only
`access_key`/`access_secret`/`endpoint`/`bucket`, and `ObsConf` maps exactly
those three into the Hadoop config). Rewrote the example to use the real
options and documented that no extra Hadoop OBS property pass-through (e.g.
session token) exists. Also removed a duplicated `sheet_name` row in the zh
table.
- `docs/{en,zh}/connectors/sink/OssFile.md` and
`docs/zh/connectors/sink/CosFile.md`: the CDC schema-evolution example block
used the wrong plugin name `LocalFile` for an OSS/COS sink (silently misleading
for copy-paste users). Changed to `OssFile` / `CosFile` with the connector's
required credential options, aligned with the correct en CosFile example.
- `docs/{en,zh}/connectors/source/LocalFile.md`: `file_format_type` was
marked required, but `LocalFileSourceFactory` registers it as `.optional(...)`
(only `tables_configs`/`path` are exclusive-required). Marked it optional.
- `docs/{en,zh}/connectors/sink/{CosFile,OssJindoFile}.md`: added the
`enable_header_write`, `schema_save_mode`, `data_save_mode` option rows that
every sibling file-sink doc documents and that the shared base sink
(`FileBaseSinkOptions`, read unconditionally by `BaseMultipleTableFileSink`)
supports.
- `docs/{en,zh}/connectors/sink/ObsFile.md`: added missing shared sink
option rows (`tmp_path`, `filename_extension`, `encoding`,
`csv_string_quote_mode`, `enable_header_write`, `schema_save_mode`,
`data_save_mode`), limited to the formats the doc claims for this connector.
- `docs/{en,zh}/connectors/sink/BosFile.md`: added 10 missing shared sink
option rows (excel/csv/cdc/save-mode options), matching `FileBaseSinkOptions`
defaults.
- `docs/{en,zh}/connectors/source/OssFile.md`: added
`archive_compress_codec` (enum `zip`/`tar`/`tar.gz`/`gz`/`none`, default
`none`), `enable_file_split` (default `false`, text/json/csv/parquet per
`FileFormat.supportFileSplit()`) and `file_split_size` (default `134217728`)
rows that other file-source docs already document.
### CDC production cookbook
- `docs/{en,zh}/connectors/cdc-production-cookbook.md`: the MySQL-CDC
examples used `exactly-once = true`, but the option key is `exactly_once`
(underscore, no fallback keys in `SourceOptions`), so the documented config
silently runs at-least-once. The Postgres-CDC example used `schema-names`, but
the Postgres connector option is `schema-name`
(`PostgresIncrementalSourceOptions.SCHEMA_NAME`); the Oracle example correctly
keeps `schema-names` (its code key is plural).
### Engine docs
- `docs/{en,zh}/engines/event-listener.md`: the `EventType` table documented
`READER_OPEN`, `READER_CLOSE`, `WRITER_OPEN`, `WRITER_CLOSE`, which do not
exist in `org.apache.seatunnel.api.event.EventType` (there is no `WRITER_OPEN`
at all). Replaced them with the real `LIFECYCLE_*` values and added the
undocumented enum values (`SCHEMA_CHANGE_CHANGE_COLUMN`,
`SCHEMA_CHANGE_RENAME_TABLE`, `SCHEMA_CHANGE_ALTER_TABLE_COMMENT`,
`SCHEMA_CHANGE_ALTER_COLUMN_COMMENT`, `SCHEMA_CHANGE_RESTORE`,
`READER_MESSAGE_DELAYED`), each mapped to the event class that actually returns
it. Fixed the example imports (the classes live in
`org.apache.seatunnel.api.table.schema.event`,
`org.apache.seatunnel.api.source.event`, `org.apache.seatunnel.api.sink.event`,
not `org.apache.seatunnel.api.event.*`) and the `switch` case labels.
- `docs/{en,zh}/engines/zeta/stain-trace.md`: documented
`stain-trace-sample-interval` as the engine parameter, but the canonical key is
`stain-trace-sample-rate` (`ServerConfigOptions.STAIN_TRACE_SAMPLE_RATE`); the
`-interval` spelling is only a backward-compatible alias in
`YamlSeaTunnelDomConfigProcessor`. Now documents `-rate` as primary and
mentions the alias.
### Others
- `docs/{en,zh}/connectors/source/Iceberg.md`: the `table_list` row now
documents the per-item split tuning keys `splitSize` / `splitLookback` /
`splitOpenFileCost` supported by `SourceTableConfig` (deserialized with a
default Jackson mapper, so camelCase); the zh table's three Kerberos rows used
`no` instead of `否` in the required column.
- `docs/{en,zh}/transforms/sql.md`: `plugin_input` was typed `string`, but
it is `List<String>` (`ConnectorCommonOptions.PLUGIN_INPUT`) and `SQLTransform`
reads element 0; fixed the type and clarified the multi-table behavior.
## Were both English and Chinese docs checked?
Yes. Every fix was applied to both `docs/en` and `docs/zh` where the same
content exists in both languages. 30 files changed in total (15 en / 15 zh).
## Duplicate check (last 7 days)
Checked all open docs PRs before starting: #12709, #12693, #12679, #12641,
#12621, #12615, #12602, #12570, #12514 (another author), #12459. Several
initially planned fixes were already covered by those PRs (e.g. PostgreSQL-CDC
`schema-name`, SqlServer-CDC `connect.timeout.ms`, MongoDB-CDC `format`,
`engine-jar-storage-mode` `enable` key, `security.md` `enable-http` default,
`telemetry.md` endpoints, `user-command.md` checkpoint options,
`state-storage-and-recovery.md` checkpoint keys/CLI/IMap names, `rest-api-v2`
/log port). All overlapping fixes were dropped from this PR; every remaining
fix above was verified not to overlap with the diffs of those PRs.
## Verification
- Verified each claim against the source before editing: type converters
(`TypeConvertUtil`, `ClickhouseTypeConverter`, plus the `ClickHouseDataType`
object classes decompiled from clickhouse-client 0.3.2-patch11), option
definitions (`ObsFileBaseOptions`, `FileBaseSinkOptions`,
`FileBaseSourceOptions`, `SourceOptions`, `ServerConfigOptions`, `EventType`),
factory option rules (`LocalFileSourceFactory`, Obs/Oss/Jindo sink factories)
and event-class-to-EventType mappings.
- Ran a table-structure check over all 30 changed files (column-count
consistency per table): 0 issues.
- Ran a relative-link check over all changed docs: 0 broken links.
- Grepped the changed files for the old wrong keys/values (`exactly-once =`,
`hadoop_obs_properties`, `stain-trace-sample-interval:`, port `9092`,
`LocalFile {` in OSS/COS examples): no leftovers.
- Did not run the full Docusaurus build (pnpm install/build) because the
changes are markdown-only and the table/link checks above cover the syntax
surface touched; happy to run it if reviewers prefer.
--
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]
