zhangshenghang opened a new pull request, #12813:
URL: https://github.com/apache/seatunnel/pull/12813
## Purpose of this PR
This PR fixes a batch of real documentation inaccuracies found by comparing
connector docs against the actual source code. All findings were verified
against the code before editing; nothing cosmetic was changed for its own sake.
## Issues found and changes made
### TDengine source (`docs/{en,zh}/connectors/source/TDengine.md`)
- The docs claimed the order of `read_columns` decides the output field
order. In fact `TDengineSourceConfig` collects `read_columns` into a `Set`
(order discarded) and `TDengineSource` builds the schema from `desc
<db>.<stable>` metadata order, using `read_columns` only as a filter. Reworded
both docs: the output order always follows the super table definition order
(normal columns first, then TAGS).
### Redis source (`docs/{en,zh}/connectors/source/Redis.md`)
- Docs scoped the `single_field_name` requirement to single-value types
only. The option rule in `RedisSourceFactory` makes it required at the top
level whenever `read_key_enabled = true`, regardless of `data_type` (a hash
config without it fails option validation), while `tables_configs` entries are
not covered by that validation and only single-value types need it at runtime
(`JsonKeyValueMerger` throws for single values without it). Documented the
exact requirement and the multi-table exception; updated the Required column in
the options table.
### Snowflake source & sink
(`docs/{en,zh}/connectors/{source,sink}/Snowflake.md`)
- Type mapping table claimed `GEOGRAPHY/GEOMETRY (WKB or EWKB) → BYTES`
depending on the JDBC URL output format. `SnowflakeTypeConverter` maps them to
`STRING` unconditionally; only `BINARY/VARBINARY` map to `BYTES`. Fixed in all
four docs (sink doc also wrongly listed GEOGRAPHY/GEOMETRY in the BYTES row).
- Removed the `DECIMAL(p, s) with p > 38 → DECIMAL(38, 18)` row: the
converter passes precision/scale through unchanged and never clamps to 38.
- Split `TIMESTAMP_LTZ/TIMESTAMP_TZ` out of the `TIMESTAMP` row: the
converter maps them to `OFFSET_DATE_TIME_TYPE`, i.e. SeaTunnel `TIMESTAMP_TZ`,
not `TIMESTAMP`.
- Added the missing `generate_sink_sql` option (Boolean, default `false`,
`JdbcSinkOptions.GENERATE_SINK_SQL`) to the sink options table — the doc's own
CDC example and several option descriptions depend on it.
### SQL Server CDC (`docs/{en,zh}/connectors/source/SqlServer-CDC.md`)
- `connect.timeout | Duration | 30s` does not exist in code; the connector
reads `connect.timeout.ms` (Long, default `30000`,
`JdbcSourceOptions.CONNECT_TIMEOUT_MS`). Fixed name, type and default in both
languages.
- `server-time-zone` default is not `UTC`; it defaults to
`ZoneId.systemDefault().getId()`. Fixed in both languages.
- `table-names` and `table-pattern` were both marked Required = Yes while
being mutually exclusive (self-contradictory). Changed to "required when the
other is not set", matching the `.exclusive(...)` rule in
`SqlServerIncrementalSourceFactory`.
- Ported three sections present only in the English doc to the Chinese doc:
the initial-snapshot behavior paragraph, "Heartbeat action"
(`debezium.heartbeat.*`), and "Databases with special characters in the name".
### Other CDC connectors
- **Vitess CDC** (`docs/{en,zh}/connectors/source/Vitess-CDC.md`): added the
missing `username` / `password` options (declared in `VitessSourceOptions`,
advertised in the factory rule, consumed for VTGate gRPC auth).
- **DB2 CDC** (`docs/{en,zh}/connectors/source/DB2-CDC.md`): added the
missing `split.allow-sampling` option (Boolean, default `true`; read by
`JdbcSourceConfigFactory` and honored by `AbstractJdbcSourceChunkSplitter`).
- **TiDB CDC** (`docs/{en,zh}/connectors/source/TiDB-CDC.md`): added the
missing `driver` option (`JdbcCommonOptions.DRIVER`, read by
`TiDBCatalogFactory`); both task examples in the doc already set it.
### Others
- **Milvus source zh** (`docs/zh/connectors/source/Milvus.md`): the zh text
said lowering `rate_limit` avoids exceeding the cluster's "gRPC message size
limit"; the code sets `collection.queryRate.max.qps` (a per-collection query
QPS quota). Aligned with the English doc.
- **Sls sink** (`docs/{en,zh}/connectors/sink/Sls.md`): added the missing
`log_group_size` option (Int, default `100`, `SlsSinkOptions.LOG_GROUP_SIZE`),
documented as reserved since the current writer sends one log group per record.
- **Replace transform zh** (`docs/zh/transforms/replace.md`): restored the
lost space character inside the inline code span ("replace the char ` `"),
which made the example impossible to understand.
## Areas updated
20 documentation files across connector sources/sinks, CDC connectors and
one transform, always in matched en/zh pairs (19 files) plus one zh-only parity
fix.
## Both English and Chinese docs checked?
Yes. Every fix was applied to both the English and Chinese doc except: the
Milvus `rate_limit` fix (the English doc was already correct) and the zh
SqlServer-CDC section port (which brings zh up to date with en).
## Duplicate check (last 7 days)
I searched all open PRs touching docs in `apache/seatunnel` created in the
last 7 days (via `gh pr list --search "is:open docs"`):
- #12771 (CDC/InfluxDB/file/IM docs) — overlaps only on
SqlServer-CDC-adjacent CDC files it did not touch (it changed
MongoDB/Oracle/PostgreSQL CDC docs). No file overlap with this PR.
- #12758 (IoTDB/Http/Paimon/SelectDB/Neo4j/Phoenix/jsonpath) — no file
overlap.
- #12730 (Clickhouse/Iceberg/Oss* file family/sql transform) — no file
overlap.
- #12709 (Doris/Jdbc/Kafka/Kudu/Hive/StarRocks/llm/python transforms) — no
file overlap.
- #12784, #12800 (CLI docs / JDBC option declaration code change) — no doc
file overlap.
None of the files or issues fixed here were touched by those PRs.
## Verification
- Every option name/default/type/required-flag change above was verified
against the corresponding source file (`RedisSourceFactory`,
`SnowflakeTypeConverter`, `JdbcSinkOptions`, `JdbcSourceOptions`,
`SqlServerIncrementalSourceFactory`, `VitessSourceOptions`,
`JdbcSourceConfigFactory`, `TiDBCatalogFactory`, `SlsSinkOptions`,
`TDengineSource`, `MilvusSourceReader`).
- Ran a local markdown validation script over all 20 modified files:
code-fence balance, per-table column-count consistency, and resolution of all
relative links — all passed.
- No full site build was run: docs rendering for seatunnel.apache.org lives
in the separate apache/seatunnel-website repository, so the markdown-level
checks above are the applicable verification in this repo.
--
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]
