You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by tw...@apache.org on 2020/06/23 16:31:42 UTC
[flink] 05/08: [FLINK-17599][docs] Add documents for DESCRIBE
statement
This is an automated email from the ASF dual-hosted git repository.
twalthr pushed a commit to branch release-1.11
in repository https://gitbox.apache.org/repos/asf/flink.git
commit a4797e43421d61d1d5eb82cc528b31e43ec73f04
Author: godfreyhe <go...@163.com>
AuthorDate: Wed Jun 10 10:34:51 2020 +0800
[FLINK-17599][docs] Add documents for DESCRIBE statement
---
docs/dev/table/sql/describe.md | 202 ++++++++++++++++++++++++++++++++++++++
docs/dev/table/sql/describe.zh.md | 201 +++++++++++++++++++++++++++++++++++++
docs/dev/table/sql/index.md | 1 +
docs/dev/table/sql/index.zh.md | 1 +
docs/dev/table/sql/queries.md | 18 +---
docs/dev/table/sql/queries.zh.md | 18 +---
6 files changed, 407 insertions(+), 34 deletions(-)
diff --git a/docs/dev/table/sql/describe.md b/docs/dev/table/sql/describe.md
new file mode 100644
index 0000000..de18869
--- /dev/null
+++ b/docs/dev/table/sql/describe.md
@@ -0,0 +1,202 @@
+---
+title: "DESCRIBE Statements"
+nav-parent_id: sql
+nav-pos: 7
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+* This will be replaced by the TOC
+{:toc}
+
+DESCRIBE statements are used to describe the schema of a table or a view.
+
+
+## Run a DESCRIBE statement
+
+DESCRIBE statements can be executed with the `executeSql()` method of the `TableEnvironment`, or executed in [SQL CLI]({{ site.baseurl }}/dev/table/sqlClient.html). The `executeSql()` method returns the schema of given table for a successful DESCRIBE operation, otherwise will throw an exception.
+
+The following examples show how to run a DESCRIBE statement in `TableEnvironment` and in SQL CLI.
+
+<div class="codetabs" markdown="1">
+<div data-lang="java" markdown="1">
+{% highlight java %}
+EnvironmentSettings settings = EnvironmentSettings.newInstance()...
+TableEnvironment tableEnv = TableEnvironment.create(settings);
+
+// register a table named "Orders"
+tableEnv.executeSql(
+ "CREATE TABLE Orders (" +
+ " `user` BIGINT NOT NULl," +
+ " product VARCHAR(32)," +
+ " amount INT," +
+ " ts TIMESTAMP(3)," +
+ " ptime AS PROCTIME()," +
+ " PRIMARY KEY(`user`) NOT ENFORCED," +
+ " WATERMARK FOR ts AS ts - INTERVAL '1' SECONDS" +
+ ") with (...)");
+
+// print the schema
+tableEnv.executeSql("DESCRIBE Orders").print();
+
+{% endhighlight %}
+</div>
+
+<div data-lang="scala" markdown="1">
+{% highlight scala %}
+val settings = EnvironmentSettings.newInstance()...
+val tableEnv = TableEnvironment.create(settings)
+
+// register a table named "Orders"
+ tableEnv.executeSql(
+ "CREATE TABLE Orders (" +
+ " `user` BIGINT NOT NULl," +
+ " product VARCHAR(32)," +
+ " amount INT," +
+ " ts TIMESTAMP(3)," +
+ " ptime AS PROCTIME()," +
+ " PRIMARY KEY(`user`) NOT ENFORCED," +
+ " WATERMARK FOR ts AS ts - INTERVAL '1' SECONDS" +
+ ") with (...)")
+
+// print the schema
+tableEnv.executeSql("DESCRIBE Orders").print()
+
+{% endhighlight %}
+</div>
+
+<div data-lang="python" markdown="1">
+{% highlight python %}
+settings = EnvironmentSettings.new_instance()...
+table_env = StreamTableEnvironment.create(env, settings)
+
+# register a table named "Orders"
+table_env.execute_sql( \
+ "CREATE TABLE Orders ("
+ " `user` BIGINT NOT NULl,"
+ " product VARCHAR(32),"
+ " amount INT,"
+ " ts TIMESTAMP(3),"
+ " ptime AS PROCTIME(),"
+ " PRIMARY KEY(`user`) NOT ENFORCED,"
+ " WATERMARK FOR ts AS ts - INTERVAL '1' SECONDS"
+ ") with (...)");
+
+# print the schema
+table_env.execute_sql("DESCRIBE Orders").print()
+
+{% endhighlight %}
+</div>
+
+<div data-lang="SQL CLI" markdown="1">
+{% highlight sql %}
+Flink SQL> CREATE TABLE Orders (
+> `user` BIGINT NOT NULl,
+> product VARCHAR(32),
+> amount INT,
+> ts TIMESTAMP(3),
+> ptime AS PROCTIME(),
+> PRIMARY KEY(`user`) NOT ENFORCED,
+> WATERMARK FOR ts AS ts - INTERVAL '1' SECONDS
+> ) with (
+> ...
+> );
+[INFO] Table has been created.
+
+Flink SQL> DESCRIBE Orders;
+
+{% endhighlight %}
+</div>
+</div>
+
+The result of the above example is:
+<div class="codetabs" markdown="1">
+<div data-lang="java" markdown="1">
+{% highlight text %}
+
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+| name | type | null | key | computed column | watermark |
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+| user | BIGINT | false | PRI(user) | | |
+| product | VARCHAR(32) | true | | | |
+| amount | INT | true | | | |
+| ts | TIMESTAMP(3) *ROWTIME* | true | | | `ts` - INTERVAL '1' SECOND |
+| ptime | TIMESTAMP(3) NOT NULL *PROCTIME* | false | | PROCTIME() | |
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+5 rows in set
+
+{% endhighlight %}
+</div>
+<div data-lang="scala" markdown="1">
+{% highlight text %}
+
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+| name | type | null | key | computed column | watermark |
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+| user | BIGINT | false | PRI(user) | | |
+| product | VARCHAR(32) | true | | | |
+| amount | INT | true | | | |
+| ts | TIMESTAMP(3) *ROWTIME* | true | | | `ts` - INTERVAL '1' SECOND |
+| ptime | TIMESTAMP(3) NOT NULL *PROCTIME* | false | | PROCTIME() | |
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+5 rows in set
+
+{% endhighlight %}
+</div>
+<div data-lang="python" markdown="1">
+{% highlight text %}
+
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+| name | type | null | key | computed column | watermark |
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+| user | BIGINT | false | PRI(user) | | |
+| product | VARCHAR(32) | true | | | |
+| amount | INT | true | | | |
+| ts | TIMESTAMP(3) *ROWTIME* | true | | | `ts` - INTERVAL '1' SECOND |
+| ptime | TIMESTAMP(3) NOT NULL *PROCTIME* | false | | PROCTIME() | |
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+5 rows in set
+
+{% endhighlight %}
+</div>
+<div data-lang="SQL CLI" markdown="1">
+{% highlight text %}
+
+root
+ |-- user: BIGINT NOT NULL
+ |-- product: VARCHAR(32)
+ |-- amount: INT
+ |-- ts: TIMESTAMP(3) *ROWTIME*
+ |-- ptime: TIMESTAMP(3) NOT NULL *PROCTIME* AS PROCTIME()
+ |-- WATERMARK FOR ts AS `ts` - INTERVAL '1' SECOND
+ |-- CONSTRAINT PK_3599338 PRIMARY KEY (user)
+
+{% endhighlight %}
+</div>
+
+</div>
+
+
+{% top %}
+
+## Syntax
+
+{% highlight sql %}
+DESCRIBE [catalog_name.][db_name.]table_name
+{% endhighlight %}
diff --git a/docs/dev/table/sql/describe.zh.md b/docs/dev/table/sql/describe.zh.md
new file mode 100644
index 0000000..cb532ca
--- /dev/null
+++ b/docs/dev/table/sql/describe.zh.md
@@ -0,0 +1,201 @@
+---
+title: "DESCRIBE 语句"
+nav-parent_id: sql
+nav-pos: 7
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+* This will be replaced by the TOC
+{:toc}
+
+DESCRIBE 语句用来描述一张表或者视图的 Schema。
+
+
+## 执行 DESCRIBE 语句
+
+DESCRIBE 语句可以通过 `TableEnvironment` 的 `executeSql()` 执行，也可以在 [SQL CLI]({{ site.baseurl }}/dev/table/sqlClient.html) 中执行 DROP 语句。 若 DESCRIBE 操作执行成功，executeSql() 方法返回该表的 Schema，否则会抛出异常。
+
+以下的例子展示了如何在 TableEnvironment 和 SQL CLI 中执行一个 DESCRIBE 语句。
+
+<div class="codetabs" markdown="1">
+<div data-lang="java" markdown="1">
+{% highlight java %}
+EnvironmentSettings settings = EnvironmentSettings.newInstance()...
+TableEnvironment tableEnv = TableEnvironment.create(settings);
+
+// register a table named "Orders"
+tableEnv.executeSql(
+ "CREATE TABLE Orders (" +
+ " `user` BIGINT NOT NULl," +
+ " product VARCHAR(32)," +
+ " amount INT," +
+ " ts TIMESTAMP(3)," +
+ " ptime AS PROCTIME()," +
+ " PRIMARY KEY(`user`) NOT ENFORCED," +
+ " WATERMARK FOR ts AS ts - INTERVAL '1' SECONDS" +
+ ") with (...)");
+
+// print the schema
+tableEnv.executeSql("DESCRIBE Orders").print();
+
+{% endhighlight %}
+</div>
+
+<div data-lang="scala" markdown="1">
+{% highlight scala %}
+val settings = EnvironmentSettings.newInstance()...
+val tableEnv = TableEnvironment.create(settings)
+
+// register a table named "Orders"
+ tableEnv.executeSql(
+ "CREATE TABLE Orders (" +
+ " `user` BIGINT NOT NULl," +
+ " product VARCHAR(32)," +
+ " amount INT," +
+ " ts TIMESTAMP(3)," +
+ " ptime AS PROCTIME()," +
+ " PRIMARY KEY(`user`) NOT ENFORCED," +
+ " WATERMARK FOR ts AS ts - INTERVAL '1' SECONDS" +
+ ") with (...)")
+
+// print the schema
+tableEnv.executeSql("DESCRIBE Orders").print()
+
+{% endhighlight %}
+</div>
+
+<div data-lang="python" markdown="1">
+{% highlight python %}
+settings = EnvironmentSettings.new_instance()...
+table_env = StreamTableEnvironment.create(env, settings)
+
+# register a table named "Orders"
+table_env.execute_sql( \
+ "CREATE TABLE Orders ("
+ " `user` BIGINT NOT NULl,"
+ " product VARCHAR(32),"
+ " amount INT,"
+ " ts TIMESTAMP(3),"
+ " ptime AS PROCTIME(),"
+ " PRIMARY KEY(`user`) NOT ENFORCED,"
+ " WATERMARK FOR ts AS ts - INTERVAL '1' SECONDS"
+ ") with (...)");
+
+# print the schema
+table_env.execute_sql("DESCRIBE Orders").print()
+
+{% endhighlight %}
+</div>
+
+<div data-lang="SQL CLI" markdown="1">
+{% highlight sql %}
+Flink SQL> CREATE TABLE Orders (
+> `user` BIGINT NOT NULl,
+> product VARCHAR(32),
+> amount INT,
+> ts TIMESTAMP(3),
+> ptime AS PROCTIME(),
+> PRIMARY KEY(`user`) NOT ENFORCED,
+> WATERMARK FOR ts AS ts - INTERVAL '1' SECONDS
+> ) with (
+> ...
+> );
+[INFO] Table has been created.
+
+Flink SQL> DESCRIBE Orders;
+
+{% endhighlight %}
+</div>
+</div>
+
+上述例子执行的结果为:
+<div class="codetabs" markdown="1">
+<div data-lang="java" markdown="1">
+{% highlight text %}
+
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+| name | type | null | key | computed column | watermark |
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+| user | BIGINT | false | PRI(user) | | |
+| product | VARCHAR(32) | true | | | |
+| amount | INT | true | | | |
+| ts | TIMESTAMP(3) *ROWTIME* | true | | | `ts` - INTERVAL '1' SECOND |
+| ptime | TIMESTAMP(3) NOT NULL *PROCTIME* | false | | PROCTIME() | |
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+5 rows in set
+
+{% endhighlight %}
+</div>
+<div data-lang="scala" markdown="1">
+{% highlight text %}
+
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+| name | type | null | key | computed column | watermark |
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+| user | BIGINT | false | PRI(user) | | |
+| product | VARCHAR(32) | true | | | |
+| amount | INT | true | | | |
+| ts | TIMESTAMP(3) *ROWTIME* | true | | | `ts` - INTERVAL '1' SECOND |
+| ptime | TIMESTAMP(3) NOT NULL *PROCTIME* | false | | PROCTIME() | |
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+5 rows in set
+
+{% endhighlight %}
+</div>
+<div data-lang="python" markdown="1">
+{% highlight text %}
+
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+| name | type | null | key | computed column | watermark |
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+| user | BIGINT | false | PRI(user) | | |
+| product | VARCHAR(32) | true | | | |
+| amount | INT | true | | | |
+| ts | TIMESTAMP(3) *ROWTIME* | true | | | `ts` - INTERVAL '1' SECOND |
+| ptime | TIMESTAMP(3) NOT NULL *PROCTIME* | false | | PROCTIME() | |
++---------+----------------------------------+-------+-----------+-----------------+----------------------------+
+5 rows in set
+
+{% endhighlight %}
+</div>
+<div data-lang="SQL CLI" markdown="1">
+{% highlight text %}
+
+root
+ |-- user: BIGINT NOT NULL
+ |-- product: VARCHAR(32)
+ |-- amount: INT
+ |-- ts: TIMESTAMP(3) *ROWTIME*
+ |-- ptime: TIMESTAMP(3) NOT NULL *PROCTIME* AS PROCTIME()
+ |-- WATERMARK FOR ts AS `ts` - INTERVAL '1' SECOND
+ |-- CONSTRAINT PK_3599338 PRIMARY KEY (user)
+
+{% endhighlight %}
+</div>
+
+</div>
+
+{% top %}
+
+## 语法
+
+{% highlight sql %}
+DESCRIBE [catalog_name.][db_name.]table_name
+{% endhighlight %}
diff --git a/docs/dev/table/sql/index.md b/docs/dev/table/sql/index.md
index 73076e8..06f8bd3 100644
--- a/docs/dev/table/sql/index.md
+++ b/docs/dev/table/sql/index.md
@@ -34,6 +34,7 @@ This page lists all the supported statements supported in Flink SQL for now:
- [ALTER TABLE, DATABASE, FUNCTION](alter.html)
- [INSERT](insert.html)
- [SQL HINTS](hints.html)
+- [DESCRIBE](describe.html)
## Data Types
diff --git a/docs/dev/table/sql/index.zh.md b/docs/dev/table/sql/index.zh.md
index 70130e8..00d34ab 100644
--- a/docs/dev/table/sql/index.zh.md
+++ b/docs/dev/table/sql/index.zh.md
@@ -34,6 +34,7 @@ under the License.
- [ALTER TABLE, DATABASE, FUNCTION](alter.html)
- [INSERT](insert.html)
- [SQL HINTS](hints.html)
+- [DESCRIBE](describe.html)
## 数据类型
diff --git a/docs/dev/table/sql/queries.md b/docs/dev/table/sql/queries.md
index b667c29..9bfb953 100644
--- a/docs/dev/table/sql/queries.md
+++ b/docs/dev/table/sql/queries.md
@@ -382,7 +382,7 @@ String literals must be enclosed in single quotes (e.g., `SELECT 'Hello World'`)
## Operations
-### Show, Describe, and Use
+### Show and Use
<div markdown="1">
<table class="table table-bordered">
@@ -419,22 +419,6 @@ SHOW VIEWS;
</tr>
<tr>
<td>
- <strong>Describe</strong><br>
- <span class="label label-primary">Batch</span> <span class="label label-primary">Streaming</span>
- </td>
- <td>
- <p>Describe the schema of the given table.</p>
-{% highlight sql %}
-DESCRIBE myTable;
-{% endhighlight %}
- <p>Describe the schema of the given view.</p>
-{% highlight sql %}
-DESCRIBE myView;
-{% endhighlight %}
- </td>
- </tr>
- <tr>
- <td>
<strong>Use</strong><br>
<span class="label label-primary">Batch</span> <span class="label label-primary">Streaming</span>
</td>
diff --git a/docs/dev/table/sql/queries.zh.md b/docs/dev/table/sql/queries.zh.md
index 62efaca..147b682 100644
--- a/docs/dev/table/sql/queries.zh.md
+++ b/docs/dev/table/sql/queries.zh.md
@@ -380,7 +380,7 @@ Flink SQL 对于标识符（表、属性、函数名）有类似于 Java 的词
## 操作符
-### Show, Describe 与 Use
+### Show 与 Use
<div markdown="1">
<table class="table table-bordered">
@@ -417,22 +417,6 @@ SHOW VIEWS;
</tr>
<tr>
<td>
- <strong>Describe</strong><br>
- <span class="label label-primary">批处理</span> <span class="label label-primary">流处理</span>
- </td>
- <td>
- <p>描述给定表的 Schema</p>
-{% highlight sql %}
-DESCRIBE myTable;
-{% endhighlight %}
- <p>描述给定视图的 Schema</p>
-{% highlight sql %}
-DESCRIBE myView;
-{% endhighlight %}
- </td>
- </tr>
- <tr>
- <td>
<strong>Use</strong><br>
<span class="label label-primary">批处理</span> <span class="label label-primary">流处理</span>
</td>