zhangshenghang opened a new pull request, #12911:
URL: https://github.com/apache/seatunnel/pull/12911
### Purpose of this pull request
Yes, this is a contribution to Apache SeaTunnel: a documentation-only batch
that fixes statements in the connector and transform docs that contradict the
connector source code. Every fix below was verified by reading the
corresponding `*Options` / `*Factory.optionRule()` / converter classes, and
each issue was fixed in both the English and the Chinese document whenever both
contain it.
#### Documentation issues found and what was changed
**Kafka sink / source** (`docs/{en,zh}/connectors/{sink,source}/Kafka.md`)
- The `format` option table and the FAQ "supported formats" lists omitted
`compatible_debezium_json` and/or `compatible_kafka_connect_json` (and
`maxwell_json` in the sink FAQ), although `MessageFormat` defines all of them
and the same docs already reference them elsewhere.
- The SASL/Kerberos FAQ examples used top-level keys such as
`kafka.security.protocol` / `kafka.sasl.jaas.config`. The connector only
forwards properties placed inside the `kafka.config` map
(`KafkaSinkWriter.getKafkaProperties`,
`KafkaSourceConfig.createKafkaProperties`), so a user copying that example
would have authentication silently ignored. The examples now use `kafka.config
= { ... }` like the existing Kerberos task examples, with an explicit note.
- The source doc referenced a non-existent `kafka.max.poll.records` key;
corrected to `max.poll.records` inside `kafka.config`.
**Hive sink / source** (`docs/{en,zh}/connectors/{sink,source}/Hive.md`)
- Both docs claimed CSV / JSON (and markdown for the source) support.
`HiveTableUtils.parseFileFormat` only accepts text/parquet/orc tables and
throws for anything else, and the format is derived from the Hive table
(`STORED AS`), not from a connector option. Removed those claims (including a
whole markdown-parsing paragraph that describes a feature the Hive connector
does not have) and the CSV/JSON `compress_codec` entries.
- The sink FAQ invented a `file_format_type` option plus `JSON`/`SEQUENCE`
support, and a `partition_by` option. `HiveSinkFactory.optionRule()` has
neither; `HiveSink` always overrides `file_format_type` and `partition_by` from
the Hive Metastore table (or from `save_mode_create_template` for auto-created
tables). Rewrote both FAQ entries accordingly.
- Removed a stray "path of `hive-site.xml`" sentence under `krb5_path`.
**HdfsFile sink** (`docs/{en,zh}/connectors/sink/HdfsFile.md`)
- The English feature list put `canal_json` / `debezium_json` /
`maxwell_json` under "compress codec"; they are file formats
(`FileFormat.java`). Moved them to the file format list and into the
`file_format_type` row; the Chinese row was missing `xml` / `binary`, so the
two languages now list the same formats.
**StarRocks sink** (`docs/{en,zh}/connectors/sink/StarRocks.md`)
- `batch_max_rows` is `int` and `batch_max_bytes` is `long`
(`StarRocksSinkOptions`); the doc had them swapped. Added the missing
`multi_table_sink_replica` row (in `StarRocksSinkFactory.optionRule()`).
**Doris sink** (`docs/{en,zh}/connectors/sink/Doris.md`)
- `database` and `table` were marked required, but
`DorisSinkFactory.optionRule()` lists them as optional and `renameCatalogTable`
falls back to the upstream table's database/table name. Added the missing
`default-database` (default `information_schema`) and
`multi_table_sink_replica` rows. The Chinese placeholder list was missing
`rowtype_duplicate_key` (present in English and in `SaveModePlaceHolder`).
**Clickhouse sink** (`docs/{en,zh}/connectors/sink/Clickhouse.md`)
- `multi_table_sink_replica` was described as "data is written to multiple
tables in parallel"; per `MultiTableSink`, it is the number of writer replicas
created per table.
**Jdbc sink / source** (`docs/{en,zh}/connectors/{sink,source}/Jdbc.md`)
- Sink: documented `schema`, `decimal_type_narrowing`, `int_type_narrowing`
and `handle_blob_as_string`, which are all in `JdbcSinkFactory.optionRule()`
but absent from the table; `field_ide` is declared with
`enumType(FieldIdeEnum.class)`, so its type is now `Enum` like the other enum
options.
- Sink appendix: the Oracle XA data source class was
`oracle.jdbc.xa.OracleXADataSource`. In ojdbc8 (verified with `javap` on 19.18
and 21.5) that class is **abstract**; `DataSourceUtils.loadDataSource`
instantiates the class via `getDeclaredConstructor().newInstance()`, so this
value fails at runtime. Replaced with the concrete
`oracle.jdbc.xa.client.OracleXADataSource`, which is what
`docs/*/connectors/sink/Oracle.md` already uses.
- Source: documented `access_key_id` / `secret_access_key` / `region`
(Amazon Aurora DSQL auth, in `JdbcSourceFactory.optionRule()` and already
documented for the sink) and added `DSQL` to the dialect list
(`DsqlDialectFactory` is shared by source and sink).
**SqlServer sink** (`docs/{en,zh}/connectors/sink/SqlServer.md`)
- The type mapping said `BINARY` / `VARBINARY` / `IMAGE` / `TIMESTAMP` are
"not supported yet" and mapped `DATETIMEOFFSET` to `LOCAL_DATE_TIME`.
`SqlServerTypeConverter` maps the former four to `BYTES`
(`PrimitiveByteArrayType`) and `DATETIMEOFFSET` to `OFFSET_DATE_TIME_TYPE`
(`TIMESTAMP_TZ`).
**MySQL-CDC source** (`docs/{en,zh}/connectors/source/MySQL-CDC.md`)
- `startup.specific-offset.skip-events` / `skip-rows` were documented with
default `0`, but both are `noDefaultValue()`; the presence of these keys is
also used by `MySqlIncrementalSource.hasSpecificStartupOffset`, so "no default,
nothing skipped when omitted" is the accurate description.
**MongoDB / TDengine / Typesense sinks**
(`docs/{en,zh}/connectors/sink/{MongoDB,TDengine,Typesense}.md`)
- MongoDB and TDengine: `multi_table_sink_replica` is in the factory option
rule but missing from the tables. Typesense: `protocol` (default `http`, read
by `TypesenseClient`, required for Typesense Cloud / https) was documented for
the source but missing for the sink.
**File sources and SQL transform**
- `docs/{en,zh}/connectors/source/CosFile.md`: `null_format` is in
`CosFileSourceFactory.optionRule()` and documented for every sibling file
source, but was missing here.
- `docs/zh/connectors/source/ObsFile.md`: removed a duplicated `sheet_name`
row.
- `docs/zh/transforms/sql.md`: synced the "Support struct query" changelog
entry that only existed in the English doc.
#### Files updated
34 files: 17 English + 17 Chinese documents under
`docs/{en,zh}/connectors/sink/` (Clickhouse, Doris, HdfsFile, Hive, Jdbc,
Kafka, MongoDB, SqlServer, StarRocks, TDengine, Typesense),
`docs/{en,zh}/connectors/source/` (CosFile, Hive, Jdbc, Kafka, MySQL-CDC, plus
zh ObsFile) and `docs/zh/transforms/sql.md`. English and Chinese versions were
both checked for every connector in scope; where only one language had the
issue (e.g. the HdfsFile codec list, the zh Doris placeholder list, the zh
ObsFile duplicate row), only that language was changed.
#### Duplicate-PR check (last 7 days)
- Listed all PRs created since 2026-10-12 (`gh pr list --search
"created:>=2026-10-12"`) and collected the doc files they touch. The previous
verified-against-source doc batches (#12758, #12771, #12813, #12833, #12865,
#12888) do not touch any of the files in this PR; this PR was deliberately
scoped to connectors that none of them cover.
- Feature/fix PRs that touch some of the same files were diffed for the
specific issues fixed here (`format` lists / SASL examples in Kafka, the Jdbc
option rows, DSQL, the Oracle XA class, Doris/StarRocks rows, Typesense
`protocol`, MySQL-CDC defaults): none of #12761, #12769, #12776, #12791,
#12792, #12828, #12839, #12876, #12877, #12880, #12893, #12900, #12907 contain
these fixes, so there is no duplication.
- One intentional omission: merged #12804 deliberately marks `field_rules`
of the DataValidator transform as optional with an explanatory sentence, so
that doc was left untouched.
- Possible textual (not semantic) conflict: open #12861 edits one line
inside the Hive-source markdown paragraph that this PR removes (the Hive
connector has no markdown support). Whichever merges second needs a trivial
conflict resolution.
### Does this PR introduce _any_ user-facing change?
Documentation only. No code, configuration option, default value or behavior
is changed; the docs are corrected to describe the existing behavior.
### How was this patch tested?
- Every statement above was verified against the source on `dev`
(`MessageFormat`, `KafkaSinkWriter`, `KafkaSourceConfig`, `HiveTableUtils`,
`HiveSink`, `HiveSinkFactory`, `FileFormat`, `StarRocksSinkOptions`/`Factory`,
`DorisSinkFactory`/`DorisSinkOptions`, `SaveModePlaceHolder`, `MultiTableSink`,
`JdbcSinkFactory`/`JdbcSourceFactory`/`JdbcCommonOptions`/`JdbcSinkOptions`,
`DsqlDialectFactory`, `DataSourceUtils`, `SqlServerTypeConverter`,
`MySqlIncrementalSourceOptions`/`MySqlIncrementalSource`, `MongodbSinkFactory`,
`TDengineSinkFactory`, `TypesenseBaseOptions`/`TypesenseClient`,
`CosFileSourceFactory`), and the Oracle XA class was checked with `javap`
against the ojdbc8 19.18.0.0 and 21.5.0.0 jars.
- Ran the same documentation build that CI runs: cloned
`apache/seatunnel-website`, synced this branch with `tools/documents/sync.sh`,
kept only the current/latest version in `versions.json`, and ran `npm install
&& npm run build`. The Docusaurus build succeeded for both the `en` and `zh-CN`
locales with no broken-link or MDX warnings for the edited pages.
- Ran a script over all changed files checking Markdown table column
consistency and that every relative link / `import` target exists: 0 problems.
- `./mvnw spotless:apply` / `./mvnw -DskipTests verify` were not run because
the change contains no Java or build files.
### 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 — this PR is the
documentation update
* [x] If necessary, please update `incompatible-changes.md` to describe the
incompatibility caused by this PR. — N/A, no behavior change
* [x] If you are contributing the connector code, please check that the
following files are updated: — N/A, documentation only
--
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]
