[SPARK-28804][DOCS][SQL] Document DESCRIBE QUERY in SQL Reference

docs/sql-ref-syntax-aux-describe-query.md

@@ -19,4 +19,89 @@ license: |
   limitations under the License.
 ---
 
-**This page is under construction**
+### Description
+The `DESCRIBE QUERY` statement is used to return the metadata of output
+of a query. A shorthand `DESC` may be used instead of `DESCRIBE` to
+describe the query output.
+
+### Syntax
+{% highlight sql %}
+{DESC | DESCRIBE} [QUERY] input_statement
+{% endhighlight %}
+
+### Parameters
+<dl>
+  <dt><code><em>QUERY</em></code></dt>
+  <dd>This clause is optional and may be omitted.</dd>
+  <dt><code><em>input_statement</em></code></dt>
+  <dd>
+    Specifies a result set producing statement and may be one of the following: 
+    <ul>
+      <li>a <code>SELECT</code> statement</li>
+      <li>a <code>CTE(Common table expression)</code> statement</li>
+      <li>an <code>INLINE TABLE</code> statement</li>
+      <li>a <code>TABLE</code> statement</li>
+      <li>a <code>FROM</code> statement</li>
+    </ul>
+    Please refer to <a href="sql-ref-syntax-qry-select.html">select-statement</a>
+    for a detailed syntax of the query parameter.
+  </dd>
+</dl>
+
+### Examples
+{% highlight sql %}
+-- Create table `person`
+CREATE TABLE person (name STRING , age INT COMMENT 'Age column', address STRING);
+
+-- Returns column metadata information for a simple select query
+DESCRIBE QUERY select age, sum(age) FROM person GROUP BY age;
+  +--------+---------+----------+
+  |col_name|data_type|comment   |
+  +--------+---------+----------+
+  |age     |int      |Age column|
+  |sum(age)|bigint   |null      |
+  +--------+---------+----------+
+
+-- Returns column metadata information for common table experession (`CTE`).
+DESCRIBE QUERY WITH all_names_cte
+  AS (SELECT name from person) SELECT * FROM all_names_cte;
+  +--------+---------+-------+
+  |col_name|data_type|comment|
+  +--------+---------+-------+
+  |name    |string   |null   |
+  +--------+---------+-------+
+
+-- Returns column metadata information for a inline table.
+DESC QUERY VALUES(100, 'John', 10000.20D) AS employee(id, name, salary);
+  +--------+---------+-------+
+  |col_name|data_type|comment|
+  +--------+---------+-------+
+  |id      |int      |null   |
+  |name    |string   |null   |
+  |salary  |double   |null   |
+  +--------+---------+-------+
+
+-- Returns column metadata information for `TABLE` statement.
+DESC QUERY TABLE person;
+  +--------+---------+----------+
+  |col_name|data_type|comment   |
+  +--------+---------+----------+
+  |name    |string   |null      |
+  |age     |int      |Age column|
+  |address |string   |null      |
+  +--------+---------+----------+
+
+-- Returns column metadata information for a `FROM` statement.
+-- `QUERY` clause is optional and can be omitted.
+DESCRIBE FROM person SELECT age;
+  +--------+---------+----------+
+  |col_name|data_type|comment   |
+  +--------+---------+----------+
+  |age     |int      |Age column|
+  +--------+---------+----------+
+{% endhighlight %}
+
+### Related Statements
+- [DESCRIBE DATABASE](sql-ref-syntax-aux-describe-database.html)
+- [DESCRIBE TABLE](sql-ref-syntax-aux-describe-table.html)
+- [DESCRIBE FUNCTION](sql-ref-syntax-aux-describe-function.html)