From a485d574a4419b4bde57cac14c0a45a7fa9f36bf Mon Sep 17 00:00:00 2001 From: Yulei-Yang Date: Tue, 22 Oct 2024 15:08:33 +0800 Subject: [PATCH 1/2] [temporary_table] add docs for temporary table --- .../Create/CREATE-TABLE-AS-SELECT.md | 2 +- .../Data-Definition-Statements/Create/CREATE-TABLE-LIKE.md | 3 ++- .../Data-Definition-Statements/Create/CREATE-TABLE.md | 5 ++++- .../Create/CREATE-TABLE-AS-SELECT.md | 2 +- .../Data-Definition-Statements/Create/CREATE-TABLE-LIKE.md | 3 ++- .../Data-Definition-Statements/Create/CREATE-TABLE.md | 5 ++++- sidebars.json | 3 ++- 7 files changed, 16 insertions(+), 7 deletions(-) diff --git a/docs/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-AS-SELECT.md b/docs/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-AS-SELECT.md index 3cc87b52e7f88..d263ed27cb7bb 100644 --- a/docs/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-AS-SELECT.md +++ b/docs/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-AS-SELECT.md @@ -37,7 +37,7 @@ This statement creates the table structure by returning the results from the Sel grammar： ```sql -CREATE TABLE table_name [( column_name_list )] +CREATE [TEMPORARY] TABLE table_name [( column_name_list )] opt_engine:engineName opt_keys:keys opt_comment:tableComment diff --git a/docs/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-LIKE.md b/docs/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-LIKE.md index 159945a66e82e..eaf29a38bf314 100644 --- a/docs/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-LIKE.md +++ b/docs/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-LIKE.md @@ -37,7 +37,7 @@ This statement is used to create an empty table with the exact same table struct grammar: ```sql -CREATE [EXTERNAL] TABLE [IF NOT EXISTS] [database.]table_name LIKE [database.]table_name [WITH ROLLUP (r1,r2,r3,...)] +CREATE [TEMPORARY | EXTERNAL] TABLE [IF NOT EXISTS] [database.]table_name LIKE [database.]table_name [WITH ROLLUP (r1,r2,r3,...)] ``` illustrate: @@ -46,6 +46,7 @@ illustrate: - The user needs to have `SELECT` permission on the copied original table - Support for copying external tables such as MySQL - Support the rollup of copying OLAP Table +- Temporary tables can only be internal tables. And they can only be created based on internal tables. ### Example diff --git a/docs/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE.md b/docs/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE.md index b155b6441c50b..17c036bbadec9 100644 --- a/docs/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE.md +++ b/docs/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE.md @@ -33,7 +33,7 @@ under the License. This command is used to create a table. The subject of this document describes the syntax for creating Doris self-maintained tables. ```sql -CREATE TABLE [IF NOT EXISTS] [database.]table +CREATE [TEMPORARY] TABLE [IF NOT EXISTS] [database.]table ( column_definition_list [, index_definition_list] @@ -48,6 +48,9 @@ distribution_desc [extra_properties] ``` +#### TEMPORARY +Indicates creating a temporary table, which only available in current session, and will be deleted after the session be closed. + #### column_definition_list Column definition list: diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-AS-SELECT.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-AS-SELECT.md index c9283fc87d7a3..48b59a51dd13d 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-AS-SELECT.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-AS-SELECT.md @@ -37,7 +37,7 @@ CREATE TABLE AS SELECT 语法： ```sql -CREATE TABLE table_name [( column_name_list )] +CREATE [TEMPORARY] TABLE table_name [( column_name_list )] opt_engine:engineName opt_keys:keys opt_comment:tableComment diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-LIKE.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-LIKE.md index 80868b4dc47f7..0372f75282eb1 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-LIKE.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-LIKE.md @@ -37,7 +37,7 @@ CREATE TABLE LIKE 语法： ```sql -CREATE [EXTERNAL] TABLE [IF NOT EXISTS] [database.]table_name LIKE [database.]table_name [WITH ROLLUP (r1,r2,r3,...)] +CREATE [TEMPORARY | EXTERNAL] TABLE [IF NOT EXISTS] [database.]table_name LIKE [database.]table_name [WITH ROLLUP (r1,r2,r3,...)] ``` 说明: @@ -46,6 +46,7 @@ CREATE [EXTERNAL] TABLE [IF NOT EXISTS] [database.]table_name LIKE [database.]ta - 用户需要对复制的原表有`SELECT`权限 - 支持复制MySQL等外表 - 支持复制OLAP Table的rollup +- 临时表只能是内表。只能基于内表创建 ### Example diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE.md index 9cb5a09861643..a5eea9aecf3ca 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE.md @@ -33,7 +33,7 @@ under the License. 该命令用于创建一张表。本文档主要介绍创建 Doris 自维护的表的语法 ```sql -CREATE TABLE [IF NOT EXISTS] [database.]table +CREATE [TEMPORARY] TABLE [IF NOT EXISTS] [database.]table ( column_definition_list [, index_definition_list] @@ -48,6 +48,9 @@ distribution_desc [extra_properties] ``` +#### TEMPORARY +创建临时表。临时表仅在当前 Session 可见，会话结束自动删除 + #### column_definition_list 列定义列表： diff --git a/sidebars.json b/sidebars.json index 52d7ab2bdbde3..54e3e59a04107 100644 --- a/sidebars.json +++ b/sidebars.json @@ -122,6 +122,7 @@ ] }, "table-design/auto-increment", + "table-design/temporary-table", "table-design/best-practice" ] }, @@ -1761,4 +1762,4 @@ ] } ] -} \ No newline at end of file +} From 6159a302d342e8c3554b20791a4fb4e1dc1a4715 Mon Sep 17 00:00:00 2001 From: Yulei-Yang Date: Tue, 22 Oct 2024 15:10:49 +0800 Subject: [PATCH 2/2] update --- docs/table-design/temporary-table.md | 61 +++++++++++++++++++ .../current/table-design/temporary-table.md | 60 ++++++++++++++++++ 2 files changed, 121 insertions(+) create mode 100644 docs/table-design/temporary-table.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/table-design/temporary-table.md diff --git a/docs/table-design/temporary-table.md b/docs/table-design/temporary-table.md new file mode 100644 index 0000000000000..745ec4139dc9d --- /dev/null +++ b/docs/table-design/temporary-table.md @@ -0,0 +1,61 @@ +--- +title: Temporary Table +language: en +--- + + + +When performing complex data processing tasks, breaking down large SQL queries into multiple steps and temporarily saving the results of each step as physical tables is an effective strategy. This method can significantly reduce the complexity of SQL queries and enhance data debuggability. However, it is important to note that these physical tables must be manually cleaned up after they have served their purpose. If non-physical temporary tables are preferred, Doris currently only supports defining them via the `WITH` clause. + +To address the above issues, Doris introduces the temporary table feature. Temporary tables are temporarily existing materialized internal tables with the following key characteristics: +1. **Session Binding**: Temporary tables exist only within the session in which they were created. Their lifecycle is tightly bound to the current session, meaning that when the session ends, the temporary tables created within that session are automatically deleted. + +2. **Session-specific Visibility**: The visibility of temporary tables is strictly confined to the session in which they were created. Even another session started by the same user at the same time cannot access these temporary tables. + +By introducing the temporary table feature, Doris not only simplifies the temporary data storage and management in complex data processing but also further enhances the flexibility and security of data processing. + + +:::note + +Similar to internal tables, temporary tables must be created under a Database within the Internal Catalog. However, since temporary tables are session-based, their naming is not subject to uniqueness constraints. You can create temporary tables with the same name in different sessions or create temporary tables with the same names as other internal tables. + +If a temporary table and a non-temporary table with the same name exist simultaneously in the same Database, the temporary table has the highest access priority. Within that session, all queries and operations on the table with the same name will only affect the temporary table (except for creating materialized views). +::: + +## Usage + +### Creating a Temporay Table + +Tables of various models can be defined as temporary tables, whether they are Unique, Aggregate, or Duplicate models. You can create temporary tables by adding the TEMPORARY keyword in the following SQL statements: +- [CREATE TABLE](../sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE) +- [CREATE TABLE AS SELECT](../sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-AS-SELECT) +- [CREATE TABLE LIKE](../sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-LIKE) + +The other uses of temporary tables are basically the same as regular internal tables. Except for the above-mentioned Create statement, other DDL and DML statements do not require adding the TEMPORARY keyword. + +## Notes + +- Temporary tables can only be created in the Internal Catalog. +- The ENGINE must be set to OLAP when creating a table. +- Alter statements are not supported for modifying temporary tables. +- Due to their temporary nature, creating views and materialized views based on temporary tables is not supported. +- Temporary tables cannot be backed up and are not supported for synchronization using CCR/Sync Job. +- Export, Stream Load, Broker Load, S3 Load, MySQL Load, Routine Load, and Spark Load are not supported. +- When a temporary table is deleted, it does not go to the recycle bin but is permanently deleted immediately. \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/table-design/temporary-table.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/table-design/temporary-table.md new file mode 100644 index 0000000000000..d505a13110581 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/table-design/temporary-table.md @@ -0,0 +1,60 @@ +--- +title: 临时表 +language: zh-CN +--- + + + +在进行复杂的数据处理任务时，将大型 SQL 查询拆分为多个步骤，并将每个步骤的计算结果临时保存为实体表，是一种有效的策略。这种方法能够显著降低 SQL 查询的复杂度，并提升数据的可调试性。然而，需要注意的是，实体表在完成其使用目的后，需要手动进行清理。若选择使用非实体临时表，当前 Doris 仅支持通过 `WITH` 子句进行定义。 + +为了解决上述问题，Doris 引入了临时表功能。临时表是一种临时存在的物化内表，具备以下关键特性： +1. **会话绑定**：临时表仅存在于创建它的会话（Session）中。其生命周期与当前会话紧密绑定，即当会话结束时，该会话中创建的临时表会自动被删除。 + +2. **会话内可见性**：临时表的可见性严格限制在创建它的会话范围内。即使在同一时间由同一用户启动的另一个会话，也无法访问这些临时表。 + +通过引入临时表功能，Doris 不仅简化了复杂数据处理过程中的临时数据存储与管理，还进一步增强了数据处理的灵活性和安全性。 + + +:::info 备注 + +与内表类似，临时表必须在 Internal Catalog 内的某个 Database 下创建。但由于临时表基于 Session，因此其命名不受唯一性约束。您可以在不同 Session 中创建同名临时表，或创建与其他内表同名的临时表。 + +如果同一 Database 中同时存在同名的临时表和非临时表，临时表具有最高访问优先级。在该 Session 内，所有针对同名表的查询和操作仅对临时表生效（除创建物化视图外）。 +::: + +## 用法 + +### 创建临时表 +各种模型的表都可以被定义为临时表， 不论是 Unique、Aggregate 或是 Duplicate 模型。可以在下列 SQL 中添加 TEMPORARY 关键字创建临时表： +- [CREATE TABLE](../sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE) +- [CREATE TABLE AS SELECT](../sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-AS-SELECT) +- [CREATE TABLE LIKE](../sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE-LIKE) + +临时表的其它用法基本和普通内表相同。除上述 Create 语句外， 其它 DDL 及 DML 语句无需添加 TEMPORARY 关键字。 + +## 注意事项 + +- 临时表只能在 Internal Catalog 中创建 +- 建表时 `ENGINE` 必须为 `OLAP` +- 不支持使用 Alter 语句修改临时表 +- 由于临时性，不支持基于临时表创建视图和物化视图 +- 不支持备份临时表，不支持使用 CCR / Sync Job 同步临时表 +- 不支持导出、Stream Load、Broker Load、S3 Load、Mysql Load、Routine Load、Spark Load +- 删除临时表时，不进回收站，直接彻底删除 \ No newline at end of file