[
https://issues.apache.org/jira/browse/FLINK-39092?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
ASF GitHub Bot updated FLINK-39092:
-----------------------------------
Labels: enhancement pull-request-available table-planner usability (was:
enhancement table-planner usability)
> [SQL] Enhance EXPLAIN plan to display watermark specification
> -------------------------------------------------------------
>
> Key: FLINK-39092
> URL: https://issues.apache.org/jira/browse/FLINK-39092
> Project: Flink
> Issue Type: Improvement
> Components: Table SQL / Planner
> Reporter: featzhang
> Priority: Minor
> Labels: enhancement, pull-request-available, table-planner,
> usability
>
> Currently, watermark logic is difficult to identify in EXPLAIN plan output,
> which creates challenges for streaming users trying to understand and debug
> watermark strategies.
> h3. Current Behavior
> {code}
> TableScan(table=[[default_catalog, default_database, orders]],
> fields=[user_id, order_time])
> {code}
> The watermark specification is not visible in the EXPLAIN output, forcing
> users to examine table DDL separately to understand the watermark strategy.
> h3. Expected Behavior
> {code}
> TableScan:
> table: [[default_catalog, default_database, orders]]
> fields: user_id, order_time
> watermark: order_time - order_time - INTERVAL '5' SECOND
> {code}
> Watermark specifications should be explicitly displayed in TableScan nodes
> within EXPLAIN plan output.
> h2. Why is this valuable?
> This enhancement helps streaming users to:
> * Quickly understand watermark configurations from query plans
> * Debug late data handling issues more efficiently
> * Verify watermark logic without examining table DDL
> * Improve overall development and troubleshooting experience
> h2. Proposed Solution
> Enhance the {{explainTerms}} method in {{FlinkLogicalTableSourceScan}} to:
> # Extract watermark specifications from {{ResolvedSchema}} via
> {{TableSourceTable}}
> # Display rowtime attribute and watermark expression in a readable format
> # Show watermark information only when present (maintaining backward
> compatibility)
> h2. Implementation Details
> *Modified Components:*
> *
> {{flink-table-planner/src/main/scala/org/apache/flink/table/planner/plan/nodes/logical/FlinkLogicalTableSourceScan.scala}}
> *Key Classes Involved:*
> * {{org.apache.flink.table.catalog.ResolvedSchema}}
> * {{org.apache.flink.table.catalog.WatermarkSpec}}
> * {{org.apache.flink.table.planner.plan.schema.TableSourceTable}}
> h2. Example Usage
> h3. Create Table with Watermark
> {code:sql}
> CREATE TABLE orders (
> user_id INT,
> order_time TIMESTAMP(3),
> WATERMARK FOR order_time AS order_time - INTERVAL '5' SECOND
> ) WITH (...);
> {code}
> h3. Verify EXPLAIN Output
> {code:sql}
> EXPLAIN SELECT * FROM orders;
> {code}
> The output will now include:
> {code}
> watermark: order_time - order_time - INTERVAL '5' SECOND
> {code}
> h2. Compatibility
> * *Backward Compatible*: Yes - watermark info is only displayed when present
> * *Public API Impact*: None - only changes internal explain output format
> * *Runtime Impact*: None - only affects plan display, not execution
> * *Serialization Impact*: None
> h2. Testing
> The enhancement can be verified by:
> # Compiling the module successfully
> # Creating tables with and without watermarks
> # Verifying EXPLAIN output displays watermark information correctly
> # Ensuring tables without watermarks continue to work normally
> h2. Priority
> *Impact*: High value for streaming users
> *Effort*: Low - minimal code changes (~13 lines)
> *Risk*: Low - display-only enhancement, no runtime changes
> h2. Related Work
> This follows similar enhancements made to improve EXPLAIN plan readability,
> such as:
> * Structured display of join conditions
> * Structured display of filter conditions
> * Enhanced projection alias information
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
