diff --git a/docs/dev/table/sql/describe.md b/docs/dev/table/sql/describe.md new file mode 100644 index 0000000000000..de188692ec9d4 --- /dev/null +++ b/docs/dev/table/sql/describe.md @@ -0,0 +1,202 @@ +--- +title: "DESCRIBE Statements" +nav-parent_id: sql +nav-pos: 7 +--- + + +* 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. + +
+
+{% 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 %} +
+ +
+{% 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 %} +
+ +
+{% 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 %} +
+ +
+{% 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 %} +
+
+ +The result of the above example is: +
+
+{% 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 %} +
+
+{% 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 %} +
+
+{% 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 %} +
+
+{% 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 %} +
+ +
+ + +{% 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 0000000000000..cb532ca07b132 --- /dev/null +++ b/docs/dev/table/sql/describe.zh.md @@ -0,0 +1,201 @@ +--- +title: "DESCRIBE 语句" +nav-parent_id: sql +nav-pos: 7 +--- + + +* 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 语句。 + +
+
+{% 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 %} +
+ +
+{% 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 %} +
+ +
+{% 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 %} +
+ +
+{% 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 %} +
+
+ +上述例子执行的结果为: +
+
+{% 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 %} +
+
+{% 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 %} +
+
+{% 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 %} +
+
+{% 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 %} +
+ +
+ +{% 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 73076e8f09eea..06f8bd38c0797 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 70130e8158ecb..00d34abd33eeb 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 b0baed1aa6c40..3de7b8fd3de91 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
@@ -417,22 +417,6 @@ SHOW VIEWS; {% endhighlight %} - - - -
- Describe
- Batch Streaming -
-

Describe the schema of the given table.

-{% highlight sql %} -DESCRIBE myTable; -{% endhighlight %} -

Describe the schema of the given view.

-{% highlight sql %} -DESCRIBE myView; -{% endhighlight %} -
Use
diff --git a/docs/dev/table/sql/queries.zh.md b/docs/dev/table/sql/queries.zh.md index 6c264ef652cb7..47c2aad10c19c 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
@@ -415,22 +415,6 @@ SHOW VIEWS; {% endhighlight %} - - - -
- Describe
- 批处理 流处理 -
-

描述给定表的 Schema

-{% highlight sql %} -DESCRIBE myTable; -{% endhighlight %} -

描述给定视图的 Schema

-{% highlight sql %} -DESCRIBE myView; -{% endhighlight %} -
Use