zhangshenghang opened a new pull request, #13193:
URL: https://github.com/apache/seatunnel/pull/13193

   ### Purpose of this pull request
   
   Yes — I acknowledge that I am contributing to **Apache SeaTunnel**.
   
   This PR fixes real documentation inaccuracies found by auditing `docs/en` 
and `docs/zh` against the source code on the latest `dev` branch 
(`b7ef4936fe`). Every change below is backed by a specific code location. There 
is no tracking issue; these are documentation accuracy fixes discovered during 
the audit.
   
   Scope: **42 documentation files** (20 en + 22 zh), +168 / −165 lines, all 
content fixes (no formatting-only or punctuation-only changes).
   
   ### What documentation issues were found and what was changed
   
   **Wrong configuration keys / broken example configs**
   
   - `source/Http.md` (en+zh): the binary-download example configured 
`LocalFile` with `file_format = "binary"`; the file sink key is 
`file_format_type` (`FileBaseSinkOptions.java:198`). Fixed the example.
   - `sink/DuckDB.md` (en+zh): the FakeSource example used `row_num = 1000`; 
the option is `row.num` (`FakeSourceOptions.java:36`), so `row_num` was 
silently ignored. Fixed.
   - `introduction/concepts/schema-feature.md` (en+zh): `constraintType` was 
documented as optional with default `KEY`, and the example used `constraintType 
= KEY`. `ConstraintKey.ConstraintType` has no `KEY` constant 
(`ConstraintKey.java:81-86`: `INDEX_KEY`, `UNIQUE_KEY`, `FOREIGN_KEY`, 
`VECTOR_INDEX_KEY`), and the parser throws when the key is missing 
(`ReadonlyConfigParser.java:172-179`, `orElseThrow`). The example now uses 
`INDEX_KEY`; the row is now required with no default and links to the 
supported-values table.
   - `zh/connectors/sink/Greenplum.md`: removed a zh-only "CDC 数据流写入" example 
that does not exist on the en page, contradicts the page's own unchecked CDC 
feature box, and uses a non-existent MySQL-CDC key `table-list` (the factory 
requires `table-names` or `table-pattern`: 
`MySqlIncrementalSourceFactory.java:74-76`), so the example could not pass 
option validation.
   
   **Option behaviour that differs from the code**
   
   - `sink/Pulsar.md` (en+zh): `pulsar.config` was described as producer client 
tuning (timeouts, batching, compression) with `sendTimeoutMs` / 
`batchingMaxMessages` examples. The map is passed to 
`ProducerBuilder.properties(...)` (`PulsarConfigUtil.java:189-194`), i.e. 
producer metadata, not client configuration, so those examples had no effect. 
Corrected the table row and section, removed the no-op entry from the basic 
example, and replaced the tuning example with a metadata example.
   - `source/MongoDB.md` (en+zh): claimed a restarted job "resumes from the 
last committed split instead of rescanning the whole collection". On restore 
the enumerator keeps the checkpointed pending splits and then `run()` re-runs 
the split strategy over the whole collection (`MongodbSplitEnumerator.java:79`, 
`pendingSplits.addAll(strategy.split())`; 
`SourceSplitEnumeratorTask.java:199,341`), and a split has no in-range read 
position. Rewrote the paragraph to describe the real behaviour and the 
duplicate risk.
   - `source/PostgreSQL.md`, `source/DuckDB.md` (en+zh): `partition_column` 
said "only support numeric type primary key", contradicting both the same 
page's "Supported split data type" list and the splitter, which handles string 
(`FixedChunkSplitter.java:81`) and date (`FixedChunkSplitter.java:551`) split 
keys. The row now points to the supported split types.
   - `sink/Mysql.md`, `sink/Oracle.md`, `sink/DuckDB.md` (en+zh): the sink 
"Tips" said sink concurrency depends on `partition_column`, which is a 
source-only option (`JdbcSourceOptions.java:136`). Replaced with the wording 
already used on `sink/PostgreSql.md`.
   - `engines/zeta/engine-jar-storage-mode.md` (en+zh): default of 
`connector-jar-storage-path` was shown as `" "` (a space); the default is the 
empty string (`ServerConfigOptions.java:479-483`), and an empty path falls back 
to `SEATUNNEL_HOME` (`AbstractConnectorJarStorageStrategy.java:124-135`). Fixed 
the default and documented the fallback.
   
   **Feature claims that do not match the implementation**
   
   - `source/Firebase.md` (en+zh): "Column Projection" was checked, but 
`FirebaseSource` does not implement `SupportColumnProjection` 
(`FirebaseSource.java:33`) and reads whole JSON nodes before mapping them to 
the schema. Unchecked.
   - `source/Typesense.md` (en+zh): "Parallelism" was checked, but the 
enumerator always creates exactly one split 
(`TypesenseSourceSplitEnumerator.java:145-155`), which the page itself notes 
for `hosts`. Unchecked and added a one-line explanation (same convention as 
`source/Qdrant.md`).
   - `sink/DuckDB.md` (en+zh): "timer flush" was unchecked, although the 
generic JDBC sink writer registers the timer flush action for every dialect 
(`JdbcSinkWriter.java:160`) and all other JDBC sink pages check it. Checked it 
and moved it back into the feature list (it was placed after a note block).
   
   **Data type mapping tables**
   
   - `sink/OceanBase.md` (en+zh), MySQL mode — compared with 
`OceanBaseMySqlTypeConverter`: `INT UNSIGNED` was listed under `BOOLEAN` (it 
maps to `BIGINT`, line 166); `TINYINT`/`TINYINT UNSIGNED`/`SMALLINT` were 
listed as `INT` (they map to TINYINT/SMALLINT, lines 147-156); `TINYINT(1)` and 
`ENUM` were missing; `TIMESTAMP` maps to `TIMESTAMP_TZ`, not `TIMESTAMP` (lines 
295-300); `GEOMETRY` maps to `BYTES`, not "Not supported yet" (line 285). 
Oracle mode — `OceanBaseOracleDialect extends OracleDialect`, so 
`OracleTypeConverter` applies: `Number(p), p > 18` never maps to 
`DECIMAL(38,18)`, `DATE` maps to `TIMESTAMP`, and `TIMESTAMP WITH LOCAL TIME 
ZONE` maps to `TIMESTAMP_TZ` (lines 142-178, 252-267). Both tables now match 
the converters and the existing `source/OceanBase.md` tables.
   - `source/DB2.md` (en+zh) and `sink/DB2.md` (en+zh): SeaTunnel types were 
written as Java names `SHORT` / `INTEGER` / `LONG`; changed to the SeaTunnel 
type names `SMALLINT` / `INT` / `BIGINT` (`DB2TypeConverter.java:114-127`), 
matching the rest of the table and the schema type list.
   - `source/IoTDB.md` (en+zh): listed an IoTDB `STRING` → `STRING` mapping. 
The source deserializer only handles 
`INT32`/`INT64`/`FLOAT`/`DOUBLE`/`TEXT`/`BOOLEAN` and throws for anything else 
(`DefaultSeaTunnelRowDeserializer.java:68-97`), and the bundled 0.13.x client 
(`connector-iotdb/pom.xml:33`) has no `STRING` data type. Removed the row and 
documented that IoTDB 1.3 `STRING`/`BLOB`/`DATE`/`TIMESTAMP` columns are not 
supported.
   - `sink/Assert.md` (en+zh): the types of `field_name` and `field_type` were 
swapped — `field_name` is read with `getString` and `field_type` accepts a 
string or an object (`AssertRuleParser.java:55-83`), as the page's own 
`field_type [string | ConfigMap]` section says. `row_rules.rule_value` is 
numeric (`RowRule.java:32`, `Double ruleValue`), not string.
   - Typo `VARBINAR` → `VARBINARY` in `sink/Mysql.md` and `source/OceanBase.md` 
(en+zh).
   
   **Getting started / FAQ**
   
   - `getting-started/docker/docker.md` (en+zh): the Dockerfile listing was an 
outdated single-stage version (with a trailing space after a line-continuation 
backslash). Replaced it with the actual two-stage 
`seatunnel-dist/src/main/docker/Dockerfile` (builder stage + final stage that 
installs `python3`).
   - `zh/getting-started/locally/quick-start-seatunnel-engine.md`: the Windows 
example used `cd apache-seatunnel-3.0.0` while the en page and the current 
version use `3.1.0`. Aligned with en.
   - `connectors/connector-faq.md` (en+zh): the "Tips for Finding Answers" list 
was a merge artifact numbered 1–5 then 2–4, with the General FAQ and "Still 
stuck?" items duplicated. Merged into one 1–6 list without losing any content.
   
   ### Which areas/files were updated
   
   42 files, en and zh in pairs (except the two zh-only fixes):
   
   - Connectors (source): `Http`, `Firebase`, `MongoDB`, `Typesense`, `IoTDB`, 
`DB2`, `DuckDB`, `PostgreSQL`, `OceanBase`
   - Connectors (sink): `Pulsar`, `DuckDB`, `Mysql`, `Oracle`, `OceanBase`, 
`DB2`, `Assert`, `Greenplum` (zh only)
   - `connectors/connector-faq.md`, `introduction/concepts/schema-feature.md`, 
`engines/zeta/engine-jar-storage-mode.md`, `getting-started/docker/docker.md`, 
`getting-started/locally/quick-start-seatunnel-engine.md` (zh only)
   
   ### Were both English and Chinese docs checked?
   
   Yes. Every page was checked in both languages and every factual fix was 
applied to both. Two issues existed only on the zh side (the zh-only Greenplum 
CDC example and the outdated version in the zh quick start); they were fixed on 
the zh side to match en and the code.
   
   ### Duplicate PR check (last 7 days)
   
   - Listed all apache/seatunnel PRs created since 2026-11-02 (61 PRs, open and 
closed) and collected every `docs/` file they touch; none of them touches any 
of the 42 files in this PR.
   - Also listed all currently open PRs (any age). Some older open code PRs 
touch a few of the same files (for example #12853 MySQL/OceanBase DECIMAL rows, 
#13055 IoTDB `zone_id`, the DuckDB PRs 
#12498/#12506/#12592/#12508/#12557/#12610, #10431, #11307, #11493, #11633, 
#10988, #11681, #13020). I checked their patches: none of them fixes the issues 
fixed here, and the edited lines do not overlap (for example #12853 only 
rewrites the DECIMAL rows, which this PR leaves unchanged).
   - To avoid conflicts, I did not fix the same `VARBINAR` typo in 
`source/Mysql.md`, `source/Vertica.md` and `source/MySQL-CDC.md`, because those 
files are being edited by open docs PRs #11782, #11713, #12993 and #13097.
   
   ### Does this PR introduce _any_ user-facing change?
   
   Documentation only. No code, configuration option, default value, or API is 
changed.
   
   ### How was this patch tested?
   
   - Verified each fix against the referenced source code (option definitions, 
factories, converters, enumerators and readers) on the current `dev` branch.
   - `[email protected] -c .dlc.json` (the CI dead-link job) on all 42 
changed files: all passed.
   - A local check of relative links and in-page anchors on all changed files, 
including the new anchors `#parallel-reader`, `#并行读取器`, 
`#what-constrainttype-supported-at-now` and `#目前支持哪些约束类型`: no broken links.
   - `git diff --check`: no whitespace errors.
   - `./mvnw -q -o spotless:check`: passed.
   - Not run: `./mvnw -DskipTests verify` and the unit tests. This PR changes 
only Markdown, which neither of them covers, and a full multi-module build is 
expensive. The Docusaurus site build lives in the separate `seatunnel-website` 
repository, so it was not run here either.
   
   ### Check list
   
   * [x] No new Jar binary package is added.
   * [x] Documentation updated (this PR is documentation-only).
   * [x] No incompatible change, so `incompatible-changes.md` is not updated.
   * [x] Not a connector code contribution.
   


-- 
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]

Reply via email to