featzhang commented on PR #27612: URL: https://github.com/apache/flink/pull/27612#issuecomment-4366778055
Scope change: this PR is now **documentation-only**. After a closer look I realized that `ExplainDetail.CHANGELOG_MODE` already provides exactly the capability I originally tried to add — both as SQL (`EXPLAIN CHANGELOG_MODE <query>`) and Table API (`table.explain(ExplainDetail.CHANGELOG_MODE)`). `StreamPlanner` already passes `withChangelogTraits=true` into `FlinkRelOptUtil.toString(...)` whenever that detail is requested, and the rel tree writer then renders the `changelogMode=[...]` tag on each streaming physical node. The previous revisions on this branch tried to make that output unconditional by modifying `RelDescriptionWriterImpl`, which: - duplicated an already-supported public API, and - changed the default `EXPLAIN` output for every streaming query, breaking the expected plans of 200+ `flink-table-planner` tests. Instead, this PR keeps the runtime behavior unchanged and expands the `EXPLAIN` reference docs (English + Chinese) so that the existing feature is discoverable and actionable: - symbol encoding table (`I` / `UB` / `UA` / `D` / `PD` mapped to `RowKind`), - motivation (sink compatibility, retract vs. upsert, non-deterministic updates), - SQL and Table API syntax with a combined-details example, - a concrete `GROUP BY` example with the exact Optimized Physical Plan output, - interpretation guidance (append-only / upsert-style / retract-style), - relation to operators and connectors (`ScanTableSource#getChangelogMode`, `DynamicTableSink#getChangelogMode`), - clarifying notes (default `EXPLAIN` does not emit the tag, `JSON_EXECUTION_PLAN` does not expose it, batch plans do not carry a changelog mode). Diff is +158 / -5 across `docs/content/docs/sql/reference/utility/explain.md` and its Chinese counterpart; Hugo renders both pages cleanly (verified locally). The JIRA ticket still applies under its new "make the feature discoverable" framing. Happy to rename the ticket to `[docs]` as well if preferred. -- 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]
