...
| Code Block |
|---|
| language | java |
|---|
| firstline | 1 |
|---|
| title | Explainable |
|---|
| linenumbers | true |
|---|
|
/**
* Represents an artifact that can be explained using a summary string.
*
* @see #explain(ExplainDetail...)
*/
@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.
*/
default String explain(ExplainDetail... extraDetails) {
return explain(ExplainFormat.PLAIN_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 explain 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")
default SELF printExplain(ExplainDetail... extraDetails) {
return printExplain(ExplainFormat.PLAIN_TEXT, extraDetails);
}
/** Like {@link #explain(ExplainDetail...)}, but piping the result to {@link System#out}. */
@SuppressWarnings("unchecked")
default SELF printExplain(ExplainFormat format, ExplainDetail... extraDetails) {
System.out.println(explain(format, extraDetails));
return (SELF) this;
}
} |
...
| Code Block |
|---|
| language | java |
|---|
| firstline | 1 |
|---|
| title | ExplainFormat |
|---|
| linenumbers | true |
|---|
|
/** Explain format categorizes the output format of explain result. */
@PublicEvolving
public enum ExplainFormat {
/** Explain a {@link Explainable} with plain text format. */
PLAIN_TEXT
} |
| Code Block |
|---|
| language | java |
|---|
| firstline | 1 |
|---|
| title | ExplainDetail |
|---|
| linenumbers | true |
|---|
|
/** ExplainDetail defines the types of details for explain result. */
@PublicEvolving
public enum ExplainDetail {
/**
* The cost information on physical rel node estimated by optimizer. e.g. TableSourceScan(...,
* cumulative cost = {1.0E8 rows, 1.0E8 cpu, 2.4E9 io, 0.0 network, 0.0 memory}
*/
ESTIMATED_COST,
/**
* The changelog mode produced by a physical rel node. e.g. GroupAggregate(...,
* changelogMode=[I,UA,D])
*/
CHANGELOG_MODE,
/** The execution plan in json format of the program. */
JSON_EXECUTION_PLAN,
/**
* The potential risk warnings and SQL optimizer tuning advice analyzed from the physical plan.
*/
PLAN_ADVICE
} |
...
| Code Block |
|---|
| language | java |
|---|
| firstline | 1 |
|---|
| title | TableEnvironment |
|---|
| linenumbers | true |
|---|
|
@PublicEvolving
public interface TableEnvironment {
/**
* 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 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.
*/
default String explainSql(String statement, ExplainDetail... extraDetails) {
return explainSql(statement, ExplainFormat.PLAIN_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 explain 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);
} |
...
To leverage the planner's power to give more understandable, actionable advice closer to the user's perspective, we propose a new explain mode, which analyzes the optimized physical plan and attaches available tuning advice or data correctness warnings to the output. We also propose to categorize the output format by introducing the enum ExplainFormat, and with ExplainFormat#PLAIN_TEXT ExplainFormat#TEXT as default, which corresponds to the current output format.
...