zhangshenghang opened a new pull request, #12833:
URL: https://github.com/apache/seatunnel/pull/12833
## Purpose of this PR
This PR fixes a batch of real documentation inaccuracies found by verifying
connector/transform docs line-by-line against the Java source code on this
branch. It covers 25 documentation files (13 English + 12 Chinese... see list
below; most fixes are applied to both languages).
## What documentation issues were found
All issues below were verified directly against the source code before
fixing:
1. **Invalid plugin name `Mysql` in JDBC sink examples**
(`docs/{en,zh}/connectors/sink/Mysql.md`): two multi-table-sync examples used
`sink { Mysql { ... } }`, but the JDBC sink factory identifier is `Jdbc`
(`JdbcSinkFactory.factoryIdentifier()`) and `plugin-mapping.properties` has no
`seatunnel.sink.Mysql` entry. A job copied from these examples fails with
"Could not find any factory for identifier 'Mysql'". Changed to `jdbc {`,
consistent with the other examples in the same file.
2. **Corrupted XA data source class name + wrong word**
(`docs/zh/connectors/sink/Oracle.md`): the option description contained
`Oracle.jdbc.xa.client。OracleXADataSource` (wrong package case, a Chinese full
stop inside the class name, unbalanced backtick). The same file's own example
already used the correct `oracle.jdbc.xa.client.OracleXADataSource`. Also fixed
the mistranslation "upstart" → "upsert" in the `enable_upsert` row.
3. **PostgreSql sink options table incomplete**
(`docs/{en,zh}/connectors/sink/PostgreSql.md`): the doc's own examples set
`batch_interval_ms = 5000` and `multi_table_sink_replica = 2`
(`JdbcSinkOptions` / `SinkConnectorCommonOptions`), but neither option had a
row in the options table. Added both rows (text mirrors the MySQL sink doc).
Also, the exactly-once note said only `is_exactly_once=true` is needed, but
`JdbcSinkFactory` validates that `max_retries` **must be 0** when exactly-once
is enabled ("JDBC XA sink requires max_retries equal to 0 when
is_exactly_once=true"); the note now says `is_exactly_once=true` and
`max_retries=0` (matching the MySQL/Oracle sink docs).
4. **DB2 type mapping wrong** (`docs/{en,zh}/connectors/sink/DB2.md`): per
`DB2TypeConverter`, `INT/INTEGER` → SeaTunnel `INT` (doc said `INTEGER`, which
is not a SeaTunnel type), `BIGINT` → `BIGINT` (doc said `LONG`), and
`DECIMAL/DEC/NUMERIC/NUM` keeps the column's declared precision/scale (doc said
fixed `DECIMAL(38,18)`).
5. **Nonexistent XA class in OceanBase example**
(`docs/{en,zh}/connectors/sink/OceanBase.md`): the exactly-once example used
`com.oceanbase.jdbc.OceanBaseXADataSource`, which does not exist in
oceanbase-client (verified against the driver jar). The class implementing
`javax.sql.XADataSource` is `com.oceanbase.jdbc.OceanBaseDataSource` (verified
with `javap`). Also fixed the `VARBINAR` → `VARBINARY` typo in the type-mapping
table.
6. **Reference to nonexistent option**
(`docs/{en,zh}/connectors/sink/Databend.md`): the `database` row described
behavior "when `generate_sink_sql = true`", but `generate_sink_sql` does not
exist anywhere in connector-databend (grep returns nothing); the sink reads
`database`/`table` directly to locate the target table.
7. **Kingbase source options**
(`docs/{en,zh}/connectors/source/Kingbase.md`): `query` was marked
Required=Yes, but `JdbcSourceFactory.optionRule()` only requires `url` and
`driver` — `query` is optional (`table_path`/`table_list` are alternatives, and
the canonical Jdbc doc marks it No).
`partition_lower_bound`/`partition_upper_bound` are declared as `StringType`
options in `JdbcSourceOptions` (doc said `BigDecimal`). Fixed invalid example
SQL `select * id, name from ...` → `select id, name from ...`. Aligned the zh
`NUMERIC` type-mapping row with the en row (precision/scale detail).
8. **Wrong feature checkboxes**:
- Zendesk/Klaviyo/Lemlist sources claimed [x] column projection, but they
extend `HttpSource`/`AbstractSingleSplitSource`, which does not implement
`SupportColumnProjection` → unchecked (en+zh).
- Zendesk sink claimed [ ] multi-table write, but `ZendeskSink implements
SupportMultiTableSink` → checked (en+zh).
- Prometheus source claimed [ ] stream, but
`PrometheusSource.getBoundedness()` returns `Boundedness.UNBOUNDED` in
streaming mode and the doc itself documents stream-only options/examples →
checked (en+zh).
9. **Misleading prose**: Zendesk source said it differs from the Http source
in "the required authentication options and the `format` default", but
`ZendeskSourceFactory` never overrides `format` → claim removed (en+zh).
Lemlist source said a user could override the generated `Authorization` header
via `headers`, but `LemlistSourceParameter` always overwrites
`headers[Authorization]` with the generated value → reworded (en+zh). Copy
transform (`docs/{en,zh}/transforms/copy.md`): `fields` was marked
unconditionally required, but `CopyFieldTransformFactory` declares `fields` and
`src_field` as an exclusive pair — the required cell now notes the deprecated
`src_field`+`dest_field` alternative.
## Which areas/files were updated (25 files)
- `docs/{en,zh}/connectors/sink/`: Mysql, Oracle (zh), PostgreSql, DB2,
OceanBase, Databend, Zendesk
- `docs/{en,zh}/connectors/source/`: Kingbase, Zendesk, Klaviyo, Lemlist,
Prometheus
- `docs/{en,zh}/transforms/`: copy
## Were English and Chinese docs both checked?
Yes. Every fix above was applied to both the English and Chinese
documentation wherever both files contain the same content; two issues were
zh-only (Oracle corrupted class name/upstart typo, Kingbase NUMERIC row)
because the en files were already correct.
## How duplicate PRs were checked
I listed all open PRs from the last 7 days before starting (via `gh pr list
--repo apache/seatunnel`):
- My own recent docs PRs #12813 (Oct 15), #12771 (Oct 14), #12758 (Oct 13),
#12730 (Oct 11), #12709 (Oct 9), #12693 (Oct 8), #12679 (Oct 7) and #12830
(badge fix, Oct 16), plus rdlau01's #12816 (Filter transform).
- I extracted the full file lists of those PRs and explicitly **excluded**
every connector they touched (e.g., Kafka, Jdbc, Doris, Paimon, Http, IoTDB,
Redis source, MongoDB-CDC, MySQL-CDC, Hudi, Fluss, Tablestore,
filter/jsonpath/sql/llm transforms, etc.) from this batch. None of the files or
issues in this PR overlap with those PRs: all target files here (DB2 sink,
OceanBase sink, PostgreSql sink, Databend sink, Mysql sink, Kingbase source,
Zendesk/Klaviyo/Lemlist, Prometheus source, copy transform) were untouched by
them, which the audit also confirmed (several of those connectors' docs were
re-verified clean and left alone).
## How was this verified?
- Every changed table row was checked against the corresponding `Option`
definition / `OptionRule` in the Java source (file:line evidence in each
finding above).
- The OceanBase XA class name was verified against the actual driver jar in
the local Maven repository (`javap` shows `OceanBaseDataSource implements
javax.sql.XADataSource`; no `OceanBaseXADataSource` class exists).
- Post-run automated checks on all 25 changed files: every Markdown table
row opens and closes with `|`, pipe counts match each table's header row (no
broken tables), and all relative `.md` links resolve to existing files.
- Docs-only change: no Java/build code is affected, so the full Maven build
was not run; the checks above are the appropriate verification for this 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]
