This is an automated email from the ASF dual-hosted git repository. lincoln pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/flink.git
commit 91fc5ba576696d64d7a65c040875e86702188b63 Author: Jane Chan <[email protected]> AuthorDate: Fri Jan 13 14:25:47 2023 +0800 [FLINK-30668][table-api] Introduce ExplainFormat to Explainable and TableEnvironment This closes #21662 --- .../api/{Explainable.java => ExplainFormat.java} | 26 ++++------------------ .../org/apache/flink/table/api/Explainable.java | 15 ++++++++++++- .../apache/flink/table/api/TableEnvironment.java | 16 ++++++++++++- .../flink/table/api/internal/CompiledPlanImpl.java | 3 ++- .../flink/table/api/internal/StatementSetImpl.java | 5 +++-- .../table/api/internal/TableEnvironmentImpl.java | 9 +++++--- .../api/internal/TableEnvironmentInternal.java | 17 +++++++++++++- .../apache/flink/table/api/internal/TableImpl.java | 5 +++-- .../table/api/internal/TablePipelineImpl.java | 5 +++-- 9 files changed, 66 insertions(+), 35 deletions(-) diff --git a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/Explainable.java b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/ExplainFormat.java similarity index 51% copy from flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/Explainable.java copy to flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/ExplainFormat.java index 59531107510..cc09103a4da 100644 --- a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/Explainable.java +++ b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/ExplainFormat.java @@ -20,28 +20,10 @@ package org.apache.flink.table.api; import org.apache.flink.annotation.PublicEvolving; -/** - * Represents an artifact that can be explained using a summary string. - * - * @see #explain(ExplainDetail...) - */ +/** Explain format categorizes the output format of explain result. */ @PublicEvolving -public interface Explainable<SELF extends Explainable<SELF>> { - - /** - * Returns the AST of this object and the execution plan to compute the result of the given - * statement. - * - * @param extraDetails The extra explain details which the result of this method should include, - * e.g. estimated cost, changelog mode for streaming - * @return AST and the execution plan. - */ - String explain(ExplainDetail... extraDetails); +public enum ExplainFormat { - /** Like {@link #explain(ExplainDetail...)}, but piping the result to {@link System#out}. */ - @SuppressWarnings("unchecked") - default SELF printExplain(ExplainDetail... extraDetails) { - System.out.println(explain(extraDetails)); - return (SELF) this; - } + /** Explain a {@link Explainable} with plain text format. */ + TEXT } diff --git a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/Explainable.java b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/Explainable.java index 59531107510..fc7e981f6d0 100644 --- a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/Explainable.java +++ b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/Explainable.java @@ -36,7 +36,20 @@ public interface Explainable<SELF extends Explainable<SELF>> { * e.g. estimated cost, changelog mode for streaming * @return AST and the execution plan. */ - String explain(ExplainDetail... extraDetails); + default String explain(ExplainDetail... extraDetails) { + return explain(ExplainFormat.TEXT, extraDetails); + } + + /** + * Returns the AST of this object and the execution plan to compute the result of the given + * statement. + * + * @param format The output format of explained plan + * @param extraDetails The extra explain details which the result of this method should include, + * e.g. estimated cost, changelog mode for streaming + * @return AST and the execution plan. + */ + String explain(ExplainFormat format, ExplainDetail... extraDetails); /** Like {@link #explain(ExplainDetail...)}, but piping the result to {@link System#out}. */ @SuppressWarnings("unchecked") diff --git a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/TableEnvironment.java b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/TableEnvironment.java index c47b50bcf52..01d5f174dbf 100644 --- a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/TableEnvironment.java +++ b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/TableEnvironment.java @@ -970,7 +970,21 @@ public interface TableEnvironment { * estimated cost, changelog mode for streaming, displaying execution plan in json format * @return AST and the execution plan. */ - String explainSql(String statement, ExplainDetail... extraDetails); + default String explainSql(String statement, ExplainDetail... extraDetails) { + return explainSql(statement, ExplainFormat.TEXT, extraDetails); + } + + /** + * Returns the AST of the specified statement and the execution plan to compute the result of + * the given statement. + * + * @param statement The statement for which the AST and execution plan will be returned. + * @param format The output format of explained plan. + * @param extraDetails The extra explain details which the explain result should include, e.g. + * estimated cost, changelog mode for streaming, displaying execution plan in json format + * @return AST and the execution plan. + */ + String explainSql(String statement, ExplainFormat format, ExplainDetail... extraDetails); /** * Returns completion hints for the given statement at the given cursor position. The completion diff --git a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/CompiledPlanImpl.java b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/CompiledPlanImpl.java index 6efa375eaf7..ea2b399997c 100644 --- a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/CompiledPlanImpl.java +++ b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/CompiledPlanImpl.java @@ -22,6 +22,7 @@ import org.apache.flink.FlinkVersion; import org.apache.flink.annotation.Internal; import org.apache.flink.table.api.CompiledPlan; import org.apache.flink.table.api.ExplainDetail; +import org.apache.flink.table.api.ExplainFormat; import org.apache.flink.table.api.TableResult; import org.apache.flink.table.api.config.TableConfigOptions; import org.apache.flink.table.delegation.InternalPlan; @@ -68,7 +69,7 @@ class CompiledPlanImpl implements CompiledPlan { } @Override - public String explain(ExplainDetail... extraDetails) { + public String explain(ExplainFormat format, ExplainDetail... extraDetails) { return tableEnvironment.explainPlan(internalPlan, extraDetails); } diff --git a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/StatementSetImpl.java b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/StatementSetImpl.java index 2233a5babee..0f349dcd54f 100644 --- a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/StatementSetImpl.java +++ b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/StatementSetImpl.java @@ -23,6 +23,7 @@ import org.apache.flink.annotation.Internal; import org.apache.flink.annotation.VisibleForTesting; import org.apache.flink.table.api.CompiledPlan; import org.apache.flink.table.api.ExplainDetail; +import org.apache.flink.table.api.ExplainFormat; import org.apache.flink.table.api.StatementSet; import org.apache.flink.table.api.Table; import org.apache.flink.table.api.TableDescriptor; @@ -96,10 +97,10 @@ public class StatementSetImpl<E extends TableEnvironmentInternal> implements Sta } @Override - public String explain(ExplainDetail... extraDetails) { + public String explain(ExplainFormat format, ExplainDetail... extraDetails) { List<Operation> operationList = operations.stream().map(o -> (Operation) o).collect(Collectors.toList()); - return tableEnvironment.explainInternal(operationList, extraDetails); + return tableEnvironment.explainInternal(operationList, format, extraDetails); } @Override diff --git a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/TableEnvironmentImpl.java b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/TableEnvironmentImpl.java index f33c2c31f2b..c8797876b91 100644 --- a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/TableEnvironmentImpl.java +++ b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/TableEnvironmentImpl.java @@ -28,6 +28,7 @@ import org.apache.flink.table.api.CompiledPlan; import org.apache.flink.table.api.DataTypes; import org.apache.flink.table.api.EnvironmentSettings; import org.apache.flink.table.api.ExplainDetail; +import org.apache.flink.table.api.ExplainFormat; import org.apache.flink.table.api.PlanReference; import org.apache.flink.table.api.ResultKind; import org.apache.flink.table.api.SqlParserException; @@ -689,7 +690,8 @@ public class TableEnvironmentImpl implements TableEnvironmentInternal { } @Override - public String explainSql(String statement, ExplainDetail... extraDetails) { + public String explainSql( + String statement, ExplainFormat format, ExplainDetail... extraDetails) { List<Operation> operations = getParser().parse(statement); if (operations.size() != 1) { @@ -701,11 +703,12 @@ public class TableEnvironmentImpl implements TableEnvironmentInternal { operations = new ArrayList<>(((StatementSetOperation) operations.get(0)).getOperations()); } - return explainInternal(operations, extraDetails); + return explainInternal(operations, format, extraDetails); } @Override - public String explainInternal(List<Operation> operations, ExplainDetail... extraDetails) { + public String explainInternal( + List<Operation> operations, ExplainFormat format, ExplainDetail... extraDetails) { operations = operations.stream() .filter(o -> !(o instanceof NopOperation)) diff --git a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/TableEnvironmentInternal.java b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/TableEnvironmentInternal.java index 36731abac8c..2f31e30ab44 100644 --- a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/TableEnvironmentInternal.java +++ b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/TableEnvironmentInternal.java @@ -22,6 +22,7 @@ import org.apache.flink.annotation.Experimental; import org.apache.flink.annotation.Internal; import org.apache.flink.table.api.CompiledPlan; import org.apache.flink.table.api.ExplainDetail; +import org.apache.flink.table.api.ExplainFormat; import org.apache.flink.table.api.Table; import org.apache.flink.table.api.TableEnvironment; import org.apache.flink.table.catalog.CatalogManager; @@ -91,7 +92,21 @@ public interface TableEnvironmentInternal extends TableEnvironment { * estimated cost, changelog mode for streaming * @return AST and the execution plan. */ - String explainInternal(List<Operation> operations, ExplainDetail... extraDetails); + default String explainInternal(List<Operation> operations, ExplainDetail... extraDetails) { + return explainInternal(operations, ExplainFormat.TEXT, extraDetails); + } + + /** + * Returns the AST of this table and the execution plan to compute the result of this table. + * + * @param operations The operations to be explained. + * @param format The output format. + * @param extraDetails The extra explain details which the explain result should include, e.g. + * estimated cost, changelog mode for streaming + * @return AST and the execution plan. + */ + String explainInternal( + List<Operation> operations, ExplainFormat format, ExplainDetail... extraDetails); /** * Registers an external {@link TableSource} in this {@link TableEnvironment}'s catalog. diff --git a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/TableImpl.java b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/TableImpl.java index 06006e72565..4eece5227b1 100644 --- a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/TableImpl.java +++ b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/TableImpl.java @@ -21,6 +21,7 @@ package org.apache.flink.table.api.internal; import org.apache.flink.annotation.Internal; import org.apache.flink.table.api.AggregatedTable; import org.apache.flink.table.api.ExplainDetail; +import org.apache.flink.table.api.ExplainFormat; import org.apache.flink.table.api.FlatAggregateTable; import org.apache.flink.table.api.GroupWindow; import org.apache.flink.table.api.GroupWindowedTable; @@ -476,9 +477,9 @@ public class TableImpl implements Table { } @Override - public String explain(ExplainDetail... extraDetails) { + public String explain(ExplainFormat format, ExplainDetail... extraDetails) { return tableEnvironment.explainInternal( - Collections.singletonList(getQueryOperation()), extraDetails); + Collections.singletonList(getQueryOperation()), format, extraDetails); } @Override diff --git a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/TablePipelineImpl.java b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/TablePipelineImpl.java index ce108322fe2..ab49eace98f 100644 --- a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/TablePipelineImpl.java +++ b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/TablePipelineImpl.java @@ -20,6 +20,7 @@ package org.apache.flink.table.api.internal; import org.apache.flink.table.api.CompiledPlan; import org.apache.flink.table.api.ExplainDetail; +import org.apache.flink.table.api.ExplainFormat; import org.apache.flink.table.api.TableException; import org.apache.flink.table.api.TablePipeline; import org.apache.flink.table.api.TableResult; @@ -57,8 +58,8 @@ class TablePipelineImpl implements TablePipeline { } @Override - public String explain(ExplainDetail... extraDetails) { - return tableEnvironment.explainInternal(singletonList(operation), extraDetails); + public String explain(ExplainFormat format, ExplainDetail... extraDetails) { + return tableEnvironment.explainInternal(singletonList(operation), format, extraDetails); } @Override
