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:44 UTC
[flink] 07/08: [FLINK-17599][docs] Add documents for USE 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 d9e3e2006b5acb85731daf4d8b189df2c87f3ac8
Author: godfreyhe <go...@163.com>
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`。