From 8ea756813eb5d716686e9919aa6ead16d01e99a9 Mon Sep 17 00:00:00 2001 From: Dilip Biswal Date: Tue, 20 Aug 2019 23:23:50 -0700 Subject: [PATCH 1/6] [SPARK-28804] Document DESCRIBE QUERY in SQL Reference --- docs/sql-ref-syntax-aux-describe-query.md | 32 ++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/docs/sql-ref-syntax-aux-describe-query.md b/docs/sql-ref-syntax-aux-describe-query.md index e1c5c54a5bfb..e6f5a0c2f13d 100644 --- a/docs/sql-ref-syntax-aux-describe-query.md +++ b/docs/sql-ref-syntax-aux-describe-query.md @@ -19,4 +19,34 @@ 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. + +### Syntax +{% highlight sql %} +{DESC | DESCRIBE} [QUERY] query + +query:= {cte | select-query | inline-table | TABLE table-name} +{% endhighlight %} +**Note** +* For detailed syntax of query parameter please refer to [select-statement](sql-ref-syntax-qry-select.html) + and the examples below. +* DESC and DESCRIBE are interchangeble and mean the same thing. + +### Examples +{% highlight sql %} +-- Returns column name, column type and comment info for a simple select query +DESCRIBE QUERY select * customer; +-- Returns column name, column type and comment info for a inline table. +DESC QUERY VALUES(1.00D, 'hello') as test_tab(c1, c2); +-- Returns column name, column type and comment info for query with set operations. +DESC QUERY SELECT int_col FROM int_tab UNION ALL select double_col from double_tab +-- Returns column name, column type and comment info for CTE. +DESCRIBE QUERY WITH cte AS (SELECT cust_id from customer) SELECT * FROM cte; +{% 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) From 837a64f33711d4008f9ec10170cc805cf9a7b728 Mon Sep 17 00:00:00 2001 From: Dilip Biswal Date: Wed, 21 Aug 2019 11:42:42 -0700 Subject: [PATCH 2/6] Code review --- docs/sql-ref-syntax-aux-describe-query.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sql-ref-syntax-aux-describe-query.md b/docs/sql-ref-syntax-aux-describe-query.md index e6f5a0c2f13d..095705ae9b52 100644 --- a/docs/sql-ref-syntax-aux-describe-query.md +++ b/docs/sql-ref-syntax-aux-describe-query.md @@ -20,7 +20,7 @@ license: | --- ### Description -The DESCRIBE QUERY statement is used to return the metadata of output +The `DESCRIBE QUERY` statement is used to return the metadata of output of a query. ### Syntax @@ -32,7 +32,7 @@ query:= {cte | select-query | inline-table | TABLE table-name} **Note** * For detailed syntax of query parameter please refer to [select-statement](sql-ref-syntax-qry-select.html) and the examples below. -* DESC and DESCRIBE are interchangeble and mean the same thing. +* `DESC` and `DESCRIBE` are interchangeble and mean the same thing. ### Examples {% highlight sql %} From 518110e16c39ea487dabb62f81b6ea68c92dcba8 Mon Sep 17 00:00:00 2001 From: Dilip Biswal Date: Thu, 29 Aug 2019 17:37:53 -0700 Subject: [PATCH 3/6] Code review --- docs/sql-ref-syntax-aux-describe-query.md | 84 ++++++++++++++++++----- 1 file changed, 68 insertions(+), 16 deletions(-) diff --git a/docs/sql-ref-syntax-aux-describe-query.md b/docs/sql-ref-syntax-aux-describe-query.md index 095705ae9b52..326393dd39ec 100644 --- a/docs/sql-ref-syntax-aux-describe-query.md +++ b/docs/sql-ref-syntax-aux-describe-query.md @@ -21,29 +21,81 @@ license: | ### Description The `DESCRIBE QUERY` statement is used to return the metadata of output -of a query. +of a query. A shorthand `DESC` may be used instead of `DESCRIBE` to +describe the query output. ### Syntax {% highlight sql %} -{DESC | DESCRIBE} [QUERY] query - -query:= {cte | select-query | inline-table | TABLE table-name} +{DESC | DESCRIBE} [QUERY] query {% endhighlight %} -**Note** -* For detailed syntax of query parameter please refer to [select-statement](sql-ref-syntax-qry-select.html) - and the examples below. -* `DESC` and `DESCRIBE` are interchangeble and mean the same thing. + +### Parameters +
+
query
+
+ Specifies a result set producing statement and may be specified in one of the following ways: +
    +
  • a SELECT statement
    • +
  • a CTE(Common table expression) statement
    • +
  • a INLINE TABLE statement
    • +
  • a TABLE statement
    • +
  • a FROM statement
    • +
+ Please refer to select-statement + for a detailed syntax of the query parameter. +
+
### Examples {% highlight sql %} --- Returns column name, column type and comment info for a simple select query -DESCRIBE QUERY select * customer; --- Returns column name, column type and comment info for a inline table. -DESC QUERY VALUES(1.00D, 'hello') as test_tab(c1, c2); --- Returns column name, column type and comment info for query with set operations. -DESC QUERY SELECT int_col FROM int_tab UNION ALL select double_col from double_tab --- Returns column name, column type and comment info for CTE. -DESCRIBE QUERY WITH cte AS (SELECT cust_id from customer) SELECT * FROM cte; +-- 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. +DESCRIBE QUERY FROM person SELECT age; + +--------+---------+----------+ + |col_name|data_type|comment | + +--------+---------+----------+ + |age |int |Age column| + +--------+---------+----------+ {% endhighlight %} ### Related Statements From 4d6f415fcbe83e768b3162e61fe51265e55bff5c Mon Sep 17 00:00:00 2001 From: Dilip Biswal Date: Thu, 29 Aug 2019 17:41:28 -0700 Subject: [PATCH 4/6] Code Review --- docs/sql-ref-syntax-aux-describe-query.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sql-ref-syntax-aux-describe-query.md b/docs/sql-ref-syntax-aux-describe-query.md index 326393dd39ec..956972e2687d 100644 --- a/docs/sql-ref-syntax-aux-describe-query.md +++ b/docs/sql-ref-syntax-aux-describe-query.md @@ -33,7 +33,7 @@ describe the query output.
query
- Specifies a result set producing statement and may be specified in one of the following ways: + Specifies a result set producing statement and may be one of the following:
  • a SELECT statement
  • a CTE(Common table expression) statement
    • From 8fe2b6741dbbef817fda84711db07823b77845c8 Mon Sep 17 00:00:00 2001 From: Dilip Biswal Date: Thu, 29 Aug 2019 17:47:21 -0700 Subject: [PATCH 5/6] minor nit --- docs/sql-ref-syntax-aux-describe-query.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/sql-ref-syntax-aux-describe-query.md b/docs/sql-ref-syntax-aux-describe-query.md index 956972e2687d..f49eed136433 100644 --- a/docs/sql-ref-syntax-aux-describe-query.md +++ b/docs/sql-ref-syntax-aux-describe-query.md @@ -26,12 +26,14 @@ describe the query output. ### Syntax {% highlight sql %} -{DESC | DESCRIBE} [QUERY] query +{DESC | DESCRIBE} [QUERY] input_statement {% endhighlight %} ### Parameters
    -
    query
    +
    QUERY
    +
    This clause is optional and may be omitted.
    +
    input_statement
    Specifies a result set producing statement and may be one of the following:
      @@ -90,7 +92,8 @@ DESC QUERY TABLE person; +--------+---------+----------+ -- Returns column metadata information for a `FROM` statement. -DESCRIBE QUERY FROM person SELECT age; +-- `QUERY` clause is optional and can be omitted. +DESCRIBE FROM person SELECT age; +--------+---------+----------+ |col_name|data_type|comment | +--------+---------+----------+ From bc8365333f182ec233d07df605a246731b610d51 Mon Sep 17 00:00:00 2001 From: Xiao Li Date: Fri, 30 Aug 2019 16:04:31 -0700 Subject: [PATCH 6/6] Update sql-ref-syntax-aux-describe-query.md --- docs/sql-ref-syntax-aux-describe-query.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sql-ref-syntax-aux-describe-query.md b/docs/sql-ref-syntax-aux-describe-query.md index f49eed136433..f7c4f0da8de9 100644 --- a/docs/sql-ref-syntax-aux-describe-query.md +++ b/docs/sql-ref-syntax-aux-describe-query.md @@ -39,7 +39,7 @@ describe the query output.
      • a SELECT statement
      • a CTE(Common table expression) statement
        • -
      • a INLINE TABLE statement
        • +
      • an INLINE TABLE statement
      • a TABLE statement
      • a FROM statement