This is an automated email from the ASF dual-hosted git repository.
lixiao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/spark.git
The following commit(s) were added to refs/heads/master by this push:
new b4d7b30 [SPARK-28803][DOCS][SQL] Document DESCRIBE TABLE in SQL
Reference
b4d7b30 is described below
commit b4d7b30aa62792e7dfaa1318d0ef608286fde806
Author: Dilip Biswal <dbis...@us.ibm.com>
AuthorDate: Sat Aug 31 14:46:55 2019 -0700
[SPARK-28803][DOCS][SQL] Document DESCRIBE TABLE in SQL Reference
### What changes were proposed in this pull request?
Document DESCRIBE TABLE statement in SQL Reference Guide.
### Why are the changes needed?
Currently Spark lacks documentation on the supported SQL constructs causing
confusion among users who sometimes have to look at the code to understand
the
usage. This is aimed at addressing this issue.
### Does this PR introduce any user-facing change?
Yes.
**Before:**
There was no documentation for this.
**After.**
<img width="1234" alt="Screen Shot 2019-08-31 at 1 53 35 PM"
src="https://user-images.githubusercontent.com/14225158/64069071-f556a380-cbf6-11e9-985d-13dd37a32bbb.png";>
<img width="1234" alt="Screen Shot 2019-08-31 at 1 53 50 PM"
src="https://user-images.githubusercontent.com/14225158/64069073-f982c100-cbf6-11e9-925b-eb2fc85c3341.png";>
<img width="1234" alt="Screen Shot 2019-08-31 at 1 54 02 PM"
src="https://user-images.githubusercontent.com/14225158/64069076-0ef7eb00-cbf7-11e9-8062-9a9fb8700bb3.png";>
<img width="1234" alt="Screen Shot 2019-08-31 at 1 54 15 PM"
src="https://user-images.githubusercontent.com/14225158/64069077-0f908180-cbf7-11e9-9a31-9b7f122db2d3.png";>
<img width="1234" alt="Screen Shot 2019-08-31 at 1 54 30 PM"
src="https://user-images.githubusercontent.com/14225158/64069078-0f908180-cbf7-11e9-96ee-438a7b64c961.png";>
<img width="1234" alt="Screen Shot 2019-08-31 at 1 54 42 PM"
src="https://user-images.githubusercontent.com/14225158/64069079-0f908180-cbf7-11e9-9bae-734a1994f936.png";>
### How was this patch tested?
Tested using jykyll build --serve
Closes #25527 from dilipbiswal/ref-doc-desc-table.
Lead-authored-by: Dilip Biswal <dbis...@us.ibm.com>
Co-authored-by: Xiao Li <gatorsm...@gmail.com>
Signed-off-by: Xiao Li <gatorsm...@gmail.com>
---
docs/sql-ref-syntax-aux-describe-table.md | 163 +++++++++++++++++++++++++++++-
1 file changed, 162 insertions(+), 1 deletion(-)
diff --git a/docs/sql-ref-syntax-aux-describe-table.md
b/docs/sql-ref-syntax-aux-describe-table.md
index 110a5e4..e2cb0e4 100644
--- a/docs/sql-ref-syntax-aux-describe-table.md
+++ b/docs/sql-ref-syntax-aux-describe-table.md
@@ -18,5 +18,166 @@ license: |
See the License for the specific language governing permissions and
limitations under the License.
---
+### Description
+`DESCRIBE TABLE` statement returns the basic metadata information of a
+table. The metadata information includes column name, column type
+and column comment. Optionally a partition spec or column name may be specified
+to return the metadata pertaining to a partition or column respectively.
-**This page is under construction**
+### Syntax
+{% highlight sql %}
+{DESC | DESCRIBE} [TABLE] [format] table_identifier [partition_spec] [col_name]
+{% endhighlight %}
+
+### Parameters
+<dl>
+ <dt><code><em>format</em></code></dt>
+ <dd>
+ Specifies the optional format of describe output. If `EXTENDED` is
specified
+ then additional metadata information (such as parent database, owner, and
access time)
+ is returned.
+ </dd>
+ <dt><code><em>table_identifier</em></code></dt>
+ <dd>
+ Specifies a table name, which may be optionally qualified with a database
name.<br><br>
+ <b>Syntax:</b>
+ <code>
+ [database_name.]table_name
+ </code>
+ </dd>
+ <dt><code><em>partition_spec</em></code></dt>
+ <dd>
+ An optional parameter that specifies a comma separated list of key and
value pairs
+ for paritions. When specified, additional partition metadata is
returned.<br><br>
+ <b>Syntax:</b>
+ <code>
+ PARTITION (partition_col_name = partition_col_val [ , ... ])
+ </code>
+ </dd>
+ <dt><code><em>col_name</em></code></dt>
+ <dd>
+ An optional paramter that specifies the column name that needs to be
described.
+ The supplied column name may be optionally qualified. Parameters
`partition_spec`
+ and `col_name` are mutually exclusive and can not be specified together.
Currently
+ nested columns are not allowed to be specified.<br><br>
+
+ <b>Syntax:</b>
+ <code>
+ [database_name.][table_name.]column_name
+ </code>
+ </dd>
+</dl>
+
+### Examples
+{% highlight sql %}
+-- Creates a table `customer`. Assumes current database is `salesdb`.
+CREATE TABLE customer(
+ cust_id INT,
+ state VARCHAR(20),
+ name STRING COMMENT 'Short name'
+ )
+ USING parquet
+ PARTITION BY state;
+ ;
+
+-- Returns basic metadata information for unqualified table `customer`
+DESCRIBE TABLE customer;
+ +-----------------------+---------+----------+
+ |col_name |data_type|comment |
+ +-----------------------+---------+----------+
+ |cust_id |int |null |
+ |name |string |Short name|
+ |state |string |null |
+ |# Partition Information| | |
+ |# col_name |data_type|comment |
+ |state |string |null |
+ +-----------------------+---------+----------+
+
+-- Returns basic metadata information for qualified table `customer`
+DESCRIBE TABLE salesdb.customer;
+ +-----------------------+---------+----------+
+ |col_name |data_type|comment |
+ +-----------------------+---------+----------+
+ |cust_id |int |null |
+ |name |string |Short name|
+ |state |string |null |
+ |# Partition Information| | |
+ |# col_name |data_type|comment |
+ |state |string |null |
+ +-----------------------+---------+----------+
+
+-- Returns additional metadata such as parent database, owner, access time etc.
+DESCRIBE TABLE EXTENDED customer;
+ +----------------------------+------------------------------+----------+
+ |col_name |data_type |comment |
+ +----------------------------+------------------------------+----------+
+ |cust_id |int |null |
+ |name |string |Short name|
+ |state |string |null |
+ |# Partition Information | | |
+ |# col_name |data_type |comment |
+ |state |string |null |
+ | | | |
+ |# Detailed Table Information| | |
+ |Database |salesdb | |
+ |Table |customer | |
+ |Owner |<table owner> | |
+ |Created Time |Fri Aug 30 09:26:04 PDT 2019 | |
+ |Last Access |Wed Dec 31 16:00:00 PST 1969 | |
+ |Created By |<spark version> | |
+ |Type |MANAGED | |
+ |Provider |parquet | |
+ |Location |file:.../salesdb.db/customer | |
+ |Serde Library |...serde.ParquetHiveSerDe | |
+ |InputFormat |...MapredParquetInputFormat | |
+ |OutputFormat |...MapredParquetOutputFormat | |
+ +----------------------------+------------------------------+----------+
+
+-- Returns partition metadata such as partitioning column name, column type
and comment.
+DESCRIBE TABLE customer PARTITION (state = 'AR');
+
+
+--------------------------------+-----------------------------------------+----------+
+ |col_name |data_type
|comment |
+
+--------------------------------+-----------------------------------------+----------+
+ |cust_id |int
|null |
+ |name |string
|Short name|
+ |state |string
|null |
+ |# Partition Information | |
|
+ |# col_name |data_type
|comment |
+ |state |string
|null |
+ | | |
|
+ |# Detailed Partition Information| |
|
+ |Database |salesdb |
|
+ |Table |customer |
|
+ |Partition Values |[state=AR] |
|
+ |Location |file:.../salesdb.db/customer/state=AR |
|
+ |Serde Library |...serde.ParquetHiveSerDe |
|
+ |InputFormat |...parquet.MapredParquetInputFormat |
|
+ |OutputFormat |...parquet.MapredParquetOutputFormat |
|
+ |Storage Properties |[path=file:.../salesdb.db/customer, |
|
+ | | serialization.format=1] |
|
+ |Partition Parameters |{rawDataSize=-1, numFiles=1l, |
|
+ | | transient_lastDdlTime=1567185245, |
|
+ | | totalSize=688, |
|
+ | | COLUMN_STATS_ACCURATE=false, numRows=-1}|
|
+ |Created Time |Fri Aug 30 10:14:05 PDT 2019 |
|
+ |Last Access |Wed Dec 31 16:00:00 PST 1969 |
|
+ |Partition Statistics |688 bytes |
|
+
+--------------------------------+-----------------------------------------+----------+
+
+-- Returns the metadata for `name` column.
+-- Optional `TABLE` clause is omitted and column is fully qualified.
+DESCRIBE customer salesdb.customer.name;
+ +---------+----------+
+ |info_name|info_value|
+ +---------+----------+
+ |col_name |name |
+ |data_type|string |
+ |comment |Short name|
+ +---------+----------+
+{% endhighlight %}
+
+### Related Statements
+- [DESCRIBE DATABASE](sql-ref-syntax-aux-describe-database.html)
+- [DESCRIBE QUERY](sql-ref-syntax-aux-describe-query.html)
+- [DESCRIBE FUNCTION](sql-ref-syntax-aux-describe-function.html)
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@spark.apache.org
For additional commands, e-mail: commits-h...@spark.apache.org
![https://user-images.githubusercontent.com/14225158/64069071-f556a380-cbf6-11e9-985d-13dd37a32bbb.png"](https://user-images.githubusercontent.com/14225158/64069071-f556a380-cbf6-11e9-985d-13dd37a32bbb.png"){kind=link}
![https://user-images.githubusercontent.com/14225158/64069073-f982c100-cbf6-11e9-925b-eb2fc85c3341.png"](https://user-images.githubusercontent.com/14225158/64069073-f982c100-cbf6-11e9-925b-eb2fc85c3341.png"){kind=link}
![https://user-images.githubusercontent.com/14225158/64069076-0ef7eb00-cbf7-11e9-8062-9a9fb8700bb3.png"](https://user-images.githubusercontent.com/14225158/64069076-0ef7eb00-cbf7-11e9-8062-9a9fb8700bb3.png"){kind=link}
![https://user-images.githubusercontent.com/14225158/64069077-0f908180-cbf7-11e9-9a31-9b7f122db2d3.png"](https://user-images.githubusercontent.com/14225158/64069077-0f908180-cbf7-11e9-9a31-9b7f122db2d3.png"){kind=link}
![https://user-images.githubusercontent.com/14225158/64069078-0f908180-cbf7-11e9-96ee-438a7b64c961.png"](https://user-images.githubusercontent.com/14225158/64069078-0f908180-cbf7-11e9-96ee-438a7b64c961.png"){kind=link}
![https://user-images.githubusercontent.com/14225158/64069079-0f908180-cbf7-11e9-9bae-734a1994f936.png"](https://user-images.githubusercontent.com/14225158/64069079-0f908180-cbf7-11e9-9bae-734a1994f936.png"){kind=link}