featzhang created FLINK-39092:
---------------------------------
Summary: [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
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)
