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 <[email protected]> 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>
