SEPURI-SAI-KRISHNA opened a new issue, #11923: URL: https://github.com/apache/seatunnel/issues/11923
### Search before asking - [X] I had searched in the [issues](https://github.com/apache/seatunnel/issues?q=is%3Aissue+label%3A%22bug%22) and found no similar issues. ### What happened `docs/en/architecture/features/multi-table.md` presents a Java code block (§5.1 "Writer Implementation" and §5.3 "Replica Selection Strategies") that reads as a description of `MultiTableSinkWriter`, but the snippet describes an API that does not exist anywhere in the repository. A reader following the page will write code against methods and fields that cannot be found. This was split out of #11721 (which fixes only the `Math.abs` correctness bug on the routing line, in both the code and the two docs occurrences). @SEZ9 asked in review that the wider snippet be reshaped to mirror the real writer, and that the deferral be tracked as its own issue rather than lost. This is that issue. ### Divergences Verified against `seatunnel-api/src/main/java/org/apache/seatunnel/api/sink/multitablesink/MultiTableSinkWriter.java` on current `dev`: | Documented | Reality | Evidence | | --- | --- | --- | | `int selectReplica(TablePath, SeaTunnelRow)` | No such method | `grep -rn "selectReplica" --include=*.java .` → **0 hits** | | `Optional<Object> extractPrimaryKeyIfPresent(row)` | No such method | `grep -rn "extractPrimaryKeyIfPresent" --include=*.java .` → **0 hits** | | `private final int replicaNum` field | Not a field on the writer; the fan-out width is `blockingQueues.size()` | field list at `MultiTableSinkWriter.java:80-97` | | `writers.get(identifier); writer.write(element)` — direct synchronous dispatch | Rows are handed to a queue: `offerRowElement(index, element)`, drained by `MultiTableWriterRunnable` workers | `MultiTableSinkWriter.java:~600-622` | | `TablePath tablePath = row.getTablePath()` | Routing keys off the string `tableId` via `sinkPrimaryKeys.get(tableId)` | `MultiTableSinkWriter.java:600` | | Random strategy is `(int) (System.nanoTime() % replicaNum)` | `random.nextInt(blockingQueues.size())` | field at `:87`, use at `:603` | | Only two branches shown (pk / no pk) | Three: single-table-no-pk, unknown table (honours `MultiTableFailurePolicy`, may `handleTableFailure` or throw), and pk-hash routing | `MultiTableSinkWriter.java:600-622` | `System.nanoTime() % replicaNum` is additionally unsound as illustrative code: `nanoTime()` may be negative, so the expression can itself produce a negative index — the same class of bug #11721 fixes one line above it. ### What you expected to happen Either of the following would resolve it; I have no strong preference and would like a maintainer's steer before writing the patch: 1. **Mirror the real implementation** — rewrite the block so names, types, and control flow match `MultiTableSinkWriter`, including the queue hand-off and the failure-policy branch. 2. **Mark it as illustrative** — keep the simplified shape (it does communicate the *concept* well) but rename the symbols so they cannot be mistaken for real API, and state plainly above the block that it is pseudocode, not a copy of the writer. Option 2 is cheaper and arguably better pedagogy; option 1 is what was asked for in review. Whichever is chosen, the `System.nanoTime()` sign bug should not survive into the new text. `docs/zh/architecture/features/multi-table.md` needs no change: it expresses replica selection as the formula $replica = hash(pk) \bmod replicaNum$ with no Java snippet, so it never carried either problem. ### SeaTunnel Version dev (3.0.0-SNAPSHOT) ### SeaTunnel Config ```conf N/A - documentation only ``` ### Running Command ```shell N/A - documentation only ``` ### Error Exception ```log N/A - documentation only ``` ### Zeta or Flink or Spark Version N/A ### Java or Scala Version N/A ### Screenshots _No response_ ### Are you willing to submit PR? - [X] Yes I am willing to submit a PR! ### Code of Conduct - [X] I agree to follow this project's [Code of Conduct](https://www.apache.org/foundation/policies/conduct) -- 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]
