Status

Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).

Motivation

Apache Flink supports the STATEMENT SET  syntax to group and optimize multiple SQL statements, which is especially useful for reusing intermediate results in INSERT INTO  statements. Currently, a user can write and execute such a block using:

EXECUTE STATEMENT SET
BEGIN
   INSERT INTO `sales` SELECT ...;
   INSERT INTO `products` SELECT ...;
END;

However, if a user wants to preview or debug the execution plan of such a block using EXPLAIN, the syntax must drop the EXECUTE keyword:

EXPLAIN STATEMENT SET
BEGIN
   INSERT INTO `sales` SELECT ...;
   INSERT INTO `products` SELECT ...;
END;

This behavior is inconsistent and counterintuitive. Typically, EXPLAIN can be prepended to most SQL operations (e.g., EXPLAIN INSERT, EXPLAIN CREATE TABLE AS SELECT) without any syntactic modification. Requiring users to remove EXECUTE breaks this convention and leads to confusion.

This FLIP proposes extending Flink SQL to support the syntax EXPLAIN EXECUTE STATEMENT SET  to improve usability and consistency.

Public Interfaces

EXPLAIN EXECUTE STATEMENT SET
BEGIN
   INSERT INTO ...;
   INSERT INTO ...;
END;

EXPLAIN STATEMENT SET
BEGIN
   INSERT INTO ...;
   INSERT INTO ...;
END;

Proposed Changes

• Extend the Flink SQL Parser:

  • Modify the SQL parser to support the EXPLAIN EXECUTE STATEMENT SET syntax. This involves adjusting the grammar rules to allow EXECUTE to precede EXECUTE STATEMENT SET.

• Grammar Location:

  • The relevant grammar is defined in parserImpls.ftl file.

  • Specifically, the SqlExecute rule begins at line 2827, where the EXECUTE STATEMENT SET construct is currently parsed.

• Internal Behavior:

  • Internally, EXPLAIN EXECUTE STATEMENT SET should be parsed and handled equivalently to EXPLAIN STATEMENT SET.

Compatibility, Deprecation, and Migration Plan

This is a backward-compatible change. It does not deprecate any existing functionality and adds syntactic sugar to support a more intuitive SQL experience.

Test Plan

• Add parser unit tests to validate that EXPLAIN EXECUTE STATEMENT SET is parsed correctly.

• Add integration tests that compare the output of:

  EXPLAIN STATEMENT SET ...

  and

  EXPLAIN EXECUTE STATEMENT SET ...

  to ensure equivalence.

Rejected Alternatives

1. Do nothing: While the functionality exists under EXPLAIN STATEMENT SET , requiring users to remove EXECUTE  deviates from the principle of minimal surprise and can introduce avoidable confusion.

2. Add documentation only: Improved documentation may clarify the difference, but it does not address the user experience problem. This proposal aims to align the syntax with user expectations.