From eec568bd4000122ee88f5edd743bb37eb8a2d344 Mon Sep 17 00:00:00 2001 From: BohuTANG Date: Thu, 13 Nov 2025 14:18:32 +0800 Subject: [PATCH 1/3] docs: consolidate alter table --- docs/cn/guides/56-security/masking-policy.md | 4 +- .../57-data-management/01-data-lifecycle.md | 4 +- .../30-table-engines/00-fuse.md | 2 +- .../00-ddl/01-table/90-alter-table-column.md | 291 ---------------- .../00-ddl/01-table/90-alter-table-comment.md | 70 ---- .../00-ddl/01-table/90-alter-table-option.md | 97 ------ .../00-ddl/01-table/90-alter-table.md | 295 ++++++++++++++++ .../01-table/91-alter-table-connection.md | 94 ------ .../00-ddl/01-table/92-alter-table-swap.md | 48 --- .../10-sql-commands/00-ddl/01-table/index.md | 7 +- .../00-ddl/13-connection/create-connection.md | 2 +- .../00-ddl/14-transaction/show-locks.md | 4 +- .../10-dml/dml-copy-into-table.md | 4 +- docs/en/guides/56-security/masking-policy.md | 2 +- .../57-data-management/01-data-lifecycle.md | 2 +- .../30-table-engines/00-fuse.md | 2 +- .../00-ddl/01-table/90-alter-table-comment.md | 70 ---- .../00-ddl/01-table/90-alter-table-option.md | 96 ------ ...lter-table-column.md => 90-alter-table.md} | 318 ++++++++++++------ .../01-table/91-alter-table-connection.md | 94 ------ .../00-ddl/01-table/92-alter-table-swap.md | 48 --- .../10-sql-commands/00-ddl/01-table/index.md | 5 +- .../00-ddl/13-connection/create-connection.md | 2 +- .../00-ddl/14-transaction/show-locks.md | 4 +- .../10-dml/dml-copy-into-table.md | 2 +- site-redirects.ts | 41 +++ 26 files changed, 569 insertions(+), 1039 deletions(-) delete mode 100644 docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-column.md delete mode 100644 docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-comment.md delete mode 100644 docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-option.md create mode 100644 docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md delete mode 100644 docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/91-alter-table-connection.md delete mode 100644 docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/92-alter-table-swap.md delete mode 100644 docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-comment.md delete mode 100644 docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-option.md rename docs/en/sql-reference/10-sql-commands/00-ddl/01-table/{90-alter-table-column.md => 90-alter-table.md} (51%) delete mode 100644 docs/en/sql-reference/10-sql-commands/00-ddl/01-table/91-alter-table-connection.md delete mode 100644 docs/en/sql-reference/10-sql-commands/00-ddl/01-table/92-alter-table-swap.md diff --git a/docs/cn/guides/56-security/masking-policy.md b/docs/cn/guides/56-security/masking-policy.md index 526eadfb49..425e5d8f3e 100644 --- a/docs/cn/guides/56-security/masking-policy.md +++ b/docs/cn/guides/56-security/masking-policy.md @@ -85,5 +85,5 @@ SELECT * FROM user_info; 有关创建、修改和管理动态脱敏策略（Masking Policy）的详细命令，请查阅： - [CREATE MASKING POLICY](/sql/sql-commands/ddl/mask-policy/create-mask-policy) -- [ALTER TABLE COLUMN](/sql/sql-commands/ddl/table/alter-table-column) -- [Masking Policy Commands](/sql/sql-commands/ddl/mask-policy/) \ No newline at end of file +- [ALTER TABLE](/sql/sql-commands/ddl/table/alter-table#column-operations) +- [Masking Policy Commands](/sql/sql-commands/ddl/mask-policy/) diff --git a/docs/cn/guides/57-data-management/01-data-lifecycle.md b/docs/cn/guides/57-data-management/01-data-lifecycle.md index be30130bdd..bf5ed2221e 100644 --- a/docs/cn/guides/57-data-management/01-data-lifecycle.md +++ b/docs/cn/guides/57-data-management/01-data-lifecycle.md @@ -35,7 +35,7 @@ Databend 支持创建和修改以下对象： - [`CREATE DATABASE`](/sql/sql-commands/ddl/database/ddl-create-database) : 创建新数据库。 - [`ALTER DATABASE`](/sql/sql-commands/ddl/database/ddl-alter-database) : 修改现有数据库。 - [`CREATE TABLE`](/sql/sql-commands/ddl/table/ddl-create-table) : 创建新表。 -- [`ALTER TABLE`](/sql/sql-commands/ddl/table/alter-table-column) : 修改现有表。 +- [`ALTER TABLE`](/sql/sql-commands/ddl/table/alter-table) : 修改现有表。 ## 存储数据 @@ -73,4 +73,4 @@ Databend 允许删除特定数据或整个表和数据库。 - [`TRUNCATE TABLE`](/sql/sql-commands/ddl/table/ddl-truncate-table) : 清空表数据但保留表结构。 - [`DROP TABLE`](/sql/sql-commands/ddl/table/ddl-drop-table) : 删除表。 -- [`DROP DATABASE`](/sql/sql-commands/ddl/database/ddl-drop-database) : 删除数据库。 \ No newline at end of file +- [`DROP DATABASE`](/sql/sql-commands/ddl/database/ddl-drop-database) : 删除数据库。 diff --git a/docs/cn/sql-reference/00-sql-reference/30-table-engines/00-fuse.md b/docs/cn/sql-reference/00-sql-reference/30-table-engines/00-fuse.md index 489e461296..330a00ebce 100644 --- a/docs/cn/sql-reference/00-sql-reference/30-table-engines/00-fuse.md +++ b/docs/cn/sql-reference/00-sql-reference/30-table-engines/00-fuse.md @@ -61,7 +61,7 @@ CREATE TABLE ( Fuse Engine 提供了各种选项（不区分大小写），允许您自定义表的属性。 - 有关详细信息，请参见 [Fuse Engine Options](#fuse-engine-options)。 - 使用空格分隔多个选项。 - - 使用 [ALTER TABLE OPTION](../../10-sql-commands/00-ddl/01-table/90-alter-table-option.md) 修改表的选项。 + - 使用 [ALTER TABLE](../../10-sql-commands/00-ddl/01-table/90-alter-table.md#fuse-引擎选项) 修改表的选项。 - 使用 [SHOW CREATE TABLE](../../10-sql-commands/00-ddl/01-table/show-create-table.md) 显示表的选项。 --- diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-column.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-column.md deleted file mode 100644 index f704d85480..0000000000 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-column.md +++ /dev/null @@ -1,291 +0,0 @@ ---- -title: ALTER TABLE COLUMN -sidebar_position: 4 ---- - -import FunctionDescription from '@site/src/components/FunctionDescription'; - - - -import EEFeature from '@site/src/components/EEFeature'; - - - -通过添加、转换、重命名、更改或删除列来修改表。 - -## 语法 - -```sql --- 在表末尾添加一列 -ALTER TABLE [ IF EXISTS ] [ . ] -ADD [ COLUMN ] [ NOT NULL | NULL ] [ DEFAULT ] - --- 在指定位置添加一列 -ALTER TABLE [ IF EXISTS ] [ . ] -ADD [ COLUMN ] [ NOT NULL | NULL ] [ DEFAULT ] [ FIRST | AFTER ] - --- 添加一个虚拟计算列 -ALTER TABLE [ IF EXISTS ] [ . ] -ADD [ COLUMN ] AS () VIRTUAL - --- 将存储计算列转换为常规列 -ALTER TABLE [ IF EXISTS ] [ . ] -MODIFY [ COLUMN ] DROP STORED - --- 重命名列 -ALTER TABLE [ IF EXISTS ] [ . ] -RENAME [ COLUMN ] TO - --- 更改数据类型 -ALTER TABLE [ IF EXISTS ] [ . ] -MODIFY [ COLUMN ] [ DEFAULT ] - [ , [ COLUMN ] [ DEFAULT ] ] - ... - --- 更改注释 -ALTER TABLE [ IF EXISTS ] [ . ] -MODIFY [ COLUMN ] [ COMMENT '' ] -[ , [ COLUMN ] [ COMMENT '' ] ] -... - --- 为列设置/取消设置脱敏策略 -ALTER TABLE [ IF EXISTS ] [ . ] -MODIFY [ COLUMN ] SET MASKING POLICY - -ALTER TABLE [ IF EXISTS ] [ . ] -MODIFY [ COLUMN ] UNSET MASKING POLICY - --- 删除一列 -ALTER TABLE [ IF EXISTS ] [ . ] -DROP [ COLUMN ] -``` - -:::note -- 在添加或修改列时，仅接受常量值作为默认值。如果使用非常量表达式，将会报错。 -- 尚不支持使用 ALTER TABLE 添加存储计算列。 -- 当更改表列的数据类型（Data Type）时，存在转换错误的风险。例如，如果尝试将文本（String）列转换为数字（Float）列，可能会引发问题。 -- 当为列设置脱敏策略（Masking Policy）时，请确保策略中定义的数据类型（请参考 [CREATE MASKING POLICY](../12-mask-policy/create-mask-policy.md) 语法中的 *arg_type_to_mask* 参数）与列的数据类型相匹配。 -- 如果策略需要额外的列，可结合 `USING` 子句使用，按照参数顺序列出对应的列；第一个参数始终代表正在脱敏的列。 -- 当声明了 `USING (...)` 时，必须至少提供被脱敏的列以及策略所需的其他列，并确保 `USING` 中的第一个标识符与正在修改的列一致。 -- 只有常规表支持绑定脱敏策略；视图、流表以及临时表均无法执行 `SET MASKING POLICY`。 -- 单个列最多只能附加一个安全策略（无论是列脱敏还是行级策略）。在重新绑定之前，请先移除原有策略。 -::: - -:::caution -如果列已绑定脱敏策略，修改列定义或删除该列前必须先执行 `ALTER TABLE ... MODIFY COLUMN UNSET MASKING POLICY`，否则操作会因安全策略仍然生效而失败。 -::: - -## 示例 - -### 示例 1：添加、重命名和删除列 - -本示例演示了如何创建一个名为 "default.users" 的表，该表包含 'username'、'email' 和 'age' 列。示例展示了如何添加具有不同约束的 'id' 和 'middle_name' 列，并演示了如何重命名和删除 "age" 列。 - -```sql --- 创建一个表 -CREATE TABLE default.users ( - username VARCHAR(50) NOT NULL, - email VARCHAR(255), - age INT -); - --- 在表末尾添加一列 -ALTER TABLE default.users -ADD COLUMN business_email VARCHAR(255) NOT NULL DEFAULT 'example@example.com'; - -DESC default.users; - -Field |Type |Null|Default |Extra| ---------------+-------+----+---------------------+-----+ -username |VARCHAR|NO |'' | | -email |VARCHAR|YES |NULL | | -age |INT |YES |NULL | | -business_email|VARCHAR|NO |'example@example.com'| | - --- 在表开头添加一列 -ALTER TABLE default.users -ADD COLUMN id int NOT NULL FIRST; - -DESC default.users; - -Field |Type |Null|Default |Extra| ---------------+-------+----+---------------------+-----+ -id |INT |NO |0 | | -username |VARCHAR|NO |'' | | -email |VARCHAR|YES |NULL | | -age |INT |YES |NULL | | -business_email|VARCHAR|NO |'example@example.com'| | - --- 在 'username' 列后添加一列 -ALTER TABLE default.users -ADD COLUMN middle_name VARCHAR(50) NULL AFTER username; - -DESC default.users; - -Field |Type |Null|Default |Extra| ---------------+-------+----+---------------------+-----+ -id |INT |NO |0 | | -username |VARCHAR|NO |'' | | -middle_name |VARCHAR|YES |NULL | | -email |VARCHAR|YES |NULL | | -age |INT |YES |NULL | | -business_email|VARCHAR|NO |'example@example.com'| | - --- 重命名一列 -ALTER TABLE default.users -RENAME COLUMN age TO new_age; - -DESC default.users; - -Field |Type |Null|Default |Extra| ---------------+-------+----+---------------------+-----+ -id |INT |NO |0 | | -username |VARCHAR|NO |'' | | -middle_name |VARCHAR|YES |NULL | | -email |VARCHAR|YES |NULL | | -new_age |INT |YES |NULL | | -business_email|VARCHAR|NO |'example@example.com'| | - --- 删除一列 -ALTER TABLE default.users -DROP COLUMN new_age; - -DESC default.users; - -Field |Type |Null|Default |Extra| ---------------+-------+----+---------------------+-----+ -id |INT |NO |0 | | -username |VARCHAR|NO |'' | | -middle_name |VARCHAR|YES |NULL | | -email |VARCHAR|YES |NULL | | -business_email|VARCHAR|NO |'example@example.com'| | -``` - -### 示例 2：添加计算列 - -本示例演示了如何创建一个用于存储员工信息的表，向表中插入数据，并添加一个计算列，根据员工的出生年份计算其年龄。 - -```sql --- 创建一个表 -CREATE TABLE Employees ( - ID INT, - Name VARCHAR(50), - BirthYear INT -); - --- 插入数据 -INSERT INTO Employees (ID, Name, BirthYear) -VALUES - (1, 'John Doe', 1990), - (2, 'Jane Smith', 1985), - (3, 'Robert Johnson', 1982); - --- 添加一个名为 Age 的计算列 -ALTER TABLE Employees -ADD COLUMN Age INT64 AS (2023 - BirthYear) VIRTUAL; - -SELECT * FROM Employees; - -ID | Name | BirthYear | Age ------------------------------------- -1 | John Doe | 1990 | 33 -2 | Jane Smith | 1985 | 38 -3 | Robert Johnson| 1982 | 41 -``` - -### 示例 3：转换计算列 - -本示例创建了一个名为 "products" 的表，包含 ID、price、quantity 列和一个计算列 "total_price"。ALTER TABLE 语句移除了 "total_price" 列的计算功能，将其转换为一个常规列。 - -```sql -CREATE TABLE IF NOT EXISTS products ( - id INT, - price FLOAT64, - quantity INT, - total_price FLOAT64 AS (price * quantity) STORED -); - -ALTER TABLE products -MODIFY COLUMN total_price DROP STORED; -``` - -### 示例 4：更改列的数据类型 - -本示例演示了如何修改列的数据类型并为其添加注释。 - -```sql -CREATE TABLE students_info ( - id INT, - name VARCHAR(50), - age INT -); - --- 将 'age' 列的数据类型更改为 VARCHAR，默认值为 '0' -ALTER TABLE students_info MODIFY COLUMN age VARCHAR(10) DEFAULT '0'; - -SHOW CREATE TABLE students_info; - -┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ -│ Table │ Create Table │ -├───────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤ -│ students_info │ CREATE TABLE students_info (\n id INT NULL,\n name VARCHAR NULL,\n age VARCHAR NULL DEFAULT '0'\n) ENGINE=FUSE │ -└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ - --- 为 'age' 列添加注释 -ALTER TABLE students_info MODIFY COLUMN age COMMENT 'abc'; - -SHOW CREATE TABLE students_info; - -┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ -│ Table │ Create Table │ -├───────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤ -│ students_info │ CREATE TABLE students_info (\n id INT NULL,\n name VARCHAR NULL,\n age VARCHAR NULL DEFAULT '0' COMMENT 'abc'\n) ENGINE=FUSE │ -└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ -``` - -### 示例 5：为列设置脱敏策略 - -本示例演示了如何设置脱敏策略（Masking Policy），以根据用户角色选择性地显示或屏蔽敏感数据。 - -```sql --- 创建表并插入示例数据 -CREATE TABLE user_info ( - id INT, - email STRING -); - -INSERT INTO user_info (id, email) VALUES (1, 'sue@example.com'); -INSERT INTO user_info (id, email) VALUES (2, 'eric@example.com'); - --- 创建一个角色 -CREATE ROLE 'MANAGERS'; -GRANT ALL ON *.* TO ROLE 'MANAGERS'; - --- 创建一个用户并授予角色 -CREATE USER manager_user IDENTIFIED BY 'databend'; -GRANT ROLE 'MANAGERS' TO 'manager_user'; - --- 创建一个脱敏策略 -CREATE MASKING POLICY email_mask -AS - (val string) - RETURNS string -> - CASE - WHEN current_role() IN ('MANAGERS') THEN - val - ELSE - '*********' - END - COMMENT = 'hide_email'; - --- 将脱敏策略与 'email' 列关联 -ALTER TABLE user_info MODIFY COLUMN email SET MASKING POLICY email_mask; - --- 使用 Root 用户查询 -SELECT * FROM user_info; - -id|email | ---+---------+ - 2|*********| - 1|*********| -``` diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-comment.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-comment.md deleted file mode 100644 index 3186caf2ad..0000000000 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-comment.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: ALTER TABLE COMMENT -sidebar_position: 4 ---- -import FunctionDescription from '@site/src/components/FunctionDescription'; - - - -修改表的注释。如果表还没有注释，此命令会将指定的注释添加到表中。 - -## 语法 - -```sql -ALTER TABLE [ IF EXISTS ] [ . ] -COMMENT = '' -``` - -## 示例 - -此示例创建一个带有注释的表，然后在之后修改注释： - -```sql --- 创建一个带有注释的表 -CREATE TABLE t(id INT) COMMENT ='original-comment'; - -SHOW CREATE TABLE t; - -┌──────────────────────────────────────────────────────────────────────────────────────┐ -│ Table │ Create Table │ -├────────┼─────────────────────────────────────────────────────────────────────────────┤ -│ t │ CREATE TABLE t (\n id INT NULL\n) ENGINE=FUSE COMMENT = 'original-comment' │ -└──────────────────────────────────────────────────────────────────────────────────────┘ - --- 修改注释 -ALTER TABLE t COMMENT = 'new-comment'; - -SHOW CREATE TABLE t; - -┌─────────────────────────────────────────────────────────────────────────────────┐ -│ Table │ Create Table │ -├────────┼────────────────────────────────────────────────────────────────────────┤ -│ t │ CREATE TABLE t (\n id INT NULL\n) ENGINE=FUSE COMMENT = 'new-comment' │ -└─────────────────────────────────────────────────────────────────────────────────┘ -``` - -此示例创建一个没有注释的表，然后在之后向表中添加注释： - -```sql --- 创建一个没有注释的表 -CREATE TABLE t(id INT); - -SHOW CREATE TABLE t; - -┌─────────────────────────────────────────────────────────┐ -│ Table │ Create Table │ -├────────┼────────────────────────────────────────────────┤ -│ t │ CREATE TABLE t (\n id INT NULL\n) ENGINE=FUSE │ -└─────────────────────────────────────────────────────────┘ - --- 添加注释 -ALTER TABLE t COMMENT = 'new-comment'; - -SHOW CREATE TABLE t; - -┌─────────────────────────────────────────────────────────────────────────────────┐ -│ Table │ Create Table │ -├────────┼────────────────────────────────────────────────────────────────────────┤ -│ t │ CREATE TABLE t (\n id INT NULL\n) ENGINE=FUSE COMMENT = 'new-comment' │ -└─────────────────────────────────────────────────────────────────────────────────┘ -``` \ No newline at end of file diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-option.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-option.md deleted file mode 100644 index 46371312c0..0000000000 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-option.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: ALTER TABLE OPTIONS -sidebar_position: 5 ---- -import FunctionDescription from '@site/src/components/FunctionDescription'; - - - -设置或取消表的 [Fuse Engine 选项](../../../00-sql-reference/30-table-engines/00-fuse.md#fuse-engine-options)。 - -## 语法 - -```sql --- 设置 Fuse Engine 选项 -ALTER TABLE [ . ] SET OPTIONS () - --- 取消设置 Fuse Engine 选项，将其恢复为默认值 -ALTER TABLE [ . ] UNSET OPTIONS () -``` - -请注意，只能取消设置以下 Fuse Engine 选项： - -- `block_per_segment` -- `block_size_threshold` -- `data_retention_period_in_hours` -- `data_retention_num_snapshots_to_keep` -- `row_avg_depth_threshold` -- `row_per_block` -- `row_per_page` - -## 示例 - -### 设置 Fuse Engine 选项 - -以下示例演示如何设置 Fuse Engine 选项，并通过 [SHOW CREATE TABLE](show-create-table.md) 验证更改： - -```sql -CREATE TABLE fuse_table (a int); - -SET hide_options_in_show_create_table=0; - --- 显示当前的 CREATE TABLE 语句，包括 Fuse Engine 选项 -SHOW CREATE TABLE fuse_table; - --[ RECORD 1 ]----------------------------------- - Table: fuse_table -Create Table: CREATE TABLE fuse_table ( - a INT NULL -) ENGINE=FUSE COMPRESSION='lz4' STORAGE_FORMAT='native' - --- 将段中的最大块数更改为 500 --- 将数据保留期限更改为 240 小时 -ALTER TABLE fuse_table SET OPTIONS (block_per_segment = 500, data_retention_period_in_hours = 240); - --- 显示更新后的 CREATE TABLE 语句，反映新的选项 -SHOW CREATE TABLE fuse_table; - --[ RECORD 1 ]----------------------------------- - Table: fuse_table -Create Table: CREATE TABLE fuse_table ( - a INT NULL -) ENGINE=FUSE BLOCK_PER_SEGMENT='500' COMPRESSION='lz4' DATA_RETENTION_PERIOD_IN_HOURS='240' STORAGE_FORMAT='native' -``` - -以下示例演示如何将 `data_retention_num_snapshots_to_keep` 选项与 `enable_auto_vacuum` 一起使用： - -```sql --- 创建新表 -CREATE OR REPLACE TABLE t(c INT); - --- 设置表仅保留最新的快照 -ALTER TABLE t SET OPTIONS(data_retention_num_snapshots_to_keep = 1); - --- 启用自动清理以触发快照清理 -SET enable_auto_vacuum = 1; - --- 在每次操作之后，只会保留一个快照 -INSERT INTO t VALUES(1); -INSERT INTO t VALUES(2); -INSERT INTO t VALUES(3); -``` - -### 取消设置 Fuse Engine 选项 - -以下示例演示如何取消设置 Fuse Engine 选项，将其恢复为默认值： - -```sql -ALTER TABLE fuse_table UNSET OPTIONS (block_per_segment, data_retention_period_in_hours); - -SHOW CREATE TABLE fuse_table; - --[ RECORD 1 ]----------------------------------- - Table: fuse_table -Create Table: CREATE TABLE fuse_table ( - a INT NULL -) ENGINE=FUSE COMPRESSION='lz4' STORAGE_FORMAT='native' -``` \ No newline at end of file diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md new file mode 100644 index 0000000000..8c9f4ad588 --- /dev/null +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md @@ -0,0 +1,295 @@ +--- +title: ALTER TABLE +sidebar_position: 4 +slug: /cn/sql/sql-commands/ddl/table/alter-table +--- + +import FunctionDescription from '@site/src/components/FunctionDescription'; + + + +import EEFeature from '@site/src/components/EEFeature'; + +`ALTER TABLE` 可用于修改现有表的列、注释、Fuse 引擎选项、外部连接等属性，甚至可以与另一张表互换所有元数据。下列小节按能力进行划分。 + +## 列操作 {#column-operations} + + + +通过添加、转换、重命名、更改或删除列来修改表。 + +### 语法 + +```sql +-- 在表末尾添加一列 +ALTER TABLE [ IF EXISTS ] [ . ] +ADD [ COLUMN ] [ NOT NULL | NULL ] [ DEFAULT ] + +-- 在指定位置添加一列 +ALTER TABLE [ IF EXISTS ] [ . ] +ADD [ COLUMN ] [ NOT NULL | NULL ] [ DEFAULT ] [ FIRST | AFTER ] + +-- 添加一个虚拟计算列 +ALTER TABLE [ IF EXISTS ] [ . ] +ADD [ COLUMN ] AS () VIRTUAL + +-- 将存储计算列转换为常规列 +ALTER TABLE [ IF EXISTS ] [ . ] +MODIFY [ COLUMN ] DROP STORED + +-- 重命名列 +ALTER TABLE [ IF EXISTS ] [ . ] +RENAME [ COLUMN ] TO + +-- 更改数据类型 +ALTER TABLE [ IF EXISTS ] [ . ] +MODIFY [ COLUMN ] [ DEFAULT ] + [ , [ COLUMN ] [ DEFAULT ] ] + ... + +-- 更改注释 +ALTER TABLE [ IF EXISTS ] [ . ] +MODIFY [ COLUMN ] [ COMMENT '' ] +[ , [ COLUMN ] [ COMMENT '' ] ] +... + +-- 为列设置/取消设置脱敏策略 +ALTER TABLE [ IF EXISTS ] [ . ] +MODIFY [ COLUMN ] SET MASKING POLICY + [ USING ( [ , ... ] ) ] + +ALTER TABLE [ IF EXISTS ] [ . ] +MODIFY [ COLUMN ] UNSET MASKING POLICY + +-- 删除一列 +ALTER TABLE [ IF EXISTS ] [ . ] +DROP [ COLUMN ] +``` + +:::note +- 在添加或修改列时，仅接受常量值作为默认值。如果使用非常量表达式，将会报错。 +- 尚不支持使用 ALTER TABLE 添加存储计算列。 +- 当更改表列的数据类型时，存在转换错误的风险。例如，如果尝试将文本（String）列转换为数字（Float）列，可能会引发问题。 +- 当为列设置脱敏策略时，请确保策略中定义的数据类型（请参考 [CREATE MASKING POLICY](../12-mask-policy/create-mask-policy.md) 语法中的 *arg_type_to_mask* 参数）与列的数据类型相匹配。 +- 如果策略需要额外的列，可结合 `USING` 子句使用，按照参数顺序列出对应的列；第一个参数始终代表正在脱敏的列。 +- 当声明了 `USING (...)` 时，必须至少提供被脱敏的列以及策略所需的其他列，并确保 `USING` 中的第一个标识符与正在修改的列一致。 +- 只有常规表支持绑定脱敏策略；视图、流表以及临时表均无法执行 `SET MASKING POLICY`。 +- 单个列最多只能附加一个安全策略（无论是列脱敏还是行级策略）。在重新绑定之前，请先移除原有策略。 +::: + +:::caution +如果列已绑定脱敏策略，修改列定义或删除该列前必须先执行 `ALTER TABLE ... MODIFY COLUMN UNSET MASKING POLICY`，否则操作会因安全策略仍然生效而失败。 +::: + +### 示例 + +#### 示例 1：添加、重命名和删除列 + +```sql +CREATE TABLE default.users ( + username VARCHAR(50) NOT NULL, + email VARCHAR(255), + age INT +); + +ALTER TABLE default.users +ADD COLUMN business_email VARCHAR(255) NOT NULL DEFAULT 'example@example.com'; + +ALTER TABLE default.users +ADD COLUMN id int NOT NULL FIRST; + +ALTER TABLE default.users +ADD COLUMN middle_name VARCHAR(50) NULL AFTER username; + +ALTER TABLE default.users +RENAME COLUMN age TO new_age; + +ALTER TABLE default.users +DROP COLUMN new_age; +``` + +#### 示例 2：修改列与脱敏策略 + +```sql +ALTER TABLE users +MODIFY COLUMN age BIGINT DEFAULT 18, + COLUMN email VARCHAR(320) DEFAULT ''; + +ALTER TABLE users +MODIFY COLUMN email SET MASKING POLICY pii_email USING (email, username); + +ALTER TABLE users +MODIFY COLUMN email UNSET MASKING POLICY; +``` + +## 表注释 {#table-comment} + +用于修改表的注释。如果表尚未设置注释，该命令会为表添加指定的注释。 + +### 语法 + +```sql +ALTER TABLE [ IF EXISTS ] [ . ] +COMMENT = '' +``` + +### 示例 + +```sql +CREATE TABLE t(id INT) COMMENT ='original-comment'; +ALTER TABLE t COMMENT = 'new-comment'; + +CREATE TABLE s(id INT); +ALTER TABLE s COMMENT = 'new-comment'; +``` + +## Fuse 引擎选项 {#fuse-engine-options} + +用于设置或取消设置表的 [Fuse 引擎选项](../../../00-sql-reference/30-table-engines/00-fuse.md#fuse-engine-options)。 + +### 语法 + +```sql +ALTER TABLE [ . ] SET OPTIONS () +ALTER TABLE [ . ] UNSET OPTIONS () +``` + +可以取消设置的 Fuse 引擎选项包括： + +- `block_per_segment` +- `block_size_threshold` +- `data_retention_period_in_hours` +- `data_retention_num_snapshots_to_keep` +- `row_avg_depth_threshold` +- `row_per_block` +- `row_per_page` + +### 示例 + +```sql +CREATE TABLE fuse_table (a int); +SET hide_options_in_show_create_table=0; +SHOW CREATE TABLE fuse_table; + +ALTER TABLE fuse_table SET OPTIONS (block_per_segment = 500, data_retention_period_in_hours = 240); +SHOW CREATE TABLE fuse_table; +``` + +```sql +CREATE OR REPLACE TABLE t(c INT); +ALTER TABLE t SET OPTIONS(data_retention_num_snapshots_to_keep = 1); +SET enable_auto_vacuum = 1; +INSERT INTO t VALUES(1); +INSERT INTO t VALUES(2); +INSERT INTO t VALUES(3); + +ALTER TABLE fuse_table UNSET OPTIONS (block_per_segment, data_retention_period_in_hours); +``` + +## 外部表连接 {#external-table-connection} + +更新外部表的连接设置。执行命令时，仅凭证相关字段（`access_key_id`、`secret_access_key`、`role_arn`）会被应用，`bucket`、`region`、`root` 等其他属性保持不变。 + +### 语法 + +```sql +ALTER TABLE [ . ] CONNECTION = ( connection_name = '' ) +``` + +| 参数 | 说明 | 是否必需 | +|------|------|----------| +| connection_name | 要用于该外部表的连接名称，必须是系统中已存在的连接。 | 是 | + +该命令适用于凭证轮换或 IAM 角色变更场景。在执行之前，目标连接必须已经创建。 + +**安全最佳实践** + +- 无需存储访问密钥，避免泄露风险。 +- 自动轮换凭证，减少人工维护。 +- 具备更细粒度的访问控制能力。 + +如需在 Databend Cloud 中使用 IAM 角色，请参阅 [Authenticate with AWS IAM Role](/guides/cloud/advanced/iam-role)。 + +### 示例 + +```sql +CREATE CONNECTION external_table_conn + STORAGE_TYPE = 's3' + ACCESS_KEY_ID = '' + SECRET_ACCESS_KEY = ''; + +CREATE CONNECTION external_table_conn_new + STORAGE_TYPE = 's3' + ACCESS_KEY_ID = '' + SECRET_ACCESS_KEY = ''; + +CREATE OR REPLACE TABLE external_table_test ( + id INT, + name VARCHAR, + age INT +) +'s3://testbucket/13_fuse_external_table/' +CONNECTION=(connection_name = 'external_table_conn'); + +ALTER TABLE external_table_test CONNECTION=( connection_name = 'external_table_conn_new' ); +``` + +```sql +CREATE CONNECTION s3_access_key_conn + STORAGE_TYPE = 's3' + ACCESS_KEY_ID = '' + SECRET_ACCESS_KEY = ''; + +CREATE TABLE sales_data ( + order_id INT, + product_name VARCHAR, + quantity INT +) +'s3://sales-bucket/data/' +CONNECTION=(connection_name = 's3_access_key_conn'); + +CREATE CONNECTION s3_role_conn + STORAGE_TYPE = 's3' + ROLE_ARN = 'arn:aws:iam::123456789012:role/databend-access'; + +ALTER TABLE sales_data CONNECTION=( connection_name = 's3_role_conn' ); +``` + +## 交换表 {#swap-tables} + +在同一个事务中交换两张表的所有元数据和数据，使双方的列、约束以及数据完全互换。 + +### 语法 + +```sql +ALTER TABLE [ IF EXISTS ] SWAP WITH +``` + +| 参数 | 说明 | +|------|------| +| `source_table_name` | 要交换的第一张表 | +| `target_table_name` | 要交换的第二张表 | + +### 使用说明 + +- 仅支持 Fuse 引擎表，外部表、系统表等其他类型不支持。 +- 临时表无法与永久表或瞬态表交换。 +- 当前角色必须同时拥有两张表的所有权。 +- 两张表必须位于同一个数据库，无法跨库交换。 +- 操作为原子事务，要么全部成功，要么全部回滚。 +- 操作不会丢失数据，双方的数据与元数据都会被完整保留。 + +### 示例 + +```sql +CREATE OR REPLACE TABLE t1(a1 INT, a2 VARCHAR, a3 DATE); +CREATE OR REPLACE TABLE t2(b1 VARCHAR); + +DESC t1; +DESC t2; + +ALTER TABLE t1 SWAP WITH t2; + +DESC t1; +DESC t2; +``` diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/91-alter-table-connection.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/91-alter-table-connection.md deleted file mode 100644 index e3f89ccc6c..0000000000 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/91-alter-table-connection.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: ALTER TABLE CONNECTION -sidebar_position: 6 ---- -import FunctionDescription from '@site/src/components/FunctionDescription'; - - - -更新外部表的连接设置。 - -## 语法 - -```sql -ALTER TABLE [ . ] CONNECTION = ( connection_name = '' ) -``` - -| 参数 | 描述 | 必需 | -|------------------|----------------------------------------------------------------------|------| -| connection_name | 用于外部表的连接名称。该连接必须在系统中已存在。 | 是 | - -## 使用说明 - -使用 ALTER TABLE CONNECTION 命令时，仅能更改与凭据相关的设置，包括 `access_key_id`、`secret_access_key` 和 `role_arn`。对其他连接参数（如 `bucket`、`region` 或 `root`）的更改将被忽略。 - -此命令在需要轮换凭据或 IAM 角色变更时特别有用。指定的连接必须在系统中已存在，才能与此命令配合使用。 - -## 安全最佳实践 - -使用外部表时，AWS IAM 角色相比访问密钥具有显著安全优势： - -- **无存储凭据**：无需在配置中存储访问密钥 -- **自动轮换**：自动处理凭据轮换 -- **细粒度控制**：支持更精确的访问控制 - -要在 Databend Cloud 中使用 IAM 角色，请参阅[使用 AWS IAM 角色进行认证](/guides/cloud/advanced/iam-role)获取指南。 - -## 示例 - -### 更新外部表的连接 - -此示例创建一个使用初始连接的外部表，然后更新为使用不同连接： - -```sql --- 创建两个使用不同凭据的连接 -CREATE CONNECTION external_table_conn - STORAGE_TYPE = 's3' - ACCESS_KEY_ID = '' - SECRET_ACCESS_KEY = ''; - -CREATE CONNECTION external_table_conn_new - STORAGE_TYPE = 's3' - ACCESS_KEY_ID = '' - SECRET_ACCESS_KEY = ''; - --- 使用第一个连接创建外部表 -CREATE OR REPLACE TABLE external_table_test ( - id INT, - name VARCHAR, - age INT -) -'s3://testbucket/13_fuse_external_table/' -CONNECTION=(connection_name = 'external_table_conn'); - --- 更新表以使用包含轮换凭据的新连接 -ALTER TABLE external_table_test CONNECTION=( connection_name = 'external_table_conn_new' ); -``` - -### 使用 IAM 角色更新外部表连接 - -此示例展示从访问密钥身份验证迁移到 IAM 角色身份验证： - -```sql --- 使用访问密钥身份验证创建外部表 -CREATE CONNECTION s3_access_key_conn - STORAGE_TYPE = 's3' - ACCESS_KEY_ID = '' - SECRET_ACCESS_KEY = ''; - -CREATE TABLE sales_data ( - order_id INT, - product_name VARCHAR, - quantity INT -) -'s3://sales-bucket/data/' -CONNECTION=(connection_name = 's3_access_key_conn'); - --- 稍后，使用 IAM 角色身份验证创建新连接 -CREATE CONNECTION s3_role_conn - STORAGE_TYPE = 's3' - ROLE_ARN = 'arn:aws:iam::123456789012:role/databend-access'; - --- 更新表以使用 IAM 角色连接 -ALTER TABLE sales_data CONNECTION=( connection_name = 's3_role_conn' ); -``` diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/92-alter-table-swap.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/92-alter-table-swap.md deleted file mode 100644 index 14d25cc615..0000000000 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/92-alter-table-swap.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: ALTER TABLE SWAP WITH -sidebar_position: 5 ---- -import FunctionDescription from '@site/src/components/FunctionDescription'; - - - -在单个事务（Transaction）中原子地交换两个表的所有元数据和数据。此操作会交换表结构（schema），包括所有列、约束和数据，从而有效地使每个表承担另一个表的身份。 - -## 语法 - -```sql -ALTER TABLE [ IF EXISTS ] SWAP WITH -``` - -| 参数 | 说明 | -|----------------------|------------------------------------------------| -| `source_table_name` | 要交换的第一个表的名称 | -| `target_table_name` | 要与之交换的第二个表的名称 | - -## 使用说明 - -- **引擎支持**：仅适用于 Fuse 引擎表。不支持外部表、系统表和其他非 Fuse 表。 -- **表类型**：临时表不能与永久表或瞬时表交换。 -- **权限**：当前角色必须是两个表的所有者才能执行交换操作。 -- **数据库范围**：两个表必须在同一个数据库中。不支持跨数据库交换。 -- **原子性**：交换操作是原子性的。要么两个表都成功交换，要么两个表都不变。 -- **数据保留**：交换期间会保留所有数据和元数据。不会丢失或修改任何数据。 - -## 示例 - -```sql --- 创建两个具有不同表结构的表 -CREATE OR REPLACE TABLE t1(a1 INT, a2 VARCHAR, a3 DATE); -CREATE OR REPLACE TABLE t2(b1 VARCHAR); - --- 交换前检查表结构 -DESC t1; -DESC t2; - --- 交换表 -ALTER TABLE t1 SWAP WITH t2; - --- 交换后，t1 拥有 t2 的表结构，t2 拥有 t1 的表结构 -DESC t1; -DESC t2; -``` \ No newline at end of file diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/index.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/index.md index 70a7712a88..99c35616b0 100644 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/index.md +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/index.md @@ -19,10 +19,7 @@ title: 表 | 命令 | 描述 | |---------|-------------| -| [ALTER TABLE COLUMN](90-alter-table-column.md) | 通过更改列来修改表结构 | -| [ALTER TABLE CONNECTION](91-alter-table-connection.md) | 更新外部表的连接设置 | -| [ALTER TABLE OPTION](90-alter-table-option.md) | 修改表的 Fuse 引擎选项 | -| [ALTER TABLE COMMENT](90-alter-table-comment.md) | 更新表的注释 | +| [ALTER TABLE](90-alter-table.md) | 修改表的列、注释、Fuse 选项、外部连接，或与另一张表交换元数据 | | [RENAME TABLE](30-ddl-rename-table.md) | 更改表名 | ## 查看表信息 @@ -54,4 +51,4 @@ title: 表 :::note 表优化属于高级操作，执行前请务必仔细阅读文档，避免潜在数据丢失。 -::: \ No newline at end of file +::: diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/13-connection/create-connection.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/13-connection/create-connection.md index fd6db47af9..c4a0022d12 100644 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/13-connection/create-connection.md +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/13-connection/create-connection.md @@ -146,7 +146,7 @@ CREATE CONNECTION ## 更新已存在表的连接 -若要将现有外部表切换到新的连接，可使用 [`ALTER TABLE ... CONNECTION`](/sql/sql-commands/ddl/table/alter-table-connection) 命令，无需重新创建表。 +若要将现有外部表切换到新的连接，可使用 [`ALTER TABLE ... CONNECTION`](/sql/sql-commands/ddl/table/alter-table#external-table-connection) 命令，无需重新创建表。 ## 示例 diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/14-transaction/show-locks.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/14-transaction/show-locks.md index 39224aec61..a4742ba03a 100644 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/14-transaction/show-locks.md +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/14-transaction/show-locks.md @@ -7,7 +7,7 @@ import FunctionDescription from '@site/src/components/FunctionDescription'; 提供当前用户在其所有会话中或 Databend 系统中所有用户当前持有表锁的活动事务的列表。锁是一种同步机制，用于限制对共享资源（如表）的访问，确保 Databend 系统中进程或线程之间的有序和受控交互，以维护数据一致性并防止冲突。 -[UPDATE](../../10-dml/dml-update.md)、[DELETE](../../10-dml/dml-delete-from.md)、[OPTIMIZE TABLE](../01-table/60-optimize-table.md)、[RECLUSTER TABLE](../06-clusterkey/dml-recluster-table.md) 和 [ALTER TABLE COLUMN](../01-table/90-alter-table-column.md) 等操作可能会导致系统中的表锁。默认情况下启用表锁功能。如果发生资源冲突，您可以使用该命令检查具体细节。要禁用此功能，请执行 `set enable_table_lock=0;`。 +[UPDATE](../../10-dml/dml-update.md)、[DELETE](../../10-dml/dml-delete-from.md)、[OPTIMIZE TABLE](../01-table/60-optimize-table.md)、[RECLUSTER TABLE](../06-clusterkey/dml-recluster-table.md) 和 [ALTER TABLE](../01-table/90-alter-table.md#column-operations) 等操作可能会导致系统中的表锁。默认情况下启用表锁功能。如果发生资源冲突，您可以使用该命令检查具体细节。要禁用此功能，请执行 `set enable_table_lock=0;`。 ## 语法 @@ -61,4 +61,4 @@ SHOW LOCKS WHERE STATUS = 'HOLDING'; +----------+----------+-------+---------+------+------------------------+--------------------------------------+----------------------------+----------------------------+------------+ | 57 | 4517 | TABLE | HOLDING | root | xzi6pRbLUYasuA9QFB36m6 | d7989971-d5ec-4764-8e37-afe38ebc13e2 | 2023-12-13 09:56:47.295684 | 2023-12-13 09:56:47.310805 | | +----------+----------+-------+---------+------+------------------------+--------------------------------------+----------------------------+----------------------------+------------+ -``` \ No newline at end of file +``` diff --git a/docs/cn/sql-reference/10-sql-commands/10-dml/dml-copy-into-table.md b/docs/cn/sql-reference/10-sql-commands/10-dml/dml-copy-into-table.md index d1c65d9b8b..cab8ac868b 100644 --- a/docs/cn/sql-reference/10-sql-commands/10-dml/dml-copy-into-table.md +++ b/docs/cn/sql-reference/10-sql-commands/10-dml/dml-copy-into-table.md @@ -606,7 +606,7 @@ COPY INTO books_with_extra_columns ``` :::note -表中的额外列可通过 [CREATE TABLE](../00-ddl/01-table/10-ddl-create-table.md) 或 [ALTER TABLE COLUMN](../00-ddl/01-table/90-alter-table-column.md) 指定默认值。若未显式设置，则使用该数据类型的默认值。例如，整型列默认值为 0。 +表中的额外列可通过 [CREATE TABLE](../00-ddl/01-table/10-ddl-create-table.md) 或 [ALTER TABLE](../00-ddl/01-table/90-alter-table.md#column-operations) 指定默认值。若未显式设置，则使用该数据类型的默认值。例如，整型列默认值为 0。 ::: ### 示例 6：使用自定义格式加载 JSON @@ -701,4 +701,4 @@ SELECT * FROM t2; │ 5 │ {"k":"v"} │ │ 6 │ null │ └──────────────────────────────────────┘ -``` \ No newline at end of file +``` diff --git a/docs/en/guides/56-security/masking-policy.md b/docs/en/guides/56-security/masking-policy.md index e893cd578d..7fb02b445e 100644 --- a/docs/en/guides/56-security/masking-policy.md +++ b/docs/en/guides/56-security/masking-policy.md @@ -85,6 +85,6 @@ SELECT * FROM user_info; For detailed commands to create, modify, and manage masking policies, see: - [CREATE MASKING POLICY](/sql/sql-commands/ddl/mask-policy/create-mask-policy) -- [ALTER TABLE COLUMN](/sql/sql-commands/ddl/table/alter-table-column) +- [ALTER TABLE](/sql/sql-commands/ddl/table/alter-table#column-operations) - [Masking Policy Commands](/sql/sql-commands/ddl/mask-policy/) diff --git a/docs/en/guides/57-data-management/01-data-lifecycle.md b/docs/en/guides/57-data-management/01-data-lifecycle.md index 5fb82d514e..e5322eeced 100644 --- a/docs/en/guides/57-data-management/01-data-lifecycle.md +++ b/docs/en/guides/57-data-management/01-data-lifecycle.md @@ -35,7 +35,7 @@ Key Commands: - [`CREATE DATABASE`](/sql/sql-commands/ddl/database/ddl-create-database): To create a new database. - [`ALTER DATABASE`](/sql/sql-commands/ddl/database/ddl-alter-database): To modify an existing database. - [`CREATE TABLE`](/sql/sql-commands/ddl/table/ddl-create-table): To create a new table. -- [`ALTER TABLE`](/sql/sql-commands/ddl/table/alter-table-column): To modify an existing table. +- [`ALTER TABLE`](/sql/sql-commands/ddl/table/alter-table): To modify an existing table. ## Storing Data diff --git a/docs/en/sql-reference/00-sql-reference/30-table-engines/00-fuse.md b/docs/en/sql-reference/00-sql-reference/30-table-engines/00-fuse.md index 979f65faf6..73181a5d46 100644 --- a/docs/en/sql-reference/00-sql-reference/30-table-engines/00-fuse.md +++ b/docs/en/sql-reference/00-sql-reference/30-table-engines/00-fuse.md @@ -57,7 +57,7 @@ Below are the main parameters for creating a Fuse Engine table: The Fuse Engine offers various options (case-insensitive) that allow you to customize the table's properties. - See [Fuse Engine Options](#fuse-engine-options) for details. - Separate multiple options with a space. - - Use [ALTER TABLE OPTION](../../10-sql-commands/00-ddl/01-table/90-alter-table-option.md) to modify a table's options. + - Use [ALTER TABLE](../../10-sql-commands/00-ddl/01-table/90-alter-table.md#fuse-engine-options) to modify a table's options. - Use [SHOW CREATE TABLE](../../10-sql-commands/00-ddl/01-table/show-create-table.md) to show a table's options. --- diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-comment.md b/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-comment.md deleted file mode 100644 index 6ffccc9bfe..0000000000 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-comment.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: ALTER TABLE COMMENT -sidebar_position: 4 ---- -import FunctionDescription from '@site/src/components/FunctionDescription'; - - - -Modifies the comment of a table. If the table does not have a comment yet, this command adds the specified comment to the table. - -## Syntax - -```sql -ALTER TABLE [ IF EXISTS ] [ . ] -COMMENT = '' -``` - -## Examples - -This example creates a table with a comment and then modifies the comment afterward: - -```sql --- Create a table with a comment -CREATE TABLE t(id INT) COMMENT ='original-comment'; - -SHOW CREATE TABLE t; - -┌──────────────────────────────────────────────────────────────────────────────────────┐ -│ Table │ Create Table │ -├────────┼─────────────────────────────────────────────────────────────────────────────┤ -│ t │ CREATE TABLE t (\n id INT NULL\n) ENGINE=FUSE COMMENT = 'original-comment' │ -└──────────────────────────────────────────────────────────────────────────────────────┘ - --- Modify the comment -ALTER TABLE t COMMENT = 'new-comment'; - -SHOW CREATE TABLE t; - -┌─────────────────────────────────────────────────────────────────────────────────┐ -│ Table │ Create Table │ -├────────┼────────────────────────────────────────────────────────────────────────┤ -│ t │ CREATE TABLE t (\n id INT NULL\n) ENGINE=FUSE COMMENT = 'new-comment' │ -└─────────────────────────────────────────────────────────────────────────────────┘ -``` - -This example creates a table without a comment and then adds a comment to the table afterward: - -```sql --- Create a table without comment -CREATE TABLE t(id INT); - -SHOW CREATE TABLE t; - -┌─────────────────────────────────────────────────────────┐ -│ Table │ Create Table │ -├────────┼────────────────────────────────────────────────┤ -│ t │ CREATE TABLE t (\n id INT NULL\n) ENGINE=FUSE │ -└─────────────────────────────────────────────────────────┘ - --- Add a comment -ALTER TABLE t COMMENT = 'new-comment'; - -SHOW CREATE TABLE t; - -┌─────────────────────────────────────────────────────────────────────────────────┐ -│ Table │ Create Table │ -├────────┼────────────────────────────────────────────────────────────────────────┤ -│ t │ CREATE TABLE t (\n id INT NULL\n) ENGINE=FUSE COMMENT = 'new-comment' │ -└─────────────────────────────────────────────────────────────────────────────────┘ -``` \ No newline at end of file diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-option.md b/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-option.md deleted file mode 100644 index df6f491647..0000000000 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-option.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: ALTER TABLE OPTIONS -sidebar_position: 5 ---- -import FunctionDescription from '@site/src/components/FunctionDescription'; - - - -Sets or unsets [Fuse Engine options](../../../00-sql-reference/30-table-engines/00-fuse.md#fuse-engine-options) for a table. - -## Syntax - -```sql --- Set Fuse Engine options -ALTER TABLE [ . ] SET OPTIONS () - --- Unset Fuse Engine options, reverting them to their default values -ALTER TABLE [ . ] UNSET OPTIONS () -``` - -Please note that only the following Fuse Engine options can be unset: - -- `block_per_segment` -- `block_size_threshold` -- `data_retention_period_in_hours` -- `data_retention_num_snapshots_to_keep` -- `row_avg_depth_threshold` -- `row_per_block` -- `row_per_page` - -## Examples - -### Setting Fuse Engine Options - -The following demonstrates how to set Fuse Engine options and verify changes with [SHOW CREATE TABLE](show-create-table.md): - -```sql -CREATE TABLE fuse_table (a int); - -SET hide_options_in_show_create_table=0; - --- Show the current CREATE TABLE statement, including the Fuse Engine options -SHOW CREATE TABLE fuse_table; - --[ RECORD 1 ]----------------------------------- - Table: fuse_table -Create Table: CREATE TABLE fuse_table ( - a INT NULL -) ENGINE=FUSE COMPRESSION='lz4' STORAGE_FORMAT='native' - --- Change maximum blocks in a segment to 500 --- Change the data retention period to 240 hours -ALTER TABLE fuse_table SET OPTIONS (block_per_segment = 500, data_retention_period_in_hours = 240); - --- Show the updated CREATE TABLE statement, reflecting the new options -SHOW CREATE TABLE fuse_table; - --[ RECORD 1 ]----------------------------------- - Table: fuse_table -Create Table: CREATE TABLE fuse_table ( - a INT NULL -) ENGINE=FUSE BLOCK_PER_SEGMENT='500' COMPRESSION='lz4' DATA_RETENTION_PERIOD_IN_HOURS='240' STORAGE_FORMAT='native' -``` - -The following demonstrates how to use the `data_retention_num_snapshots_to_keep` option with `enable_auto_vacuum`: - -```sql --- Create a new table -CREATE OR REPLACE TABLE t(c INT); - --- Set the table to retain only the most recent snapshot -ALTER TABLE t SET OPTIONS(data_retention_num_snapshots_to_keep = 1); - --- Enable automatic vacuum to trigger snapshot cleanup -SET enable_auto_vacuum = 1; - --- After each of these operations, only one snapshot will be kept -INSERT INTO t VALUES(1); -INSERT INTO t VALUES(2); -INSERT INTO t VALUES(3); -``` - -### Unsetting Fuse Engine Options - -The following demonstrates how to unset Fuse Engine options, reverting them to their default values: - -```sql -ALTER TABLE fuse_table UNSET OPTIONS (block_per_segment, data_retention_period_in_hours); - -SHOW CREATE TABLE fuse_table; - --[ RECORD 1 ]----------------------------------- - Table: fuse_table -Create Table: CREATE TABLE fuse_table ( - a INT NULL -) ENGINE=FUSE COMPRESSION='lz4' STORAGE_FORMAT='native' \ No newline at end of file diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-column.md b/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md similarity index 51% rename from docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-column.md rename to docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md index a606825104..50e7c6e0f8 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table-column.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md @@ -1,18 +1,24 @@ --- -title: ALTER TABLE COLUMN +title: ALTER TABLE sidebar_position: 4 +slug: /sql/sql-commands/ddl/table/alter-table --- + import FunctionDescription from '@site/src/components/FunctionDescription'; - + import EEFeature from '@site/src/components/EEFeature'; +Use `ALTER TABLE` to modify the structure and properties of an existing table, including its columns, comment, storage options, external connection, or even swapping metadata with another table. The subsections below cover each supported capability. + +## Column Operations {#column-operations} + -Modifies a table by adding, converting, renaming, changing, or removing a column. +Modify a table by adding, converting, renaming, changing, or removing columns. -## Syntax +### Syntax ```sql -- Add a column to the end of the table @@ -75,9 +81,9 @@ DROP [ COLUMN ] You must `ALTER TABLE ... MODIFY COLUMN UNSET MASKING POLICY` before changing the column definition or dropping the column; otherwise the statement fails because the column is still protected by a security policy. ::: -## Examples +### Examples -### Example 1: Adding, Renaming, and Removing a Column +#### Example 1: Adding, Renaming, and Removing a Column This example illustrates the creation of a table called "default.users" with columns 'username', 'email', and 'age'. It showcases the addition of columns 'id' and 'middle_name' with various constraints. The example also demonstrates the renaming and subsequent removal of the "age" column. @@ -158,136 +164,238 @@ id |INT |NO |0 | | username |VARCHAR|NO |'' | | middle_name |VARCHAR|YES |NULL | | email |VARCHAR|YES |NULL | | -business_email|VARCHAR|NO |'example@example.com'| | ``` -### Example 2: Adding a Computed Column +#### Example 2: Modify Columns and Masking Policies + +```sql +-- Change column types and defaults +ALTER TABLE users +MODIFY COLUMN age BIGINT DEFAULT 18, + COLUMN email VARCHAR(320) DEFAULT ''; + +-- Add masking policy that expects extra arguments +ALTER TABLE users +MODIFY COLUMN email SET MASKING POLICY pii_email USING (email, username); + +-- To drop or alter the column, remove the policy first +ALTER TABLE users +MODIFY COLUMN email UNSET MASKING POLICY; +``` + +## Table Comment {#table-comment} -This example demonstrates creating a table for storing employee information, inserting data into the table, and adding a computed column to calculate the age of each employee based on their birth year. +Modifies the comment of a table. If the table does not have a comment yet, this command adds the specified comment to the table. + +### Syntax ```sql --- Create a table -CREATE TABLE Employees ( - ID INT, - Name VARCHAR(50), - BirthYear INT -); +ALTER TABLE [ IF EXISTS ] [ . ] +COMMENT = '' +``` + +### Examples + +```sql +-- Create a table with a comment +CREATE TABLE t(id INT) COMMENT ='original-comment'; + +SHOW CREATE TABLE t; --- Insert data -INSERT INTO Employees (ID, Name, BirthYear) -VALUES - (1, 'John Doe', 1990), - (2, 'Jane Smith', 1985), - (3, 'Robert Johnson', 1982); +┌──────────────────────────────────────────────────────────────────────────────────────┐ +│ Table │ Create Table │ +├────────┼─────────────────────────────────────────────────────────────────────────────┤ +│ t │ CREATE TABLE t (\n id INT NULL\n) ENGINE=FUSE COMMENT = 'original-comment' │ +└──────────────────────────────────────────────────────────────────────────────────────┘ --- Add a computed column named Age -ALTER TABLE Employees -ADD COLUMN Age INT64 AS (2023 - BirthYear) VIRTUAL; +-- Modify the comment +ALTER TABLE t COMMENT = 'new-comment'; -SELECT * FROM Employees; +SHOW CREATE TABLE t; -ID | Name | BirthYear | Age ------------------------------------- -1 | John Doe | 1990 | 33 -2 | Jane Smith | 1985 | 38 -3 | Robert Johnson| 1982 | 41 +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ Table │ Create Table │ +├────────┼────────────────────────────────────────────────────────────────────────┤ +│ t │ CREATE TABLE t (\n id INT NULL\n) ENGINE=FUSE COMMENT = 'new-comment' │ +└─────────────────────────────────────────────────────────────────────────────────┘ ``` -### Example 3: Converting a Computed Column +```sql +-- Create a table without comment +CREATE TABLE t(id INT); + +-- Add a comment later +ALTER TABLE t COMMENT = 'new-comment'; +``` + +## Fuse Engine Options {#fuse-engine-options} + +Sets or unsets [Fuse Engine options](../../../00-sql-reference/30-table-engines/00-fuse.md#fuse-engine-options) for a table. -This example creates a table called "products" with columns for ID, price, quantity, and a computed column "total_price." The ALTER TABLE statement removes the computed functionality from the "total_price" column, converting it into a regular column. +### Syntax ```sql -CREATE TABLE IF NOT EXISTS products ( - id INT, - price FLOAT64, - quantity INT, - total_price FLOAT64 AS (price * quantity) STORED -); +-- Set Fuse Engine options +ALTER TABLE [ . ] SET OPTIONS () -ALTER TABLE products -MODIFY COLUMN total_price DROP STORED; +-- Unset Fuse Engine options, reverting them to their default values +ALTER TABLE [ . ] UNSET OPTIONS () ``` -### Example 4: Changing Data Type of a Column +Only the following Fuse Engine options can be unset: + +- `block_per_segment` +- `block_size_threshold` +- `data_retention_period_in_hours` +- `data_retention_num_snapshots_to_keep` +- `row_avg_depth_threshold` +- `row_per_block` +- `row_per_page` -This example demonstrates how to modify the data type of a column and add a comment to it. +### Examples ```sql -CREATE TABLE students_info ( - id INT, - name VARCHAR(50), - age INT -); +CREATE TABLE fuse_table (a int); + +SET hide_options_in_show_create_table=0; + +-- Show current options +SHOW CREATE TABLE fuse_table; + +-- Change Fuse options +ALTER TABLE fuse_table SET OPTIONS (block_per_segment = 500, data_retention_period_in_hours = 240); --- Change the data type of the 'age' column to VARCHAR with a default value of 0 -ALTER TABLE students_info MODIFY COLUMN age VARCHAR(10) DEFAULT '0'; +-- Show updated options +SHOW CREATE TABLE fuse_table; +``` -SHOW CREATE TABLE students_info; +```sql +-- Limit snapshots and enable auto vacuum +CREATE OR REPLACE TABLE t(c INT); +ALTER TABLE t SET OPTIONS(data_retention_num_snapshots_to_keep = 1); +SET enable_auto_vacuum = 1; +INSERT INTO t VALUES(1); +INSERT INTO t VALUES(2); +INSERT INTO t VALUES(3); + +-- Revert options to defaults +ALTER TABLE fuse_table UNSET OPTIONS (block_per_segment, data_retention_period_in_hours); +``` -┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ -│ Table │ Create Table │ -├───────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤ -│ students_info │ CREATE TABLE students_info (\n id INT NULL,\n name VARCHAR NULL,\n age VARCHAR NULL DEFAULT '0'\n) ENGINE=FUSE │ -└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +## External Table Connection {#external-table-connection} --- Add a comment to the 'age' column -ALTER TABLE students_info MODIFY COLUMN age COMMENT 'abc'; +Updates the connection settings for an external table. Only credential-related fields (`access_key_id`, `secret_access_key`, `role_arn`) are applied when the command runs. Other properties such as `bucket`, `region`, or `root` remain unchanged. -SHOW CREATE TABLE students_info; +### Syntax -┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ -│ Table │ Create Table │ -├───────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤ -│ students_info │ CREATE TABLE students_info (\n id INT NULL,\n name VARCHAR NULL,\n age VARCHAR NULL DEFAULT '0' COMMENT 'abc'\n) ENGINE=FUSE │ -└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +```sql +ALTER TABLE [ . ] CONNECTION = ( connection_name = '' ) ``` -### Example 5: Setting a Masking Policy with the USING Clause +| Parameter | Description | Required | +|-----------|-------------|----------| +| connection_name | Name of the connection to be used for the external table. The connection must already exist in the system. | Yes | + +This command is particularly useful when credentials need to be rotated or when IAM roles change. The specified connection must already exist before it can be used with this command. + +**Security best practices** + +When working with external tables, AWS IAM roles provide significant security advantages over access keys: -This example illustrates how to set up a masking policy that references additional columns by using the `USING` clause. +- No stored credentials: Eliminates the need to store access keys in your configuration +- Automatic rotation: Handles credential rotation automatically +- Fine-grained control: Allows for more precise access control + +To use IAM roles with Databend Cloud, see [Authenticate with AWS IAM Role](/guides/cloud/advanced/iam-role). + +### Examples ```sql --- Create a table and insert sample data -CREATE TABLE user_info ( +-- Create connections +CREATE CONNECTION external_table_conn + STORAGE_TYPE = 's3' + ACCESS_KEY_ID = '' + SECRET_ACCESS_KEY = ''; + +CREATE CONNECTION external_table_conn_new + STORAGE_TYPE = 's3' + ACCESS_KEY_ID = '' + SECRET_ACCESS_KEY = ''; + +-- Create an external table using the first connection +CREATE OR REPLACE TABLE external_table_test ( id INT, - phone STRING, - email STRING -); + name VARCHAR, + age INT +) +'s3://testbucket/13_fuse_external_table/' +CONNECTION=(connection_name = 'external_table_conn'); + +-- Update to use the new connection +ALTER TABLE external_table_test CONNECTION=( connection_name = 'external_table_conn_new' ); +``` + +```sql +-- Migrate to IAM role authentication +CREATE CONNECTION s3_access_key_conn + STORAGE_TYPE = 's3' + ACCESS_KEY_ID = '' + SECRET_ACCESS_KEY = ''; + +CREATE TABLE sales_data ( + order_id INT, + product_name VARCHAR, + quantity INT +) +'s3://sales-bucket/data/' +CONNECTION=(connection_name = 's3_access_key_conn'); + +CREATE CONNECTION s3_role_conn + STORAGE_TYPE = 's3' + ROLE_ARN = 'arn:aws:iam::123456789012:role/databend-access'; + +ALTER TABLE sales_data CONNECTION=( connection_name = 's3_role_conn' ); +``` + +## Swap Tables {#swap-tables} + +Swaps all table metadata and data between two tables atomically in a single transaction. This operation exchanges the table schemas, including all columns, constraints, and data, effectively making each table take on the identity of the other. + +### Syntax + +```sql +ALTER TABLE [ IF EXISTS ] SWAP WITH +``` + +| Parameter | Description | +|----------------------|------------------------------------------------| +| `source_table_name` | The name of the first table to swap | +| `target_table_name` | The name of the second table to swap with | + +### Usage Notes + +- Only available for Fuse Engine tables. External tables, system tables, and other non-Fuse tables are not supported. +- Temporary tables cannot be swapped with permanent or transient tables. +- The current role must be the owner of both tables to perform the swap operation. +- Both tables must be in the same database. Cross-database swapping is not supported. +- The swap operation is atomic. Either both tables are swapped successfully, or neither is changed. +- All data and metadata are preserved during the swap. No data is lost or modified. + +### Examples + +```sql +-- Create two tables with different schemas +CREATE OR REPLACE TABLE t1(a1 INT, a2 VARCHAR, a3 DATE); +CREATE OR REPLACE TABLE t2(b1 VARCHAR); + +-- Check table schemas before swap +DESC t1; +DESC t2; + +-- Swap the tables +ALTER TABLE t1 SWAP WITH t2; -INSERT INTO user_info (id, phone, email) VALUES (1, '91234567', 'sue@example.com'); -INSERT INTO user_info (id, phone, email) VALUES (2, '81234567', 'eric@example.com'); - --- Create a role -CREATE ROLE 'MANAGERS'; -GRANT ALL ON *.* TO ROLE 'MANAGERS'; - --- Create a user and grant the role to the user -CREATE USER manager_user IDENTIFIED BY 'databend'; -GRANT ROLE 'MANAGERS' TO 'manager_user'; - --- Create a masking policy that inspects another column -CREATE MASKING POLICY email_mask -AS - (email_val nullable(string), phone_ref nullable(string)) - RETURNS nullable(string) -> - CASE - WHEN current_role() IN ('MANAGERS') THEN email_val - WHEN phone_ref LIKE '91%' THEN email_val - ELSE '*********' - END - COMMENT = 'hide_email_when_phone_is_masked'; - --- Associate the masking policy with the 'email' column and provide --- the additional column required by the policy by using USING(...) -ALTER TABLE user_info -MODIFY COLUMN email SET MASKING POLICY email_mask USING (email, phone); - --- Query with the Root user -SELECT id, phone, email FROM user_info ORDER BY id; - -id|phone |email | ---+--------+---------------+ - 1|91234567|sue@example.com| - 2|81234567|********* | +-- After swapping, t1 now has t2's schema, and t2 has t1's schema +DESC t1; +DESC t2; ``` diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/91-alter-table-connection.md b/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/91-alter-table-connection.md deleted file mode 100644 index c00c2e5ba9..0000000000 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/91-alter-table-connection.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: ALTER TABLE CONNECTION -sidebar_position: 6 ---- -import FunctionDescription from '@site/src/components/FunctionDescription'; - - - -Updates the connection settings for an external table. - -## Syntax - -```sql -ALTER TABLE [ . ] CONNECTION = ( connection_name = '' ) -``` - -| Parameter | Description | Required | -|-----------|-------------|----------| -| connection_name | Name of the connection to be used for the external table. The connection must already exist in the system. | Yes | - -## Usage Notes - -When using the ALTER TABLE CONNECTION command, only credential-related settings can be changed, including `access_key_id`, `secret_access_key`, and `role_arn`. Changes to other connection parameters such as `bucket`, `region`, or `root` will be ignored. - -This command is particularly useful when credentials need to be rotated or when IAM roles change. The specified connection must already exist in the system before it can be used with this command. - -## Security Best Practices - -When working with external tables, AWS IAM roles provide significant security advantages over access keys: - -- **No stored credentials**: Eliminates the need to store access keys in your configuration -- **Automatic rotation**: Handles credential rotation automatically -- **Fine-grained control**: Allows for more precise access control - -To use IAM roles with Databend Cloud, see [Authenticate with AWS IAM Role](/guides/cloud/advanced/iam-role) for instructions. - -## Examples - -### Updating Connection for an External Table - -This example creates an external table with an initial connection, then updates it to use a different connection: - -```sql --- Create two connections with different credentials -CREATE CONNECTION external_table_conn - STORAGE_TYPE = 's3' - ACCESS_KEY_ID = '' - SECRET_ACCESS_KEY = ''; - -CREATE CONNECTION external_table_conn_new - STORAGE_TYPE = 's3' - ACCESS_KEY_ID = '' - SECRET_ACCESS_KEY = ''; - --- Create an external table using the first connection -CREATE OR REPLACE TABLE external_table_test ( - id INT, - name VARCHAR, - age INT -) -'s3://testbucket/13_fuse_external_table/' -CONNECTION=(connection_name = 'external_table_conn'); - --- Update the table to use the new connection with rotated credentials -ALTER TABLE external_table_test CONNECTION=( connection_name = 'external_table_conn_new' ); -``` - -### Updating Connection for an External Table with IAM Role - -This example demonstrates migrating from access key authentication to IAM role authentication: - -```sql --- Create an external table with access key authentication -CREATE CONNECTION s3_access_key_conn - STORAGE_TYPE = 's3' - ACCESS_KEY_ID = '' - SECRET_ACCESS_KEY = ''; - -CREATE TABLE sales_data ( - order_id INT, - product_name VARCHAR, - quantity INT -) -'s3://sales-bucket/data/' -CONNECTION=(connection_name = 's3_access_key_conn'); - --- Later, create a new connection using IAM role authentication -CREATE CONNECTION s3_role_conn - STORAGE_TYPE = 's3' - ROLE_ARN = 'arn:aws:iam::123456789012:role/databend-access'; - --- Update the table to use the IAM role connection instead -ALTER TABLE sales_data CONNECTION=( connection_name = 's3_role_conn' ); -``` diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/92-alter-table-swap.md b/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/92-alter-table-swap.md deleted file mode 100644 index 7a63418a37..0000000000 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/92-alter-table-swap.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: ALTER TABLE SWAP WITH -sidebar_position: 5 ---- -import FunctionDescription from '@site/src/components/FunctionDescription'; - - - -Swaps all table metadata and data between two tables atomically in a single transaction. This operation exchanges the table schemas, including all columns, constraints, and data, effectively making each table take on the identity of the other. - -## Syntax - -```sql -ALTER TABLE [ IF EXISTS ] SWAP WITH -``` - -| Parameter | Description | -|----------------------|------------------------------------------------| -| `source_table_name` | The name of the first table to swap | -| `target_table_name` | The name of the second table to swap with | - -## Usage Notes - -- **Engine Support**: Only available for Fuse Engine tables. External tables, system tables, and other non-Fuse tables are not supported. -- **Table Type**: Temporary tables cannot be swapped with permanent or transient tables. -- **Permissions**: The current role must be the owner of both tables to perform the swap operation. -- **Database Scope**: Both tables must be in the same database. Cross-database swapping is not supported. -- **Atomicity**: The swap operation is atomic. Either both tables are swapped successfully, or neither is changed. -- **Data Preservation**: All data and metadata are preserved during the swap. No data is lost or modified. - -## Examples - -```sql --- Create two tables with different schemas -CREATE OR REPLACE TABLE t1(a1 INT, a2 VARCHAR, a3 DATE); -CREATE OR REPLACE TABLE t2(b1 VARCHAR); - --- Check table schemas before swap -DESC t1; -DESC t2; - --- Swap the tables -ALTER TABLE t1 SWAP WITH t2; - --- After swapping, t1 now has t2's schema, and t2 has t1's schema -DESC t1; -DESC t2; -``` diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/index.md b/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/index.md index 1114fa9a59..636cb6c483 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/index.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/index.md @@ -19,10 +19,7 @@ This page provides a comprehensive overview of table operations in Databend, org | Command | Description | |---------|-------------| -| [ALTER TABLE COLUMN](90-alter-table-column.md) | Modifies the structure of a table by making changes to its columns | -| [ALTER TABLE CONNECTION](91-alter-table-connection.md) | Updates the connection settings for an external table | -| [ALTER TABLE OPTION](90-alter-table-option.md) | Modifies the Fuse engine options of a table | -| [ALTER TABLE COMMENT](90-alter-table-comment.md) | Updates the comment for a table | +| [ALTER TABLE](90-alter-table.md) | Modifies table columns, comments, Fuse options, external connections, or swaps metadata with another table | | [RENAME TABLE](30-ddl-rename-table.md) | Changes the name of a table | ## Table Information diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/13-connection/create-connection.md b/docs/en/sql-reference/10-sql-commands/00-ddl/13-connection/create-connection.md index 0e57cb9541..dfd29ee3b0 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/13-connection/create-connection.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/13-connection/create-connection.md @@ -148,7 +148,7 @@ To create a connection, the user performing the operation or the [current_role]( ## Update Table Connections -To switch an existing table to a new connection, use [`ALTER TABLE ... CONNECTION`](/sql/sql-commands/ddl/table/alter-table-connection). This command rebinds external tables to a different connection without recreating the table. +To switch an existing table to a new connection, use [`ALTER TABLE ... CONNECTION`](/sql/sql-commands/ddl/table/alter-table#external-table-connection). This command rebinds external tables to a different connection without recreating the table. ## Examples diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/14-transaction/show-locks.md b/docs/en/sql-reference/10-sql-commands/00-ddl/14-transaction/show-locks.md index c8f887564a..33b9f00b25 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/14-transaction/show-locks.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/14-transaction/show-locks.md @@ -7,7 +7,7 @@ import FunctionDescription from '@site/src/components/FunctionDescription'; Provides a list of active transactions currently holding locks on tables, either for the current user across all their sessions or for all users within the Databend system. A lock is a synchronization mechanism that restricts access to shared resources, such as tables, ensuring orderly and controlled interactions among processes or threads within the Databend system to maintain data consistency and prevent conflicts. -The operations, such as [UPDATE](../../10-dml/dml-update.md), [DELETE](../../10-dml/dml-delete-from.md), [OPTIMIZE TABLE](../01-table/60-optimize-table.md), [RECLUSTER TABLE](../06-clusterkey/dml-recluster-table.md), and [ALTER TABLE COLUMN](../01-table/90-alter-table-column.md), can result in table locks in the system. The table lock feature is enabled by default. In case of resource conflicts, you can examine specific details using the command. To disable this feature, execute `set enable_table_lock=0;`. +The operations, such as [UPDATE](../../10-dml/dml-update.md), [DELETE](../../10-dml/dml-delete-from.md), [OPTIMIZE TABLE](../01-table/60-optimize-table.md), [RECLUSTER TABLE](../06-clusterkey/dml-recluster-table.md), and [ALTER TABLE](../01-table/90-alter-table.md#column-operations), can result in table locks in the system. The table lock feature is enabled by default. In case of resource conflicts, you can examine specific details using the command. To disable this feature, execute `set enable_table_lock=0;`. ## Syntax @@ -61,4 +61,4 @@ SHOW LOCKS WHERE STATUS = 'HOLDING'; +----------+----------+-------+---------+------+------------------------+--------------------------------------+----------------------------+----------------------------+------------+ | 57 | 4517 | TABLE | HOLDING | root | xzi6pRbLUYasuA9QFB36m6 | d7989971-d5ec-4764-8e37-afe38ebc13e2 | 2023-12-13 09:56:47.295684 | 2023-12-13 09:56:47.310805 | | +----------+----------+-------+---------+------+------------------------+--------------------------------------+----------------------------+----------------------------+------------+ -``` \ No newline at end of file +``` diff --git a/docs/en/sql-reference/10-sql-commands/10-dml/dml-copy-into-table.md b/docs/en/sql-reference/10-sql-commands/10-dml/dml-copy-into-table.md index a4223c0381..0eee228e93 100644 --- a/docs/en/sql-reference/10-sql-commands/10-dml/dml-copy-into-table.md +++ b/docs/en/sql-reference/10-sql-commands/10-dml/dml-copy-into-table.md @@ -606,7 +606,7 @@ COPY INTO books_with_extra_columns ``` :::note -Extra columns in a table can have default values specified by [CREATE TABLE](../00-ddl/01-table/10-ddl-create-table.md) or [ALTER TABLE COLUMN](../00-ddl/01-table/90-alter-table-column.md). If a default value is not explicitly set for an extra column, the default value associated with its data type will be applied. For instance, an integer-type column will default to 0 if no other value is specified. +Extra columns in a table can have default values specified by [CREATE TABLE](../00-ddl/01-table/10-ddl-create-table.md) or [ALTER TABLE](../00-ddl/01-table/90-alter-table.md#column-operations). If a default value is not explicitly set for an extra column, the default value associated with its data type will be applied. For instance, an integer-type column will default to 0 if no other value is specified. ::: ### Example 6: Loading JSON with Custom Format diff --git a/site-redirects.ts b/site-redirects.ts index 2cd57f0df9..c96cd6a9c7 100644 --- a/site-redirects.ts +++ b/site-redirects.ts @@ -23,6 +23,47 @@ const siteRedirects = [ from: '/sql/sql-reference/sql-variables', to: '/sql/sql-commands/ddl/variable/' }, + // ALTER TABLE doc consolidation + { + from: '/sql/sql-commands/ddl/table/alter-table-column', + to: '/sql/sql-commands/ddl/table/alter-table' + }, + { + from: '/sql/sql-commands/ddl/table/alter-table-comment', + to: '/sql/sql-commands/ddl/table/alter-table' + }, + { + from: '/sql/sql-commands/ddl/table/alter-table-option', + to: '/sql/sql-commands/ddl/table/alter-table' + }, + { + from: '/sql/sql-commands/ddl/table/alter-table-connection', + to: '/sql/sql-commands/ddl/table/alter-table' + }, + { + from: '/sql/sql-commands/ddl/table/alter-table-swap', + to: '/sql/sql-commands/ddl/table/alter-table' + }, + { + from: '/cn/sql/sql-commands/ddl/table/alter-table-column', + to: '/cn/sql/sql-commands/ddl/table/alter-table' + }, + { + from: '/cn/sql/sql-commands/ddl/table/alter-table-comment', + to: '/cn/sql/sql-commands/ddl/table/alter-table' + }, + { + from: '/cn/sql/sql-commands/ddl/table/alter-table-option', + to: '/cn/sql/sql-commands/ddl/table/alter-table' + }, + { + from: '/cn/sql/sql-commands/ddl/table/alter-table-connection', + to: '/cn/sql/sql-commands/ddl/table/alter-table' + }, + { + from: '/cn/sql/sql-commands/ddl/table/alter-table-swap', + to: '/cn/sql/sql-commands/ddl/table/alter-table' + }, // AI Functions redirects - functions moved to external implementation { from: '/sql/sql-functions/ai-functions/ai-cosine-distance', From abcd5bf020de22ae9a4b56a1afae624670edbdc5 Mon Sep 17 00:00:00 2001 From: q <787025321@qq.com> Date: Thu, 13 Nov 2025 14:23:02 +0800 Subject: [PATCH 2/3] Remove outdated Chinese SQL table alter redirects Removed obsolete Chinese redirects for alter table commands. --- site-redirects.ts | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/site-redirects.ts b/site-redirects.ts index c96cd6a9c7..32549df835 100644 --- a/site-redirects.ts +++ b/site-redirects.ts @@ -44,26 +44,6 @@ const siteRedirects = [ from: '/sql/sql-commands/ddl/table/alter-table-swap', to: '/sql/sql-commands/ddl/table/alter-table' }, - { - from: '/cn/sql/sql-commands/ddl/table/alter-table-column', - to: '/cn/sql/sql-commands/ddl/table/alter-table' - }, - { - from: '/cn/sql/sql-commands/ddl/table/alter-table-comment', - to: '/cn/sql/sql-commands/ddl/table/alter-table' - }, - { - from: '/cn/sql/sql-commands/ddl/table/alter-table-option', - to: '/cn/sql/sql-commands/ddl/table/alter-table' - }, - { - from: '/cn/sql/sql-commands/ddl/table/alter-table-connection', - to: '/cn/sql/sql-commands/ddl/table/alter-table' - }, - { - from: '/cn/sql/sql-commands/ddl/table/alter-table-swap', - to: '/cn/sql/sql-commands/ddl/table/alter-table' - }, // AI Functions redirects - functions moved to external implementation { from: '/sql/sql-functions/ai-functions/ai-cosine-distance', From cef30d1427113ff2e1d823ef2d149896c3b3ddbe Mon Sep 17 00:00:00 2001 From: BohuTANG Date: Thu, 13 Nov 2025 14:42:42 +0800 Subject: [PATCH 3/3] docs: simplify index refresh guidance --- .../00-ddl/01-table/90-alter-table.md | 2 +- .../create-aggregating-index.md | 4 +-- .../refresh-aggregating-index.md | 26 ++++++++----------- .../refresh-inverted-index.md | 18 +++++++++---- .../07-ngram-index/refresh-ngram-index.md | 16 +++++++++--- .../00-ddl/01-table/90-alter-table.md | 2 +- .../create-aggregating-index.md | 4 +-- .../refresh-aggregating-index.md | 26 ++++++++----------- .../refresh-inverted-index.md | 18 +++++++++---- .../07-ngram-index/refresh-ngram-index.md | 16 +++++++++--- 10 files changed, 78 insertions(+), 54 deletions(-) diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md index 8c9f4ad588..bdfcfad930 100644 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md @@ -1,7 +1,7 @@ --- title: ALTER TABLE sidebar_position: 4 -slug: /cn/sql/sql-commands/ddl/table/alter-table +slug: /sql-commands/ddl/table/alter-table --- import FunctionDescription from '@site/src/components/FunctionDescription'; diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/07-aggregating-index/create-aggregating-index.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/07-aggregating-index/create-aggregating-index.md index 6b9cdb456e..a546dcf3aa 100644 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/07-aggregating-index/create-aggregating-index.md +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/07-aggregating-index/create-aggregating-index.md @@ -12,11 +12,9 @@ import FunctionDescription from '@site/src/components/FunctionDescription'; ## 语法 ```sql -CREATE [ OR REPLACE ] [ ASYNC ] AGGREGATING INDEX AS SELECT ... +CREATE [ OR REPLACE ] AGGREGATING INDEX AS SELECT ... ``` -- `ASYNC` 选项：添加 ASYNC 是可选的。它允许异步创建索引，即索引不会立即构建。要稍后构建，请使用 [REFRESH AGGREGATING INDEX](refresh-aggregating-index.md) 命令。 - - 创建聚合索引（Aggregating Index）时，请将其使用限制在标准的[聚合函数](../../../20-sql-functions/07-aggregate-functions/index.md)（例如 AVG、SUM、MIN、MAX、COUNT 和 GROUP BY）内，同时请注意，不支持 GROUPING SETS、[窗口函数](../../../20-sql-functions/08-window-functions/index.md)、[LIMIT](../../20-query-syntax/01-query-select.md#limit-clause) 和 [ORDER BY](../../20-query-syntax/01-query-select.md#order-by-clause)，否则将收到错误提示：`Currently create aggregating index just support simple query, like: SELECT ... FROM ... WHERE ... GROUP BY ...`。 - 创建聚合索引（Aggregating Index）时定义的查询（Query）筛选范围应与实际查询（Query）的范围匹配或包含实际查询（Query）的范围。 diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/07-aggregating-index/refresh-aggregating-index.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/07-aggregating-index/refresh-aggregating-index.md index 52873d9984..40f881a9ee 100644 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/07-aggregating-index/refresh-aggregating-index.md +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/07-aggregating-index/refresh-aggregating-index.md @@ -7,34 +7,30 @@ import FunctionDescription from '@site/src/components/FunctionDescription'; +Databend 默认以 `SYNC` 模式自动维护聚合索引。只有当表里已有数据、而聚合索引是后来补建时，才需要运行 `REFRESH AGGREGATING INDEX` 来补齐这些历史行。 + ## 语法 ```sql -REFRESH AGGREGATING INDEX [ LIMIT ] +REFRESH AGGREGATING INDEX ``` -"LIMIT" 参数允许您控制每次刷新操作可以更新的最大块数。 强烈建议使用此参数并定义限制以优化内存使用。 另请注意，设置限制可能会导致部分数据更新。 例如，如果您有 100 个块但设置的限制为 10，则单次刷新可能无法更新最新数据，可能会导致某些块未刷新。 您可能需要执行多次刷新操作以确保完全更新。 - -## 何时使用 REFRESH AGGREGATING INDEX - -- **当自动更新失败时：** 如果默认自动更新（`SYNC` 模式）无法正常工作，请使用 `REFRESH AGGREGATING INDEX` 将任何遗漏的数据包含在索引中。 -- **对于 ASYNC 索引：** 如果使用 `ASYNC` 选项创建聚合索引，则它不会自动更新。 您需要使用 `REFRESH AGGREGATING INDEX` 手动刷新它。 - ## 示例 -此示例创建并刷新名为 *my_agg_index* 的聚合索引： +以下示例演示：表先有数据，再创建聚合索引并通过 `REFRESH` 回填： ```sql --- Prepare data +-- 先建表并写入在索引创建前的数据 CREATE TABLE agg(a int, b int, c int); INSERT INTO agg VALUES (1,1,4), (1,2,1), (1,2,4); --- Create an aggregating index +-- 声明聚合索引（现有数据尚未被索引） CREATE AGGREGATING INDEX my_agg_index AS SELECT MIN(a), MAX(c) FROM agg; --- Insert new data -INSERT INTO agg VALUES (2,2,5); - --- Refresh the aggregating index +-- 回填历史数据 REFRESH AGGREGATING INDEX my_agg_index; + +-- 索引创建后再写入的数据会自动同步 +INSERT INTO agg VALUES (2,2,5); +-- SYNC 模式会自动保持索引最新 ``` diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/07-inverted-index/refresh-inverted-index.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/07-inverted-index/refresh-inverted-index.md index b4f061865f..a593698383 100644 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/07-inverted-index/refresh-inverted-index.md +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/07-inverted-index/refresh-inverted-index.md @@ -7,10 +7,7 @@ import FunctionDescription from '@site/src/components/FunctionDescription'; -刷新 Databend 中的倒排索引。在以下情况下，倒排索引需要刷新： - -- 当在创建倒排索引之前将数据插入到表中时，创建后需要手动刷新倒排索引，才能有效地索引插入的数据。 -- 当倒排索引遇到问题或损坏时，需要刷新。如果由于某些块的倒排索引文件损坏而导致倒排索引中断，则诸如 `where match(body, 'wiki')` 之类的查询将返回错误。在这种情况下，您需要刷新倒排索引以解决此问题。 +倒排索引在默认的 `SYNC` 模式下会随着新数据写入自动刷新。仅在创建索引前表中已有数据、需要回填历史行时才需要执行 `REFRESH INVERTED INDEX`。 ## 语法 @@ -25,6 +22,17 @@ REFRESH INVERTED INDEX ON [.] [LIMIT ] ## 示例 ```sql --- 刷新表 "customer_feedback" 的名为 "customer_feedback_idx" 的倒排索引 +-- 表中已有在创建索引之前写入的数据 +CREATE TABLE IF NOT EXISTS customer_feedback(id INT, body STRING); +INSERT INTO customer_feedback VALUES + (1, 'Great coffee beans'), + (2, 'Needs fresh roasting'); + +-- 之后才创建倒排索引 +CREATE INVERTED INDEX customer_feedback_idx ON customer_feedback(body); + +-- 通过 REFRESH 回填历史数据 REFRESH INVERTED INDEX customer_feedback_idx ON customer_feedback; + +-- 之后的新写入会在 SYNC 模式下自动刷新 ``` diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/07-ngram-index/refresh-ngram-index.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/07-ngram-index/refresh-ngram-index.md index 1e1a7edc54..71bf814af6 100644 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/07-ngram-index/refresh-ngram-index.md +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/07-ngram-index/refresh-ngram-index.md @@ -7,7 +7,7 @@ import FunctionDescription from '@site/src/components/FunctionDescription'; -刷新表上已有的 NGRAM 索引（NGRAM INDEX）。 +在默认情况下，NGRAM 索引会在数据写入时自动刷新。只有在需要为历史数据回填索引时才需要执行 `REFRESH NGRAM INDEX`。 ## 语法 @@ -18,8 +18,18 @@ ON [.]; ## 示例 -以下示例刷新 `amazon_reviews_ngram` 表上的 `idx1` 索引： - ```sql +-- 表中已有在创建索引之前写入的数据 +CREATE TABLE IF NOT EXISTS amazon_reviews_ngram(review_id INT, review STRING); +INSERT INTO amazon_reviews_ngram VALUES + (1, 'coffee beans from Colombia'), + (2, 'best roasting kit'); + +-- 随后才声明 NGRAM 索引 +CREATE NGRAM INDEX idx1 ON amazon_reviews_ngram(review) WITH (ngram_size = 3); + +-- 通过刷新补齐历史数据 REFRESH NGRAM INDEX idx1 ON amazon_reviews_ngram; + +-- 之后的新写入会在 SYNC 模式下自动刷新 ``` diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md b/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md index 50e7c6e0f8..6bbed397db 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md @@ -1,7 +1,7 @@ --- title: ALTER TABLE sidebar_position: 4 -slug: /sql/sql-commands/ddl/table/alter-table +slug: /sql-commands/ddl/table/alter-table --- import FunctionDescription from '@site/src/components/FunctionDescription'; diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/07-aggregating-index/create-aggregating-index.md b/docs/en/sql-reference/10-sql-commands/00-ddl/07-aggregating-index/create-aggregating-index.md index 47d9759607..fc0db28b92 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/07-aggregating-index/create-aggregating-index.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/07-aggregating-index/create-aggregating-index.md @@ -12,11 +12,9 @@ Create a new aggregating index in Databend. ## Syntax ```sql -CREATE [ OR REPLACE ] [ ASYNC ] AGGREGATING INDEX AS SELECT ... +CREATE [ OR REPLACE ] AGGREGATING INDEX AS SELECT ... ``` -- `ASYNC` Option: Adding ASYNC is optional. It allows the index to be created asynchronously. This means the index isn't built right away. To build it later, use the [REFRESH AGGREGATING INDEX](refresh-aggregating-index.md) command. - - When creating aggregating indexes, limit their usage to standard [Aggregate Functions](../../../20-sql-functions/07-aggregate-functions/index.md) (e.g., AVG, SUM, MIN, MAX, COUNT and GROUP BY), while keeping in mind that GROUPING SETS, [Window Functions](../../../20-sql-functions/08-window-functions/index.md), [LIMIT](../../20-query-syntax/01-query-select.md#limit-clause), and [ORDER BY](../../20-query-syntax/01-query-select.md#order-by-clause) are not accepted, or you will get an error: `Currently create aggregating index just support simple query, like: SELECT ... FROM ... WHERE ... GROUP BY ...`. - The query filter scope defined when creating aggregating indexes should either match or encompass the scope of your actual queries. diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/07-aggregating-index/refresh-aggregating-index.md b/docs/en/sql-reference/10-sql-commands/00-ddl/07-aggregating-index/refresh-aggregating-index.md index feaa49f12e..59e1e03fa5 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/07-aggregating-index/refresh-aggregating-index.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/07-aggregating-index/refresh-aggregating-index.md @@ -7,34 +7,30 @@ import FunctionDescription from '@site/src/components/FunctionDescription'; +Databend automatically maintains aggregating indexes in `SYNC` mode as new data is ingested. Run `REFRESH AGGREGATING INDEX` when you introduce an index on a table that already contains data so earlier rows are backfilled. + ## Syntax ```sql -REFRESH AGGREGATING INDEX [ LIMIT ] +REFRESH AGGREGATING INDEX ``` -The "LIMIT" parameter allows you to control the maximum number of blocks that can be updated with each refresh action. It is strongly recommended to use this parameter with a defined limit to optimize memory usage. Please also note that setting a limit may result in partial data updates. For example, if you have 100 blocks but set a limit of 10, a single refresh might not update the most recent data, potentially leaving some blocks unrefreshed. You may need to execute multiple refresh actions to ensure a complete update. - -## When to Use REFRESH AGGREGATING INDEX - -- **When Automatic Updates Fail:** In cases where the default automatic updates (`SYNC` mode) do not work properly, use `REFRESH AGGREGATING INDEX` to include any missed data in the index. -- **For ASYNC Indexes:** If aggregating index is created with the `ASYNC` option, it won't update automatically. You need to manually refresh it using `REFRESH AGGREGATING INDEX`. - ## Examples -This example creates and refreshes an aggregating index named *my_agg_index*: +This example creates an aggregating index on a table that already contains data, then runs `REFRESH` once to backfill those rows: ```sql --- Prepare data +-- Prepare a table and load data before the index exists CREATE TABLE agg(a int, b int, c int); INSERT INTO agg VALUES (1,1,4), (1,2,1), (1,2,4); --- Create an aggregating index +-- Declare the aggregating index (existing rows are not indexed yet) CREATE AGGREGATING INDEX my_agg_index AS SELECT MIN(a), MAX(c) FROM agg; --- Insert new data -INSERT INTO agg VALUES (2,2,5); - --- Refresh the aggregating index +-- Backfill previously inserted rows REFRESH AGGREGATING INDEX my_agg_index; + +-- Insert new data after the index exists (no manual refresh needed) +INSERT INTO agg VALUES (2,2,5); +-- SYNC mode keeps the index current automatically ``` diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/07-inverted-index/refresh-inverted-index.md b/docs/en/sql-reference/10-sql-commands/00-ddl/07-inverted-index/refresh-inverted-index.md index 7c706dd5ea..291a1de503 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/07-inverted-index/refresh-inverted-index.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/07-inverted-index/refresh-inverted-index.md @@ -7,10 +7,7 @@ import FunctionDescription from '@site/src/components/FunctionDescription'; -Refreshes an inverted index in Databend. An inverted index requires refresh in the following scenarios: - -- When data is inserted into the table before creating the inverted index, manual refreshing of the inverted index is necessary post-creation to effectively index the inserted data. -- When the inverted index encounters issues or becomes corrupted, it needs to be refreshed. If the inverted index breaks due to certain blocks' inverted index files being corrupted, a query such as `where match(body, 'wiki')` will return an error. In such instances, you need to refresh the inverted index to fix the issue. +Databend automatically refreshes inverted indexes in `SYNC` mode whenever new data is written. Use `REFRESH INVERTED INDEX` primarily to backfill rows that existed before the index was declared. ## Syntax @@ -25,6 +22,17 @@ REFRESH INVERTED INDEX ON [.]
[LIMIT ] ## Examples ```sql --- Refresh an inverted index named "customer_feedback_idx" for the table "customer_feedback" +-- Existing table with data loaded before the index was declared +CREATE TABLE IF NOT EXISTS customer_feedback(id INT, body STRING); +INSERT INTO customer_feedback VALUES + (1, 'Great coffee beans'), + (2, 'Needs fresh roasting'); + +-- Create the inverted index afterward +CREATE INVERTED INDEX customer_feedback_idx ON customer_feedback(body); + +-- Backfill historical rows so the index covers earlier inserts REFRESH INVERTED INDEX customer_feedback_idx ON customer_feedback; + +-- Future inserts refresh automatically in SYNC mode ``` diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/07-ngram-index/refresh-ngram-index.md b/docs/en/sql-reference/10-sql-commands/00-ddl/07-ngram-index/refresh-ngram-index.md index 79d6a30d44..bc4e2a6e9f 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/07-ngram-index/refresh-ngram-index.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/07-ngram-index/refresh-ngram-index.md @@ -7,7 +7,7 @@ import FunctionDescription from '@site/src/components/FunctionDescription'; -Refresh an existing NGRAM index from a table. +Databend automatically refreshes NGRAM indexes when data is ingested. Use `REFRESH NGRAM INDEX` when you need to backfill data that existed before the index was defined. ## Syntax @@ -18,8 +18,18 @@ ON [.]; ## Examples -The following example refreshes the `idx1` index from the `amazon_reviews_ngram` table: - ```sql +-- Table already populated before the NGRAM index exists +CREATE TABLE IF NOT EXISTS amazon_reviews_ngram(review_id INT, review STRING); +INSERT INTO amazon_reviews_ngram VALUES + (1, 'coffee beans from Colombia'), + (2, 'best roasting kit'); + +-- Declare the NGRAM index afterward +CREATE NGRAM INDEX idx1 ON amazon_reviews_ngram(review) WITH (ngram_size = 3); + +-- Refresh so the pre-existing rows are indexed REFRESH NGRAM INDEX idx1 ON amazon_reviews_ngram; + +-- Subsequent inserts refresh automatically in SYNC mode ```