zhangshenghang opened a new pull request, #12986: URL: https://github.com/apache/seatunnel/pull/12986
## Acknowledgement Yes, I acknowledge that I am contributing to Apache SeaTunnel. ## What documentation issues were found While auditing connector and transform documentation against the actual Java source code on this branch, I found the following real inaccuracies: **JDBC connector (source + sink)** 1. The docs told users to set `dialect = "starrocks"` (and listed `StarRocks`/`Inceptor` as dialect names). In reality no `JdbcDialectFactory.dialectFactoryName()` returns `StarRocks`/`Inceptor` — StarRocks is reached through the MySQL dialect via `compatible_mode = "starrocks"` and Inceptor through the Hive dialect via `compatible_mode = "inceptor"` (`MySqlDialectFactory.java`, `HiveDialectFactory.java`, `JdbcDialectLoader.java`). Configuring `dialect = "starrocks"` selects no factory and fails. 2. The dialect list was missing the existing `OpenGauss`, `Presto` and `DuckDB` dialects (`OpenGaussDialectFactory.java`, `PrestoDialectFactory.java`, `DuckDBDialectFactory.java`). 3. The sink options table missed the factory-registered option `multi_table_sink_replica` (Int, default `1`, `JdbcSinkFactory.java` / `SinkConnectorCommonOptions.java`). 4. The source options table missed `multi_table.failure_policy` (Enum, default `FAIL_FAST`), which `JdbcSourceConfig.java` actually consumes for `table_list` reads. **Kafka connector (source + sink)** 5. The sink doc banner claimed "By default, we will use 2pc to guarantee the message is sent to kafka exactly once", but the default `semantics` is `NON` (`KafkaSinkOptions.java`), which provides no such guarantee — contradicting the doc's own option table. 6. The NATIVE format example output lacked the `offset` field, which is part of the NATIVE schema and populated by the deserializer (`KafkaSourceConfig.nativeTableSchema()`, `NativeKafkaConnectDeserializationSchema.java`). 7. The source options table missed `key_converter_schema_enabled` (Boolean, default `true`) which is read alongside `value_converter_schema_enabled` for `format = compatible_kafka_connect_json` (`KafkaConnectJsonFormatOptions.java`, `KafkaSourceConfig.java`). 8. The zh sink doc still said to "configure `kafka_headers_fields` carefully" with NATIVE, while the code rejects the combination with `OPERATION_NOT_SUPPORTED` at serializer construction (`KafkaSinkSerializer.java`); the en doc was already corrected. **MQTT sink** 9. The `retry_timeout` section claimed exponential backoff, but `MqttSinkWriter` retries with a fixed 200 ms interval (`RETRY_BACKOFF_MS = 200L`). **SQL functions transform** 10. `LOG` was described with H2-copy text (PostgreSQL/MSSQLServer compatibility modes, deprecated single-argument variant). The Zeta implementation requires exactly two arguments (`NumericFunction.log` reads both unconditionally). 11. `RAND/RANDOM` was described as seeding "the session's random number generator", but a new `Random` is created per call, so the argument only seeds that single call. 12. The `ARRAY` note claimed only string/double/long/int element types are supported, while `ArrayFunction` supports the full numeric/string promotion set (and `sql.md` itself documents `ARRAY<TINYINT>`). ## What was changed - Corrected the `dialect` guidance in all four JDBC docs and removed invalid dialect values. - Rebuilt the dialect lists to match the actual `JdbcDialectFactory` implementations (added OpenGauss, Presto, DuckDB; removed StarRocks/Inceptor). - Added the missing `multi_table_sink_replica` and `multi_table.failure_policy` option rows. - Fixed the Kafka sink exactly-once banner, added `offset` to the NATIVE example output, added the `key_converter_schema_enabled` option row, and aligned the zh NATIVE + `kafka_headers_fields` warning with the en doc. - Replaced the MQTT sink "exponential backoff" claim with the actual fixed-interval retry behavior. - Rewrote the `LOG`, `RAND/RANDOM` and `ARRAY` descriptions in sql-functions.md to match the Zeta engine implementation. - Restored en/zh parity for the JDBC sink (SqlServer CDC source example, Aurora DSQL explanation paragraph, xugu / InterSystems IRIS driver rows, `方言列表` heading) and the JDBC source (bounded-source note, "explicit partition column + partition query" section, key-features paragraph). ## Areas / files updated 11 files (English and Chinese, 149 insertions / 55 deletions): - `docs/en/connectors/source/Jdbc.md`, `docs/zh/connectors/source/Jdbc.md` - `docs/en/connectors/sink/Jdbc.md`, `docs/zh/connectors/sink/Jdbc.md` - `docs/en/connectors/source/Kafka.md`, `docs/zh/connectors/source/Kafka.md` - `docs/en/connectors/sink/Kafka.md`, `docs/zh/connectors/sink/Kafka.md` - `docs/en/connectors/sink/Mqtt.md` - `docs/en/transforms/sql-functions.md`, `docs/zh/transforms/sql-functions.md` ## Were English and Chinese docs both checked? Yes. Every fix was applied to both languages where the text exists in both. Where the zh docs were missing content present in en (SqlServer CDC sink example, DSQL explanation, partition-query pattern, driver rows), the missing sections were translated and added. ## Duplicate PR check (last 7 days) I checked all PRs by any author touching docs in the last 7 days, with special attention to my own open doc PRs #12971, #12951, #12941, #12865 and #12813. None of them touch the files modified here (JDBC source/sink, Kafka source/sink, MQTT sink, sql-functions transform), so there is no overlap or duplication. The recently merged #12932/#12911 covered engine/REST and Kafka/Hive/JDBC topics, and this PR was rebased on the latest `upstream/dev` which already contains them. ## How the change was verified - Cross-checked every changed statement against the source code: option constants and defaults (`KafkaSinkOptions`, `KafkaConnectJsonFormatOptions`, `MqttSinkWriter`, `SinkConnectorCommonOptions`, `MultiTableCommonOptions`), dialect factory names (all 28 `*DialectFactory` classes + `DatabaseIdentifier`), NATIVE schema/deserializer fields, and the Zeta SQL function implementations (`NumericFunction`, `ArrayFunction`). - Ran `[email protected]` with the repository's `.dlc.json` config on all 11 modified files (the same tool and config used by CI in `backend.yml`): all links pass. - Verified markdown table column consistency across all modified tables programmatically (no pipe-count mismatches; the pre-existing escaped-pipe formatting in `Mqtt.md` was left untouched). - No Java code was changed, so `./mvnw verify` was not run; the change is documentation-only. -- 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]
