zhangshenghang opened a new pull request, #13089:
URL: https://github.com/apache/seatunnel/pull/13089
## Purpose of this PR
This PR is a documentation-only change that fixes real documentation issues
found by auditing connector docs against the actual source code on `dev`. I
confirm that I am contributing to **SeaTunnel**.
## What documentation issues were found
Issues were verified line-by-line against connector code before editing:
1. **`dag-parsing.mode` documented a non-existent enum value**
(`source-common-options.md`, en+zh). Docs said `MULTIPLEXING`, but
`ParsingMode` only defines `SINGLENESS`, `SHARDING`, and the deprecated
`MULTIPLEX`. Setting the documented value fails enum parsing at job submission.
Also, the deprecated `MULTIPLEX` description was wrong (it means one source
with separate sinks, not one source and one sink).
2. **DataHub sink recommended an unsupported placeholder** (`Datahub.md`,
en+zh). Docs told users to use `${table}` and called `${table_name}` a
"deprecated alias" — exactly backwards. `TablePlaceholder` has no `${table}`;
following the docs, the literal string `${table}` reaches the DataHub client
and the job fails. Fixed all occurrences (description, `topic` section,
multi-table example, FAQ) and added `multi_table_sink_replica` to the option
table.
3. **File connectors: wrong format-scope claims** (`LocalFile.md`,
`HdfsFile.md`, source+sink, en+zh). `null_format` also applies to `csv` reads,
not only `text` (used by `CsvReadStrategy`); HdfsFile `skip_header_row_number`
also applies to Excel (`ExcelReadStrategy` honors it), not only txt/csv;
HdfsFile sink `field_delimiter`/`row_delimiter` descriptions contradicted
themselves and the writers.
4. **File sink options missing from docs** (`LocalFile.md`/`HdfsFile.md`
sink, en+zh). `date_format` / `datetime_format` / `time_format` (registered in
both sink factories, used by text/csv/excel/xml writers) and
`multi_table_sink_replica` (LocalFile sink) were absent; HdfsFile source lacked
`excel_use_header_line` and the `markdown_rag_metadata_enabled` /
`pdf_rag_metadata_enabled` table rows (referenced only in prose).
5. **Hive source `table_list` inheritance claim was wrong** (`Hive.md`,
en+zh). Entries are parsed as standalone configs (`ReadonlyConfig::fromMap`)
and do NOT inherit root-level options; `metastore_uri` etc. must be repeated
per entry. Also documented the missing `null_format` and
`parse_partition_from_path` options, noted that regex discovery (`use_regex`)
requires a reachable metastore, and added `${current_timestamp}` to the sink
`save_mode_create_template` variable list (`HiveTableTemplateUtils` substitutes
it).
6. **Iceberg source `table_list` per-item keys undocumented** (`Iceberg.md`,
en+zh). Items are deserialized by Jackson with camelCase field names
(`startSnapshotId`, `streamScanStrategy`, `splitSize`, `splitLookback`,
`splitOpenFileCost`, ...); copying the snake_case root names fails with
unknown-property errors. Added a per-item key table in both languages.
7. **Chinese Iceberg docs were incomplete/mixed-language** (`zh
sink/`+`source/Iceberg.md`). Added the missing "Glue Catalog" example section
(parity with en) and replaced English `yes`/`no` cells with `是`/`否`.
8. **MongoDB sink type mapping claimed `STRING -> ObjectId`** (`MongoDB.md`,
en+zh). No sink code path produces an `ObjectId` (`RowDataToBsonConverters`
only emits `BsonString`); removed the row and documented the actual behavior.
## What was changed
- Documentation only — 21 markdown files (11 topics × en + zh), 162
insertions / 62 deletions. No code, config, or build files touched.
## Which areas/files were updated
- `docs/{en,zh}/connectors/source/{LocalFile,HdfsFile,Hive,Iceberg}.md`
-
`docs/{en,zh}/connectors/sink/{LocalFile,HdfsFile,Hive,Iceberg,MongoDB,Datahub}.md`
- `docs/{en,zh}/connectors/common-options/source-common-options.md`
## Were English and Chinese docs both checked?
Yes. Every fix was applied to both language versions; the Chinese Iceberg
pages additionally received the missing Glue Catalog section and consistent
`是`/`否` required-column cells.
## How duplicate PRs from the last 7 days were checked
Listed all open PRs from the last week (`gh pr list --state open`) and
inspected the changed-file lists of my own recent open doc PRs: #13072, #13050,
#12993, #12986, #12971, plus merged #13062/#13019 and the just-merged #11779.
This PR deliberately targets only pages not covered by those PRs (file
connectors, Hive, Iceberg, non-CDC MongoDB, DataHub, source common options).
Overlapping connectors (JDBC, Kafka, MySQL/Oracle/PG/Redis,
Clickhouse/Doris/StarRocks, CDC connectors, cloud file connectors, engine
pages) were intentionally not touched here.
## How the change was verified
- Every changed option name/default/type was cross-checked against the
defining Java classes (`ParsingMode`, `TablePlaceholder`, `FormatOptions`,
`SinkConnectorCommonOptions`, `FileBaseSourceOptions`, `SourceTableConfig`,
`IcebergStreamScanStrategy`, `RowDataToBsonConverters`,
`MultipleTableHiveSourceConfig`, `HiveTableTemplateUtils`, sink factories,
read/write strategies) before editing.
- Ran a script over all 21 changed files: every markdown table row matches
its header's column count and every relative link resolves (all pass).
- Grep-verified no stale references remain (`MULTIPLEXING`, `${table}`
outside the explicit warning notes) and that anchors used in cross-references
exist.
- No full docs site build was run because this repository contains only the
docs sources (no package.json/docusaurus tooling in-repo, no docs CI workflow);
the checks above cover table structure and link integrity.
--
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]
