This is an automated email from the ASF dual-hosted git repository.
jark pushed a commit to branch release-1.16
in repository https://gitbox.apache.org/repos/asf/flink.git
The following commit(s) were added to refs/heads/release-1.16 by this push:
new 29d95797ac1 [FLINK-29020][docs] Add document for CREATE TABLE AS SELECT
29d95797ac1 is described below
commit 29d95797ac170fa4ab4038dd063766171d8d7fe4
Author: Ron <[email protected]>
AuthorDate: Tue Oct 11 16:54:29 2022 +0800
[FLINK-29020][docs] Add document for CREATE TABLE AS SELECT
This closes #21013
---
docs/content.zh/docs/dev/table/sql/create.md | 44 +++++++++++++++++++++++++++-
docs/content/docs/dev/table/sql/create.md | 44 +++++++++++++++++++++++++++-
2 files changed, 86 insertions(+), 2 deletions(-)
diff --git a/docs/content.zh/docs/dev/table/sql/create.md
b/docs/content.zh/docs/dev/table/sql/create.md
index a3db8afb316..d480161a389 100644
--- a/docs/content.zh/docs/dev/table/sql/create.md
+++ b/docs/content.zh/docs/dev/table/sql/create.md
@@ -157,7 +157,7 @@ CREATE TABLE [IF NOT EXISTS]
[catalog_name.][db_name.]table_name
[COMMENT table_comment]
[PARTITIONED BY (partition_column_name1, partition_column_name2, ...)]
WITH (key1=val1, key2=val2, ...)
- [ LIKE source_table [( <like_options> )] ]
+ [ LIKE source_table [( <like_options> )] | AS select_query ]
<physical_column_definition>:
column_name column_type [ <column_constraint> ] [COMMENT column_comment]
@@ -513,6 +513,48 @@ LIKE Orders_in_file (
**注意：** 源表 `source_table` 可以是一个组合 ID。您可以指定不同 catalog 或者 DB 的表作为源表:
例如，`my_catalog.my_db.MyTable` 指定了源表 `MyTable` 来源于名为 `MyCatalog` 的 catalog 和名为
`my_db` 的 DB ，`my_db.MyTable` 指定了源表 `MyTable` 来源于当前 catalog 和名为 `my_db` 的 DB。
+### `AS select_statement`
+
+表也可以通过一个 CTAS 语句中的查询结果来创建并填充数据，CTAS 是一种简单、快捷的创建表并插入数据的方法。
+
+CTAS 有两个部分，SELECT 部分可以是 Flink SQL 支持的任何 [SELECT 查询]({{< ref
"docs/dev/table/sql/queries/overview" >}})。 CREATE 部分从 SELECT 查询中获取列信息，并创建目标表。
与 `CREATE TABLE` 类似，CTAS 要求必须在目标表的 WITH 子句中指定必填的表属性。
+
+CTAS 的建表操作需要依赖目标 Catalog。比如，Hive Catalog 会自动在 Hive 中创建物理表。但是基于内存的 Catalog
只会将表的元信息注册在执行 SQL 的 Client 的内存中。
+
+示例如下:
+
+```sql
+CREATE TABLE my_ctas_table
+WITH (
+ 'connector' = 'kafka',
+ ...
+)
+AS SELECT id, name, age FROM source_table WHERE mod(id, 10) = 0;
+```
+
+结果表 `my_ctas_table` 等效于使用以下语句创建表并写入数据:
+```sql
+CREATE TABLE my_ctas_table (
+ id BIGINT,
+ name STRING,
+ age INT
+) WITH (
+ 'connector' = 'kafka',
+ ...
+);
+
+INSERT INTO my_ctas_table SELECT id, name, age FROM source_table WHERE mod(id,
10) = 0;
+```
+
+**注意** CTAS 有如下约束：
+* 暂不支持创建临时表。
+* 暂不支持指定列信息。
+* 暂不支持指定 Watermark。
+* 暂不支持创建分区表。
+* 暂不支持主键约束。
+
+**注意** 目前，CTAS 创建的目标表是非原子性的，如果在向表中插入数据时发生错误，该表不会被自动删除。
+
{{< top >}}
## CREATE CATALOG
diff --git a/docs/content/docs/dev/table/sql/create.md
b/docs/content/docs/dev/table/sql/create.md
index f96847cc029..99b064ad7dd 100644
--- a/docs/content/docs/dev/table/sql/create.md
+++ b/docs/content/docs/dev/table/sql/create.md
@@ -155,7 +155,7 @@ CREATE TABLE [IF NOT EXISTS]
[catalog_name.][db_name.]table_name
[COMMENT table_comment]
[PARTITIONED BY (partition_column_name1, partition_column_name2, ...)]
WITH (key1=val1, key2=val2, ...)
- [ LIKE source_table [( <like_options> )] ]
+ [ LIKE source_table [( <like_options> )] | AS select_query ]
<physical_column_definition>:
column_name column_type [ <column_constraint> ] [COMMENT column_comment]
@@ -513,6 +513,48 @@ If you provide no like options, `INCLUDING ALL OVERWRITING
OPTIONS` will be used
**NOTE** The `source_table` can be a compound identifier. Thus, it can be a
table from a different catalog or database: e.g. `my_catalog.my_db.MyTable`
specifies table `MyTable` from catalog `MyCatalog` and database `my_db`;
`my_db.MyTable` specifies table `MyTable` from current catalog and database
`my_db`.
+### `AS select_statement`
+
+Tables can also be created and populated by the results of a query in one
create-table-as-select (CTAS) statement. CTAS is the simplest and fastest way
to create and insert data into a table with a single command.
+
+There are two parts in CTAS, the SELECT part can be any [SELECT query]({{< ref
"docs/dev/table/sql/queries/overview" >}}) supported by Flink SQL. The CREATE
part takes the resulting schema from the SELECT part and creates the target
table. Similar to `CREATE TABLE`, CTAS requires the required options of the
target table must be specified in WITH clause.
+
+The creating table operation of CTAS depends on the target Catalog. For
example, Hive Catalog creates the physical table in Hive automatically. But the
in-memory catalog registers the table metadata in the client's memory where the
SQL is executed.
+
+Consider the example statement below:
+
+```sql
+CREATE TABLE my_ctas_table
+WITH (
+ 'connector' = 'kafka',
+ ...
+)
+AS SELECT id, name, age FROM source_table WHERE mod(id, 10) = 0;
+```
+
+The resulting table `my_ctas_table` will be equivalent to create the table and
insert the data with the following statement:
+```sql
+CREATE TABLE my_ctas_table (
+ id BIGINT,
+ name STRING,
+ age INT
+) WITH (
+ 'connector' = 'kafka',
+ ...
+);
+
+INSERT INTO my_ctas_table SELECT id, name, age FROM source_table WHERE mod(id,
10) = 0;
+```
+
+**Note** CTAS has these restrictions:
+* Does not support creating a temporary table yet.
+* Does not support specifying explicit columns yet.
+* Does not support specifying explicit watermark yet.
+* Does not support creating partitioned table yet.
+* Does not support specifying primary key constraints yet.
+
+**Note** The target table created by CTAS is non-atomic currently, the table
won't be dropped automatically if occur errors while inserting data into the
table.
+
{{< top >}}
## CREATE CATALOG
