zhangshenghang opened a new pull request, #12447:
URL: https://github.com/apache/seatunnel/pull/12447
## Purpose of this pull request
This PR fixes a batch of real documentation defects found by auditing
connector docs against the actual connector source on `upstream/dev` (option
definitions, `optionRule()` wiring, dialect type converters and runtime
fallbacks), and syncs Chinese docs that lagged behind their English
counterparts. Every fix listed below was verified against the cited source file
before editing. **66 documentation files** are updated (English + Chinese kept
in lockstep).
## What documentation issues were found and changed
### CDC connector docs (`docs/{en,zh}/connectors/source/`)
1. **`server-time-zone` default shown as `UTC` in MySQL-CDC, Oracle-CDC,
Opengauss-CDC and DB2-CDC**, while `JdbcSourceOptions.java:63-65` defaults to
`ZoneId.systemDefault().getId()`; the rows even contradicted their own
description ("If not set, then ZoneId.systemDefault() is used"). Default column
changed to `-`.
2. **`connect.timeout.ms` type shown as `Duration`** in the same four
connectors, while the code declares `longType()` (milliseconds). Changed to
`Long`; DB2-CDC also showed the default as `30s` instead of `30000`.
3. **Oracle-CDC documented a `decimal_type_narrowing` option (row + full
section with mapping tables) that does not exist in any CDC module** — the
option is defined only in `connector-jdbc` (`JdbcCommonOptions.java`), and
`OracleIncrementalSourceFactory.optionRule()` has no such entry. Row and
section removed (en + zh).
4. **Missing options that ARE consumed at runtime**:
`incremental.parallelism` (read by `IncrementalSource.java:125`) added to
MySQL-CDC and Opengauss-CDC; `enable_concurrent_read` (read by
`JdbcSourceConfigFactory.java:305`) added to Opengauss-CDC and DB2-CDC, with
code-accurate defaults (1 / true). MongoDB-CDC was deliberately left alone: its
runtime never reads these base options.
### Kafka source docs (`docs/{en,zh}/connectors/source/Kafka.md`)
5. **The `format = "NATIVE"` example set `value_converter_schema_enabled`,
which is a silent no-op there** — the option is only read in the
`COMPATIBLE_KAFKA_CONNECT_JSON` branch (`KafkaSourceConfig.java:384-390`).
Removed from the example and documented properly as a new option row with its
real default (`true`) and scope.
6. **The FAQ "supported message formats" list omitted `maxwell_json` and
`compatible_kafka_connect_json`**, contradicting the doc's own `format` row and
`MessageFormat.java`. List corrected in en + zh.
### JDBC-family docs (source + sink, en + zh)
7. **`partition_num` default documented as "job parallelism" in DuckDB,
Kingbase, Oracle and HiveJdbc source docs**, while the code default is a fixed
10 (`JdbcSourceTableConfig.java:42,97-99`); the DB2 source doc already
documented 10 correctly. Fixed in option tables and "split" sections. The
Snowflake "greater of `partition_num` or job parallelism" tip described logic
that does not exist (`FixedChunkSplitter` uses `partition_num` only) and was
reworded (en + zh).
8. **DuckDB source `partition_lower_bound` / `partition_upper_bound` typed
`BigDecimal`** while `JdbcSourceOptions.java:138-151` declares `stringType()`.
Fixed in tables and sub-headings.
9. **DuckDB sink `database` default shown as `main`** while
`JdbcSinkOptions.java:31` has `noDefaultValue()`. Fixed to `-`.
10. **DuckDB sink (en) `schema_save_mode` omitted the supported `IGNORE`
value** (`SchemaSaveMode.java:32`). Added.
11. **S3-Redshift `file_format_type` default shown as `"text"`** while
`FileBaseSinkOptions.java:197-201` defaults to `FileFormat.CSV`. Fixed (en +
zh).
12. **Databend `database` claimed to default to the database name parsed
from the URL** — no URL parsing exists; the source falls back to the literal
`default` (`DatabendSourceFactory.java:88`) and the sink applies no fallback
(`DatabendSinkConfig.java:64`). Both descriptions corrected (en + zh, source +
sink).
13. **`database`/`table` sink rows claimed "mutually exclusive with `query`
and has a higher priority"** in DuckDB, Kingbase, Mysql, Oracle, PostgreSql,
Redshift, SqlServer and Vertica sink docs, contradicting the sibling `query`
row and the code: the options are conditional on `generate_sink_sql`
(`JdbcSinkFactory.java:245-246`). Reworded everywhere (en + zh).
14. **StarRocks sink carried the same stale JDBC-template sentences**
("auto-generate sql", "mutually exclusive with `query`") although the connector
has neither option; `StarRocksSinkFactory.java:97-98` falls back to the
upstream table name when `table` is blank. Section rewritten (en + zh, the zh
copy also fixed a "具具有" typo).
15. **Type-mapping fixes against the dialect converters**: DB2 source/sink
(en + zh): `XML` → STRING (`DB2TypeConverter.java:189-193`),
`BINARY`/`VARBINARY` → BYTES, only `ROWID` unsupported. Vertica sink (en + zh):
`BIT` (any width) → BOOLEAN, `INT UNSIGNED` only → BIGINT, `BIT(n)` never BYTES
(`VerticaTypeMapper.java:99-114`), plus a `VARBINAR` typo. HiveJdbc (en + zh):
`TINYINT` → TINYINT, not SHORT (`HiveTypeMapper.java:74-77`). Oracle sink (en +
zh): `INTEGER` → DECIMAL(38,0) and `DATE` → TIMESTAMP, matching
`OracleTypeConverter` and the Oracle source doc.
### ClickHouse family (`docs/{en,zh}/connectors/sink/`)
16. **ClickhouseFile `key_path` default shown as `/tmp/id_rsa`** while
`ClickhouseFileSinkOptions` declares `noDefaultValue()` (`RsyncFileTransfer`
explicitly handles null). Fixed to `-`.
17. **Clickhouse sink and ClickhouseFile sink omitted accepted options**:
`server_time_zone` (in both factories' `optionRule()`) and
`multi_table_sink_replica` / `clickhouse.config` rows added with code-accurate
defaults.
### Sink option-table consistency (`multi_table_sink_replica` and others)
18. **`multi_table_sink_replica` (default 1,
`SinkConnectorCommonOptions.java:31-34`) missing from Hudi, Qdrant and Zendesk
sink tables** (all three factories include it in `optionRule()`); **default
shown as `-` instead of 1 in Iceberg and BigQuery sink tables**. Fixed in en +
zh.
19. **Hbase sink `ttl` option undocumented** although it is defined
(`HbaseSinkOptions.java:80-84`) and applied per cell at write time
(`HbaseSinkWriter`). Row added (en + zh).
20. **HugeGraph sink `allow_cascade_delete_unmapped_edges` undocumented**
(defined and in `optionRule()`; its sibling `delete_vertex_with_edges` is
documented). Row added (en + zh).
21. **zh Hudi sink missing content present in en**: the multi-table
flatten/`record_key_fields` notes and the "S3 Storage" example section —
translated and added.
## Areas / files updated
66 files under `docs/en/connectors/` and `docs/zh/connectors/` (source +
sink CDC, messaging, JDBC family, file/lake, ClickHouse, vector/SaaS sinks).
## Both English and Chinese docs checked?
Yes — every fix above was applied to the English and Chinese docs in
lockstep; zh-only gaps (Hudi notes/S3 section) were filled from the English
content.
## Duplicate-PR check (last 7 days)
Checked open/recent doc PRs before starting: **#12347** (file-connector
`field_delimiter`, Kingbase/PostgreSQL sharding threshold, Doris
`enable-delete`, OneSignal `format`, LocalFile/Hive tables, faq/developer
links, zh Splunk), **#12378** (doc moves + feature-checklist sync), **#12409**
(Http-Linear, IoTDBv2 changelog, Mem0 options, zh sync for
HdfsFile/S3File/OssFile/SftpFile/ObsFile/Http/Prometheus/AmazonSqs/SqlServer-CDC/GraphQL/InfluxDB),
**#12423** (transforms, Zeta engine pages,
Maxcompute/SelectDB/SqlServer-CDC/StarRocks/Paimon/DynamoDB/MySQL-CDC skip-rows
defaults, zh Doris/rest-api-v2) and **#12427** (JDBC/Kingbase/PostgreSQL
`split.sample-sharding.threshold`) were reviewed file-by-file — none of the
issues or rows touched by this PR overlap them. This PR intentionally does not
touch PostgreSQL-CDC (open audit #12359) or MongoDB-CDC base-split options
(runtime never reads them).
## How the change was verified
- Every changed row was cross-checked against the connector source (option
keys, `defaultValue()`/`noDefaultValue()`, `optionRule()` required/conditional
wiring, dialect type converters, runtime fallbacks) — cited above per item.
- Scripted structural checks over all 66 changed files: markdown table
column-count consistency, balanced code fences, and resolution of every
relative link — all pass.
- No docs site build exists in this repository (the Docusaurus toolchain
lives in the separate seatunnel-website repo) and the PR contains no code
changes, so no Maven build was run; the checks above are the doc-scoped
equivalents.
--
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]
