zhangshenghang opened a new pull request, #12609:
URL: https://github.com/apache/seatunnel/pull/12609
## Purpose of this PR
This PR fixes a batch of real documentation inaccuracies found by
cross-checking the docs against the actual source code. All fixes are
behavior/config descriptions that contradicted the code, misleading examples,
or broken/missing content. 26 doc files are updated (13 issue groups, each
fixed in both `docs/en` and `docs/zh` where both versions exist).
## Issues found & changes made
### Transform docs (`docs/{en,zh}/transforms/`)
1. **llm.md** — The doc claimed a custom `output_column_name` colliding with
an existing field is silently replaced with `llm_output`. The code
(`LLMTransform#getOutputColumn`) actually throws `IllegalArgumentException("llm
inference field name %s already exists")`. Rewrote the description in EN and ZH.
2. **llm.md** — Documented that `api_key` is not used when `model_provider`
is `CUSTOM` (verified against `LLMTransform#open`), and that
`custom_response_parse` / `custom_request_headers` / `custom_request_body` are
only read from inside the `custom_config` block (top-level settings are
silently ignored).
3. **embedding.md** — EN table showed the wrong default for `dimension` (`-`
instead of `2048`, `ModelTransformConfig#DIMENSION`) and contained a "TThe"
typo; the ZH table was already correct. Also documented the per-provider
requirements for `api_key`/`secret_key` (e.g. `secret_key` is only required by
`AMAZON` and `QIANFAN`; neither is used by `CUSTOM`).
4. **filter-rowkind.md** — `include_kinds`/`exclude_kinds` were marked as
required `yes`, but `FilterRowKindTransformFactory#optionRule` registers them
as optional and mutually exclusive (exactly one must be set; both or neither
fails validation). Fixed the tables and added an explicit note in EN and ZH.
Also fixed the misspelled plugin name `FilterRowKink` → `FilterRowKind`, and
the mistranslated ZH heading `## 操作` → `## 属性`.
5. **python.md** — The doc framed the absolute-path requirement for
`python_executable` as a production "preference". `PythonProcessWorker` rejects
any non-default non-absolute value at runtime
(`PYTHON_EXECUTABLE_NOT_ALLOWED`); restated it as a hard requirement in EN and
ZH.
6. **regexextract.md** — Added the missing standard "common options" section
(the factory registers the common multi-table options), matching all sibling
transform docs.
7. **sql.md** — `plugin_input`/`plugin_output` were marked required `yes`,
but `SQLTransform` falls back to the input catalog table name when they are
absent; changed to `no` with a fallback note.
8. **calcite.md** — `row_error_handle_way = ROUTE_TO_TABLE` was documented
as routing error rows to an error table, but the Calcite transform never
implements error-table routing (only `SKIP` is honored in
`AbstractSeaTunnelTransform`; routing exists only in DataValidator). Annotated
it as not implemented / behaving like `FAIL` in EN and ZH.
9. **sql-functions.md** — Added the undocumented `ATAN2(numeric, numeric)`
and `MAP(key, value, ...)` functions (both exist in `ZetaSQLFunction`), and
added `DATETIME`, `TIMESTAMP_TZ`, `BINARY` to the CAST/TRY_CAST supported-type
lists to match `CastFunction`. Fixed in EN and ZH.
10. **field-mapper.md** — Changelog said "Add Copy Transform Connector"
(copy-paste from copy.md); changed to FieldMapper in EN and ZH.
### Configuration / general docs
(`docs/{en,zh}/introduction/configuration/`, `faq.md`)
11. **JobEnvConfig.md** — Claimed the Zeta `STREAMING` default of
`checkpoint.interval` is 30000 ms; the engine default is 300000 ms
(`ServerConfigOptions#CHECKPOINT_INTERVAL`). 30000 is the *timeout* default.
Fixed in EN and ZH.
12. **config-encryption-decryption.md (zh)** — Example listed `config.f1` in
`shade.options` but the config block defines `config1.f1` (the EN doc was
already correct); with `config.f1` the shown encrypted output could never
happen.
13. **sink-options-placeholders.md** — Removed `${comment}` from the
supported sink-options placeholder list; `TablePlaceholderProcessor` only
replaces the 9 placeholders defined in `TablePlaceholder`, and `${comment}`
exists only in the separate save-mode DDL template feature. Fixed in EN and ZH.
14. **schema-evolution.md (zh)** — StarRocks sink example used `url =
"jdbc:mysql://..."`, but the connector option is `base-url` (EN doc was already
correct).
15. **faq.md** — Example command used `-m local[2]`, which is invalid for
Zeta (`MasterType.valueOf` only accepts `local`/`cluster`/`remote`/...; `[2]`
is Spark syntax). Changed to `-m local` in EN and ZH.
## Were both English and Chinese docs checked?
Yes. Every fix was applied to both `docs/en` and `docs/zh` unless the issue
existed only in one language version (embedding.md `dimension` default,
`config1.f1`, `base-url` were already correct in one of the two).
## Duplicate check (last 7 days)
Checked all PRs opened/merged in the last week (mine: #12602, #12570,
#12553, #12499, #12487, #12476, #12459, #12447; others: #12514, #12505,
#12488). None of them touch the files or issues in this PR: my recent PRs
covered connector/format/file-connector option tables, a different set of
transform pages (copy, data-validator, field-rename, filter, jsonpath,
metadata, table-*) and Zeta engine pages; this PR covers the remaining
transform pages (llm, embedding, field-mapper, filter-rowkind, python,
regexextract, sql, calcite, sql-functions) and the introduction/configuration
pages.
## How the changes were verified
- Every option name, default value and behavior claim was verified against
the source before editing (e.g. `ServerConfigOptions#CHECKPOINT_INTERVAL`,
`LLMTransform`, `FilterRowKindTransformFactory#optionRule`,
`ModelTransformConfig#DIMENSION`, `TablePlaceholder`, `CastFunction`,
`MasterType`).
- Ran a script over all 26 changed files: markdown table column-consistency
check and relative-link target check — all passed.
- The repo has no dedicated docs lint workflow (docs site is built
separately); `./mvnw verify` was not run because this PR contains no code
changes.
--
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]
