maropu commented on a change in pull request #26970: [SPARK-28825][SQL][DOC]
Documentation for Explain Command
URL: https://github.com/apache/spark/pull/26970#discussion_r362446099
##########
File path: docs/sql-ref-syntax-qry-explain.md
##########
@@ -19,4 +19,112 @@ license: |
limitations under the License.
---
-**This page is under construction**
+### Description
+
+The `EXPLAIN` statement is used to provide logical/physical plans for an input
statement.
+By default, this clause provides information about a physical plan only.
+
+
+### Syntax
+{% highlight sql %}
+EXPLAIN [EXTENDED | CODEGEN | COST | FORMATTED] statement
+{% endhighlight %}
+
+### Parameters
+
+<dl>
+ <dt><code><em>EXTENDED</em></code></dt>
+ <dd>Generates Parsed Logical Plan, Analyzed Logical Plan, Optimized Logical
Plan and Physical Plan.
+ Parsed Logical plan is a unresolved plan that extracted from the query.
+ Analyzed logical plans transforms which translates UnresolvedAttribute and
UnresolvedRelation into fully typed objects.
+ The optimized logical plan transforms through a set of optimization rules,
resulting in the Physical plan.
+ </dd>
+</dl>
+
+<dl>
+ <dt><code><em>CODEGEN</em></code></dt>
+ <dd>Generates code for the statement, if any and a Physical Plan.</dd>
+</dl>
+
+<dl>
+ <dt><code><em>COST</em></code></dt>
+ <dd>If plan node statistics are available, generates a logical plan and the
statistics.</dd>
+</dl>
+
+<dl>
+ <dt><code><em>FORMATTED</em></code></dt>
+ <dd>Generates two sections: a physical plan outline and node details.</dd>
+</dl>
+
+<dl>
+ <dt><code><em>statement</em></code></dt>
+ <dd>
+ Specifies a SQL statement to be explained.
+ </dd>
+ </dl>
+
+### Examples
+{% highlight sql %}
+
+--Default Output
+
+EXPLAIN select * from emp;
++----------------------------------------------------+
+| plan |
++----------------------------------------------------+
+| == Physical Plan ==
+*(1) ColumnarToRow
++- FileScan parquet default.emp[id#0] Batched: true, DataFilters: [], Format:
Parquet, Location:
InMemoryFileIndex[file:/home/root1/Spark/spark/spark-warehouse/emp],
PartitionFilters: [], PushedFilters: [], ReadSchema: struct<id:int>
Review comment:
How about just using a simpler query? e.g.,
```
scala> sql("explain select k, sum(v) from values (1, 2), (1, 3) t(k, v)
group by k").show(1, false)
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|plan
|
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|== Physical Plan ==
*(2) HashAggregate(keys=[k#5], functions=[sum(cast(v#6 as bigint))])
+- Exchange hashpartitioning(k#5, 200), true, [id=#16]
+- *(1) HashAggregate(keys=[k#5], functions=[partial_sum(cast(v#6 as
bigint))])
+- *(1) LocalTableScan [k#5, v#6]
|
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
```
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscr...@spark.apache.org
For additional commands, e-mail: reviews-h...@spark.apache.org
