zhangshenghang opened a new pull request, #13163:
URL: https://github.com/apache/seatunnel/pull/13163
### Purpose
This PR fixes real documentation inaccuracies found by auditing `docs/en`
and `docs/zh` against the source code on the current `dev` branch. Every change
is backed by a specific code location listed below. 36 documentation files
changed (+161/−31 lines of real content), meeting the 10+ file scope
requirement.
I acknowledge that I am contributing to Apache SeaTunnel.
### Issues found and changes made
**JDBC dialect docs (Oracle / SqlServer / Redshift / HiveJdbc, en+zh)**
- `partition_column` claimed only numeric (primary-key) columns are
supported. The splitter actually accepts
TINYINT/SMALLINT/INT/BIGINT/DOUBLE/FLOAT/DECIMAL/STRING/DATE, and any such
column (not necessarily a primary key):
`seatunnel-connectors-v2/connector-jdbc/.../source/ChunkSplitter.java:438-455`
(`isSupportSplitColumn`) and the split-key fallback at lines 384-423. Rewrote
the row on all 8 pages.
- Oracle page: `DATE`/`TIMESTAMP` columns map to SeaTunnel `TIMESTAMP`
(`OracleTypeConverter.java:252-258`), so despite `DATE` passing
`isSupportSplitColumn`, no Oracle column maps to the split-supported `DATE`
type. Removed the misleading "Date" bullet from the "Supported split data type"
list and documented this explicitly (en+zh).
- Oracle "Streaming With Incremental ID Range" example put `?` placeholders
in `query`; user-query placeholders are never bound (the splitter wraps the
query and binds exactly the 2 split-range parameters):
`FixedChunkSplitter.java:441-469`. Changed the example to `query = "SELECT *
FROM ORDERS"` (en+zh).
- Oracle streaming section said the read range is half-open `[lower,
upper)`; the split SQL is `>= ? AND <= ?` (`FixedChunkSplitter.java:441`), so
corrected to the closed interval `[lower, upper]` (en+zh).
- zh HiveJdbc type table listed a `DATETIME -> TIMESTAMP` mapping that does
not exist in `HiveTypeMapper.java:73-115` (no `DATETIME` case; it falls to
`default` and throws `convertToSeaTunnelTypeError`). Removed the row to match
the en page.
**Transform docs — missing multi-table options (9 transforms, en+zh)**
`Replace`, `RowKindExtractor`, `FieldRename`, `TableRename`, `TableFilter`,
`DefineSinkType`, `DynamicCompile`, `TextChunk`, `DataValidator` pages did not
document the multi-table options their factories register (sibling pages
`filter.md`/`split.md` already document them):
- `table_match_regex` (string, default `.*`), `table_transform` (array),
`rule_match_mode` (`FIRST_MATCH` default / `ALL_MATCH`). Evidence: each
factory's `optionRule()` (e.g. `ReplaceTransformFactory.java:58-68`,
`TextChunkTransformFactory.java:82-94` — TextChunk does not register
`rule_match_mode`, so it was not added there) and
`TransformCommonOptions.java:44-54` for defaults; duplicate-`table_path`
rejection when `rule_match_mode` is unset:
`AbstractMultiCatalogTransform.java:71-73`. Added option-table rows plus a
short description section per page, mirroring the existing `filter.md` style.
**Zeta engine docs**
- `stain-trace.md`: "Extended Stages: 40+ codes" -> 34 (the enum defines
exactly 40 codes, 6 basic + 34 extended: `StainTraceStage.java`); quick-start
`stain-trace-file-base-path` example changed from `/data/seatunnel/traces` to
`/tmp/seatunnel/traces` to match the page's own "View Traces"/analyzer sections
(en+zh).
- `download-seatunnel.md`: "plugin.properties" -> the real `plugin_config`
file (`bin/install-plugin.sh:282` reads `config/plugin_config`; no
`plugin.properties` exists), and `plugins-mapping.properties` ->
`plugin-mapping.properties`
(`seatunnel-dist/src/main/assembly/assembly-seatunnel-bin.xml:144-148` ships
the root `plugin-mapping.properties` to `/connectors`) (en+zh).
- `benchmark.md`: "Java 8 and Java 11" -> "Java 11 and Java 17" for the
comparison workflow (`.github/workflows/benchmarks.yml:74` matrix `['11',
'17']`) (en+zh).
**Connector sink docs**
- `Aerospike.md`: `data_format` bullets claimed `map`/`string`/`kv` pack
"all non-key fields"; the writer iterates all selected fields with no key
exclusion (`AerospikeSinkWriter.java:98-130`,
`AerospikeTypeConverter.java:46-55`) — contradicted the page's own Usage Notes.
Now says "the selected fields" (en+zh).
- `GcsFile.md`: sink option table was missing 4 options present in
`GcsFileSinkFactory.optionRule()`: `date_format`, `datetime_format`,
`time_format` (defaults per `FormatOptions.java:27-42`) and
`multi_table_sink_replica` (default 1,
`SinkConnectorCommonOptions.java:30-35`). Added rows (en+zh).
### Which areas/files
36 files: 18 en + 18 zh —
`docs/{en,zh}/connectors/source/{Oracle,SqlServer,Redshift,HiveJdbc}.md`,
`docs/{en,zh}/connectors/sink/{Aerospike,GcsFile}.md`,
`docs/{en,zh}/transforms/{replace,rowkind-extractor,field-rename,table-rename,table-filter,define-sink-type,dynamic-compile,text-chunk,data-validator}.md`,
`docs/{en,zh}/engines/zeta/{stain-trace,download-seatunnel,benchmark}.md`.
### English and Chinese docs
Both were audited and every factual fix was mirrored into the other
language; zh got natural Chinese phrasing. One zh-only issue (HiveJdbc
`DATETIME` type row) was removed on the zh side. One zh-only structural
divergence (GoogleBigtable heading level) was inspected but left unchanged
because the fix would be formatting-only.
### Duplicate PR check
Checked all PRs created or updated in the last 7 days (209 PRs inspected,
including all 379 currently-open PRs' file lists): no open PR touches any of
the 36 files in this PR. The only recent PRs that touched these files are my
own already-merged PRs #12865 (merged 2026-11-03) and #12365 (merged
2026-10-31), both before this branch's base; the partition_column wording this
PR corrects is the text those merged PRs introduced (the "date columns are
supported" claim they left on SqlServer/Redshift/HiveJdbc is refined here for
Oracle based on its type mapping, and their "numeric primary key only" phrasing
remains wrong for the other pages). The `plugin-mapping.properties` typo in
`getting-started/locally/deployment.md` is already fixed by open PR #12971, so
I deliberately excluded that file to avoid overlap.
### Verification
Ran locally:
- Link check used by CI: `markdown-link-check -c .dlc.json` (v3.8.7, same as
`.github/workflows/backend.yml` dead-link job) on all 36 changed files — 0
failures.
- Custom script over the 36 files: relative link targets, in-page/heading
anchors, and MDX-risky syntax in added lines (Docusaurus 2 / MDX 1) — 0
problems.
- Full website build (CI "Build website" job equivalent): synced the branch
docs into a checkout of apache/seatunnel-website with
`tools/documents/sync.sh`, trimmed `versions.json` exactly like the CI job, and
ran `docusaurus build` — en and zh-CN both compile successfully; the updated
text was verified present in the generated HTML.
- `./mvnw -q -B spotless:check -Dskip.ui=true` — passed (docs-only change,
no code touched).
- `git diff --check` — no whitespace errors.
Not run: unit tests / `-DskipTests verify` (no Java code changed in this PR).
--
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]