You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@seatunnel.apache.org by "SEPURI-SAI-KRISHNA (via GitHub)" <gi...@apache.org> on 2026/08/21 08:10:47 UTC

[I] [Bug] [Docs] multi-table.md replica-selection snippet describes an API that does not exist [seatunnel]

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: commits-unsubscribe@seatunnel.apache.org.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [I] [Bug] [Docs] multi-table.md replica-selection snippet describes an API that does not exist [seatunnel]

Posted by "priyanshuvishwakarma273403 (via GitHub)" <gi...@apache.org>.
priyanshuvishwakarma273403 commented on issue #11923:
URL: https://github.com/apache/seatunnel/issues/11923#issuecomment-5369601793

   hi can i work on this issue??
   


-- 
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: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [I] [Bug] [Docs] multi-table.md replica-selection snippet describes an API that does not exist [seatunnel]

Posted by "SEPURI-SAI-KRISHNA (via GitHub)" <gi...@apache.org>.
SEPURI-SAI-KRISHNA commented on issue #11923:
URL: https://github.com/apache/seatunnel/issues/11923#issuecomment-5371697748

   PR is up: #11925.
   
   @DanielLeens thanks for the direction, I followed option 1, and the PR description lists the source paths mirrored so the doc/code mapping can be checked quickly.
   
   Two notes on how I read your item 4, since I did not want to either skip `zh` or pad it:
   
   `docs/zh/architecture/features/multi-table.md` has no Java listing at all, it is prose plus one formula, so most of the drift you and I listed simply is not present there. What *was* wrong is narrower but real: it described rows as routed directly to the underlying writer (they are queued and drained by `MultiTableWriterRunnable` workers), it omitted the unknown-table / `MultiTableFailurePolicy` branch, and it omitted the schema-change barrier. Those three are fixed, and the §5.3 formula becomes `(hash(pk) & Integer.MAX_VALUE) mod replicaNum` with both the `Math.abs` and `System.nanoTime()` traps called out. So `zh` is updated in the same PR, just with a smaller diff than `en` (+24/-11 vs +116/-84) because there was less that was wrong.
   
   I also extended slightly beyond the writer and replica-selection sections, to **§6.2 Schema Evolution Routing**. It carried the identical defect, `handleSchemaChange(...)` (the real method is `applySchemaChange`), the non-existent `writers` field, and a direct loop over replicas where the real path enqueues a `SchemaChangeBarrier` onto every queue. Leaving a `writers.get(identifier)` call in the same file would have contradicted the PR's own claim to have aligned the page. §4.1 I checked and deliberately left alone: `MultiTableSink` really does have `sinks`, `replicaNum`, and `catalogTables`, so it was already correct.
   
   One coordination point for whoever reviews: **#11925 and #11721 touch the same regions of this file**, so whichever merges second needs a trivial rebase, which I am happy to do either way. The routing line in #11925 is written in the post-#11721 masked form, because documenting the current `Math.abs` line as the reference pattern would mean documenting a known bug. If you would rather #11925 wait until #11721 lands, say so and I will hold it.
   
   @priyanshuvishwakarma273403 apologies for the overlap, I had already started on this one when you asked, which is why I claimed it. Thanks for checking first rather than duplicating work.


-- 
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: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [I] [Bug] [Docs] multi-table.md replica-selection snippet describes an API that does not exist [seatunnel]

Posted by "DanielLeens (via GitHub)" <gi...@apache.org>.
DanielLeens commented on issue #11923:
URL: https://github.com/apache/seatunnel/issues/11923#issuecomment-5369664827

   Thanks for splitting this out and for checking the current `dev` implementation so carefully. I re-checked the current code path before replying, and the drift you listed is real: the docs section still reads like a concrete `MultiTableSinkWriter` API, but current `dev` routes rows by `tableId`, hashes against `blockingQueues.size()`, hands work to queues via `offerQueueElement(...)`, and also has the unknown-table / failure-policy branch that the snippet does not show. The `System.nanoTime() % replicaNum` example is also not a safe illustrative fallback, because it can produce a negative value.
   
   Given that, I would take option 1 as the maintainer direction for this issue:
   1. rewrite the writer / replica-selection section so it matches the real current writer shape and names closely enough that readers can map the doc back to source;
   2. if the docs intentionally simplify something for explanation, mark it explicitly as simplified instead of presenting it as a copy of the current API;
   3. keep the narrower `Math.abs(Integer.MIN_VALUE)` correctness fix in #11721, and keep this issue scoped to the broader documentation alignment;
   4. update both English and Chinese docs in the same PR.
   
   A focused docs-only PR against `dev` would be welcome. Please cite the source paths you align with in the PR description so reviewers can verify the doc/code mapping quickly.


-- 
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: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [I] [Bug] [Docs] multi-table.md replica-selection snippet describes an API that does not exist [seatunnel]

Posted by "davidzollo (via GitHub)" <gi...@apache.org>.
davidzollo closed issue #11923: [Bug] [Docs] multi-table.md replica-selection snippet describes an API that does not exist
URL: https://github.com/apache/seatunnel/issues/11923


-- 
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: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [I] [Bug] [Docs] multi-table.md replica-selection snippet describes an API that does not exist [seatunnel]

Posted by "SEPURI-SAI-KRISHNA (via GitHub)" <gi...@apache.org>.
SEPURI-SAI-KRISHNA commented on issue #11923:
URL: https://github.com/apache/seatunnel/issues/11923#issuecomment-5369695907

   Hey @priyanshuvishwakarma273403 , thanks for reaching out. I have already started working on it. I will submit a PR soon. Thanks 


-- 
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: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org