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]

Reply via email to