zhangshenghang opened a new pull request, #13274:
URL: https://github.com/apache/seatunnel/pull/13274
## Purpose of the pull request
I acknowledge that this contribution is to the **SeaTunnel** project.
This PR fixes real documentation writing errors found by auditing connector
and transform docs against the actual source code on `dev`. All fixes are
backed by code evidence read from the repository; no code, configuration names,
or defaults were changed.
## What documentation issues were found and changed
**Doris sink (`docs/{en,zh}/connectors/sink/Doris.md`)**
- The "Timer flush on Zeta" example and the FAQ "How does exactly-once work"
example were missing the required `doris.config` option. `DorisSinkFactory`
declares `doris.config` as required and the row serializer fails at runtime
without a `format` key (`DorisSinkFactory.optionRule()`,
`SeaTunnelRowSerializerFactory`), which also contradicted the FAQ itself
("there is no default and the job fails to start without it"). Added
`doris.config { format = "json" read_json_by_line = "true" }` to both examples
in EN and ZH.
- EN option table described `${database_name}` as "the upstream table name";
it actually substitutes the upstream **database** name (`SaveModePlaceHolder`).
Fixed the description (ZH already said 数据库名称).
- EN FAQ claimed `case_sensitive = false` folds both `database` and `table`
names to lowercase; the code only folds the **table** (and column) names while
the database keeps its case (`DorisStreamLoad`). Corrected the FAQ (ZH made no
such claim).
**Doris source (`docs/{en,zh}/connectors/source/Doris.md`)**
- `doris.request.read.timeout.ms` was described as applying only to requests
sent to Doris BE, but the same option drives the socket timeout on FE
`_query_plan` requests too (`RestService.send`) as well as BE scan requests
(`BackendClient`). Updated to "FE or BE", matching the sibling connect-timeout
row, in EN and ZH.
**StarRocks sink (`docs/{en,zh}/connectors/sink/StarRocks.md`)**
- The EN "Simple" example and the EN "Support write cdc changelog event"
example were missing the required `base-url` option
(`StarRocksSinkFactory.optionRule()` requires both `base-url` and `nodeUrls`),
so the examples would fail option validation. Added `base-url` to both examples
(ZH already had it).
- EN and ZH FAQ claimed `nodeUrls`/`base-url` are "required when automatic
table creation is enabled"; both are required unconditionally per the option
rule. Updated both languages.
**LLM transform (`docs/{en,zh}/transforms/llm.md`)**
- The `api_key` table row said it is required for `QIANFAN` (plus
`secret_key`/`oauth_path`), but the runtime throws `Unsupported model provider:
QIANFAN` (`LLMTransform`), and the provider list plus the `api_key` section on
the same page correctly omit QIANFAN. Removed the misleading QIANFAN mention
from the table in EN and ZH so all three places agree.
**Embedding transform (`docs/{en,zh}/transforms/embedding.md`)**
- The `api_key` section said the option is "not required for other
providers" than AMAZON/OPENAI/DOUBAO/QIANFAN, contradicting the option table on
the same page which (correctly, per `ZhipuModel` reading `api_key` at runtime)
says ZHIPU needs it. Reworded the section in EN and ZH.
**Calcite transform (`docs/{en,zh}/transforms/calcite.md`)**
- The option table marked `sql` unconditionally required, but
`CalciteTransformFactory` only requires the global `sql` when `table_transform`
is not configured; with `table_transform` entries each entry must carry its own
`sql` and the global `sql` becomes optional (`TableTransformRuleValidator`).
Changed Required to "conditional" and documented the exact rule in EN and ZH.
**TDengine source (`docs/{en,zh}/connectors/source/TDengine.md`)**
- Docs claimed the order of `read_columns` decides the output field order.
The code only filters by `read_columns` while iterating `desc <db>.<stable>`;
output order follows the TDengine super table column order (timestamp first,
normal columns in table-definition order, TAGS last) and is never re-ordered
(`TDengineSource`, `TDengineSourceSplitEnumerator`). Rewrote both the
`read_columns` section and the "Output Schema" section in EN and ZH.
**Milvus source (`docs/zh/connectors/source/Milvus.md`)**
- The ZH "限制读取速度" section said lowering `rate_limit` avoids exceeding "the
cluster's gRPC message size limit"; `rate_limit` actually sets the
per-collection query-QPS quota (`collection.queryRate.max.qps` in
`MilvusSourceReader`). Aligned the ZH rationale with the EN page and the code.
## Which areas/files were updated
15 files, all under `docs/`:
- `docs/en/connectors/sink/{Doris,StarRocks}.md`,
`docs/zh/connectors/sink/{Doris,StarRocks}.md`
- `docs/en/connectors/source/{Doris,TDengine}.md`,
`docs/zh/connectors/source/{Doris,TDengine,Milvus}.md`
- `docs/{en,zh}/transforms/{calcite,embedding,llm}.md`
## Were English and Chinese docs both checked?
Yes. Every issue was checked in both language trees. Fixes were applied to
both where the problem existed in both (Doris sink `doris.config` examples,
Doris source timeout, StarRocks FAQ, llm/embedding/calcite/TDengine), and only
where it existed (EN-only: Doris `${database_name}`, `case_sensitive` FAQ,
StarRocks missing `base-url` examples; ZH-only: Milvus throttle rationale).
## Duplicate PR check (last 7 days)
Checked all open PRs from the last 7 days by list and by touched files
(`#13258`, `#13234`, `#13216`, `#13204`, `#13193`, `#13163`, `#13149`,
`#13135`, `#13121`, `#13097`, `#13089`, plus current open PRs
`#13272`–`#13209`): none of them modify the 15 files fixed here, except:
- `#13257` adds a `case_sensitive` row to the Doris **source** option tables
in `docs/{en,zh}/connectors/source/Doris.md` — different section and different
content from the `doris.request.read.timeout.ms` row fixed here; no textual
conflict.
- `#13270` rewrites `transforms/text-chunk.md`, untouched by this PR.
No PR covers the Doris/StarRocks examples, TDengine ordering claims, Milvus
ZH rationale, or the llm/embedding/calcite option semantics fixed here.
## How the change was verified
- Each documented claim was verified against the connector/transform source
before editing (factory `optionRule()` required/optional sets, `Option`
defaults, runtime code paths cited above).
- A verification script was run over all 15 changed files: code fences
balanced and every relative link/anchor target resolves (15/15 OK).
- No full website build was run: the SeaTunnel website is built in the
separate `apache/seatunnel-website` repository (docs are synced there after
merge, see `.github/workflows/backend.yml` "Build website"), so there is no
in-repo docs build to execute. Markdown structure and link integrity were
verified locally instead.
- This is a docs-only change; no build or tests are affected.
--
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]