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 d9e3e2006b5acb85731daf4d8b189df2c87f3ac8 Author: godfreyhe <[email protected]> AuthorDate: Wed Jun 10 16:57:22 2020 +0800 [FLINK-17599][docs] Add documents for USE statement --- 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 +--- docs/dev/table/sql/use.md | 200 +++++++++++++++++++++++++++++++++++++++ docs/dev/table/sql/use.zh.md | 199 ++++++++++++++++++++++++++++++++++++++ 6 files changed, 403 insertions(+), 34 deletions(-) diff --git a/docs/dev/table/sql/index.md b/docs/dev/table/sql/index.md index 5ac4ff1..db96b1e 100644 --- a/docs/dev/table/sql/index.md +++ b/docs/dev/table/sql/index.md @@ -36,6 +36,7 @@ This page lists all the supported statements supported in Flink SQL for now: - [SQL HINTS](hints.html) - [DESCRIBE](describe.html) - [EXPLAIN](explain.html) +- [USE](use.html) ## Data Types diff --git a/docs/dev/table/sql/index.zh.md b/docs/dev/table/sql/index.zh.md index 9b220f7..f81474b 100644 --- a/docs/dev/table/sql/index.zh.md +++ b/docs/dev/table/sql/index.zh.md @@ -36,6 +36,7 @@ under the License. - [SQL HINTS](hints.html) - [DESCRIBE](describe.html) - [EXPLAIN](explain.html) +- [USE](use.html) ## 数据类型 diff --git a/docs/dev/table/sql/queries.md b/docs/dev/table/sql/queries.md index 9bfb953..0040072 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 and Use +### Show <div markdown="1"> <table class="table table-bordered"> @@ -417,22 +417,6 @@ SHOW VIEWS; {% endhighlight %} </td> </tr> - <tr> - <td> - <strong>Use</strong><br> - <span class="label label-primary">Batch</span> <span class="label label-primary">Streaming</span> - </td> - <td> - <p>Set current catalog for the session </p> -{% highlight sql %} -USE CATALOG mycatalog; -{% endhighlight %} - <p>Set current database of the current catalog for the session</p> -{% highlight sql %} -USE mydatabase; -{% endhighlight %} - </td> - </tr> </tbody> </table> </div> diff --git a/docs/dev/table/sql/queries.zh.md b/docs/dev/table/sql/queries.zh.md index 147b682..d208380 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 与 Use +### Show <div markdown="1"> <table class="table table-bordered"> @@ -415,22 +415,6 @@ SHOW VIEWS; {% endhighlight %} </td> </tr> - <tr> - <td> - <strong>Use</strong><br> - <span class="label label-primary">批处理</span> <span class="label label-primary">流处理</span> - </td> - <td> - <p>为本次会话设置 catalog </p> -{% highlight sql %} -USE CATALOG mycatalog; -{% endhighlight %} - <p>为会话设置一个属于当前 catalog 的数据库</p> -{% highlight sql %} -USE mydatabase; -{% endhighlight %} - </td> - </tr> </tbody> </table> </div> diff --git a/docs/dev/table/sql/use.md b/docs/dev/table/sql/use.md new file mode 100644 index 0000000..983d2d4 --- /dev/null +++ b/docs/dev/table/sql/use.md @@ -0,0 +1,200 @@ +--- +title: "USE Statements" +nav-parent_id: sql +nav-pos: 9 +--- +<!-- +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} + +USE statements are used to set the current database or catalog. + + +## Run a USE statement + +USE 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 'OK' for a successful USE operation, otherwise will throw an exception. + +The following examples show how to run a USE statement in `TableEnvironment` and in SQL CLI. + +<div class="codetabs" markdown="1"> +<div data-lang="java" markdown="1"> +{% highlight java %} +StreamExecutionEnvironment env = StreamExecutionEnvironment.getExecutionEnvironment(); +StreamTableEnvironment tEnv = StreamTableEnvironment.create(env); + +// create a catalog +tEnv.executeSql("CREATE CATALOG cat1 WITH (...)"); +tEnv.executeSql("SHOW CATALOGS").print(); +// +-----------------+ +// | catalog name | +// +-----------------+ +// | default_catalog | +// | cat1 | +// +-----------------+ + +// change default catalog +tEnv.executeSql("USE CATALOG cat1"); + +tEnv.executeSql("SHOW DATABASES").print(); +// databases are empty +// +---------------+ +// | database name | +// +---------------+ +// +---------------+ + +// create a database +tEnv.executeSql("CREATE DATABASE db1 WITH (...)"); +tEnv.executeSql("SHOW DATABASES").print(); +// +---------------+ +// | database name | +// +---------------+ +// | db1 | +// +---------------+ + +// change default database +tEnv.executeSql("USE db1"); + +{% endhighlight %} +</div> + +<div data-lang="scala" markdown="1"> +{% highlight scala %} +val env = StreamExecutionEnvironment.getExecutionEnvironment() +val tEnv = StreamTableEnvironment.create(env) + +// create a catalog +tEnv.executeSql("CREATE CATALOG cat1 WITH (...)") +tEnv.executeSql("SHOW CATALOGS").print() +// +-----------------+ +// | catalog name | +// +-----------------+ +// | default_catalog | +// | cat1 | +// +-----------------+ + +// change default catalog +tEnv.executeSql("USE CATALOG cat1") + +tEnv.executeSql("SHOW DATABASES").print() +// databases are empty +// +---------------+ +// | database name | +// +---------------+ +// +---------------+ + +// create a database +tEnv.executeSql("CREATE DATABASE db1 WITH (...)") +tEnv.executeSql("SHOW DATABASES").print() +// +---------------+ +// | database name | +// +---------------+ +// | db1 | +// +---------------+ + +// change default database +tEnv.executeSql("USE db1") + +{% endhighlight %} +</div> + +<div data-lang="python" markdown="1"> +{% highlight python %} +settings = EnvironmentSettings.new_instance()... +table_env = StreamTableEnvironment.create(env, settings) + +# create a catalog +table_env.execute_sql("CREATE CATALOG cat1 WITH (...)") +table_env.execute_sql("SHOW CATALOGS").print() +# +-----------------+ +# | catalog name | +# +-----------------+ +# | default_catalog | +# | cat1 | +# +-----------------+ + +# change default catalog +table_env.execute_sql("USE CATALOG cat1") + +table_env.execute_sql("SHOW DATABASES").print() +# databases are empty +# +---------------+ +# | database name | +# +---------------+ +# +---------------+ + +# create a database +table_env.execute_sql("CREATE DATABASE db1 WITH (...)") +table_env.execute_sql("SHOW DATABASES").print() +# +---------------+ +# | database name | +# +---------------+ +# | db1 | +# +---------------+ + +# change default database +table_env.execute_sql("USE db1") + +{% endhighlight %} +</div> + +<div data-lang="SQL CLI" markdown="1"> +{% highlight sql %} +Flink SQL> CREATE CATALOG cat1 WITH (...); +[INFO] Catalog has been created. + +Flink SQL> SHOW CATALOGS; +default_catalog +cat1 + +Flink SQL> USE CATALOG cat1; + +Flink SQL> SHOW DATABASES; + +Flink SQL> CREATE DATABASE db1 WITH (...); +[INFO] Database has been created. + +Flink SQL> SHOW DATABASES; +db1 + +Flink SQL> USE db1; + +{% endhighlight %} +</div> +</div> + +{% top %} + +## USE CATLOAG + +{% highlight sql %} +USE CATALOG catalog_name +{% endhighlight %} + +Set the current catalog. All subsequent commands that do not explicitly specify a catalog will use this one. If the provided catalog does not exist, an exception is thrown. The default current catalog is `default_catalog`. + + +## USE + +{% highlight sql %} +USE [catalog_name.]database_name +{% endhighlight %} + +Set the current database. All subsequent commands that do not explicitly specify a database will use this one. If the provided database does not exist, an exception is thrown. The default current database is `default_database`. diff --git a/docs/dev/table/sql/use.zh.md b/docs/dev/table/sql/use.zh.md new file mode 100644 index 0000000..128faf5 --- /dev/null +++ b/docs/dev/table/sql/use.zh.md @@ -0,0 +1,199 @@ +--- +title: "USE 语句" +nav-parent_id: sql +nav-pos: 9 +--- +<!-- +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} + +USE 语句用来设置当前的 catalog 或者 database。 + +## 运行一个 USE 语句 + +可以使用 TableEnvironment 中的 executeSql() 方法执行 USE 语句，也可以在 SQL CLI 中执行 USE 语句。 若 USE 操作执行成功，executeSql() 方法返回 'OK'，否则会抛出异常。 + +以下的例子展示了如何在 TableEnvironment 和 SQL CLI 中执行一个 USE 语句。 + +<div class="codetabs" markdown="1"> +<div data-lang="java" markdown="1"> +{% highlight java %} +StreamExecutionEnvironment env = StreamExecutionEnvironment.getExecutionEnvironment(); +StreamTableEnvironment tEnv = StreamTableEnvironment.create(env); + +// create a catalog +tEnv.executeSql("CREATE CATALOG cat1 WITH (...)"); +tEnv.executeSql("SHOW CATALOGS").print(); +// +-----------------+ +// | catalog name | +// +-----------------+ +// | default_catalog | +// | cat1 | +// +-----------------+ + +// change default catalog +tEnv.executeSql("USE CATALOG cat1"); + +tEnv.executeSql("SHOW DATABASES").print(); +// databases are empty +// +---------------+ +// | database name | +// +---------------+ +// +---------------+ + +// create a database +tEnv.executeSql("CREATE DATABASE db1 WITH (...)"); +tEnv.executeSql("SHOW DATABASES").print(); +// +---------------+ +// | database name | +// +---------------+ +// | db1 | +// +---------------+ + +// change default database +tEnv.executeSql("USE db1"); + +{% endhighlight %} +</div> + +<div data-lang="scala" markdown="1"> +{% highlight scala %} +val env = StreamExecutionEnvironment.getExecutionEnvironment() +val tEnv = StreamTableEnvironment.create(env) + +// create a catalog +tEnv.executeSql("CREATE CATALOG cat1 WITH (...)") +tEnv.executeSql("SHOW CATALOGS").print() +// +-----------------+ +// | catalog name | +// +-----------------+ +// | default_catalog | +// | cat1 | +// +-----------------+ + +// change default catalog +tEnv.executeSql("USE CATALOG cat1") + +tEnv.executeSql("SHOW DATABASES").print() +// databases are empty +// +---------------+ +// | database name | +// +---------------+ +// +---------------+ + +// create a database +tEnv.executeSql("CREATE DATABASE db1 WITH (...)") +tEnv.executeSql("SHOW DATABASES").print() +// +---------------+ +// | database name | +// +---------------+ +// | db1 | +// +---------------+ + +// change default database +tEnv.executeSql("USE db1") + +{% endhighlight %} +</div> + +<div data-lang="python" markdown="1"> +{% highlight python %} +settings = EnvironmentSettings.new_instance()... +table_env = StreamTableEnvironment.create(env, settings) + +# create a catalog +table_env.execute_sql("CREATE CATALOG cat1 WITH (...)") +table_env.execute_sql("SHOW CATALOGS").print() +# +-----------------+ +# | catalog name | +# +-----------------+ +# | default_catalog | +# | cat1 | +# +-----------------+ + +# change default catalog +table_env.execute_sql("USE CATALOG cat1") + +table_env.execute_sql("SHOW DATABASES").print() +# databases are empty +# +---------------+ +# | database name | +# +---------------+ +# +---------------+ + +# create a database +table_env.execute_sql("CREATE DATABASE db1 WITH (...)") +table_env.execute_sql("SHOW DATABASES").print() +# +---------------+ +# | database name | +# +---------------+ +# | db1 | +# +---------------+ + +# change default database +table_env.execute_sql("USE db1") + +{% endhighlight %} +</div> + +<div data-lang="SQL CLI" markdown="1"> +{% highlight sql %} +Flink SQL> CREATE CATALOG cat1 WITH (...); +[INFO] Catalog has been created. + +Flink SQL> SHOW CATALOGS; +default_catalog +cat1 + +Flink SQL> USE CATALOG cat1; + +Flink SQL> SHOW DATABASES; + +Flink SQL> CREATE DATABASE db1 WITH (...); +[INFO] Database has been created. + +Flink SQL> SHOW DATABASES; +db1 + +Flink SQL> USE db1; + +{% endhighlight %} +</div> +</div> + +{% top %} + +## USE CATLOAG + +{% highlight sql %} +USE CATALOG catalog_name +{% endhighlight %} + +设置当前的 catalog。所有后续命令未显式指定 catalog 的将使用此 catalog。如果指定的的 catalog 不存在，则抛出异常。默认的当前 catalog 是 `default_catalog`。 + + +## USE + +{% highlight sql %} +USE [catalog_name.]database_name +{% endhighlight %} + +设置当前的 database。所有后续命令未显式指定 database 的将使用此 database。如果指定的的 database 不存在，则抛出异常。默认的当前 database 是 `default_database`。
