This is an automated email from the ASF dual-hosted git repository.
morningman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 50efee5b792 Fix schema change docs: NOT NULL to NULL is supported
(#4107)
50efee5b792 is described below
commit 50efee5b79282dfd23f0f253020ebb786582b201
Author: ZhenchaoXu <[email protected]>
AuthorDate: Sat Sep 26 17:29:55 2026 +0800
Fix schema change docs: NOT NULL to NULL is supported (#4107)
## Summary
- Clarify nullable modification rules in the Schema Change
documentation: **NOT NULL → NULL is supported** (heavyweight Schema
Change); **NULL → NOT NULL is not supported**.
- Remove the incorrect blanket limitation that all Nullable attribute
changes are unsupported, which contradicted examples on the same page
and actual Doris behavior (`Column.checkSchemaChangeAllowed()`).
- Add an explicit `MODIFY COLUMN ... NULL` example and list NOT NULL →
NULL under heavyweight Schema Change operations.
## Motivation
The current Limitations table states:
> Modifying the aggregation type, Nullable attribute, and default value
is not supported
This is misleading for operators changing columns to nullable (e.g.
`MODIFY COLUMN col INT NULL`), which triggers a heavyweight Schema
Change job and is covered by regression tests
(`test_alter_table_column_nullable.groovy`).
## Files changed
- `docs/table-design/schema-change.md` (dev/current, EN)
- `i18n/zh-CN/.../current/table-design/schema-change.md` (dev/current,
ZH)
- `versioned_docs/version-4.x/table-design/schema-change.md` (4.x, EN)
- `i18n/zh-CN/.../version-4.x/table-design/schema-change.md` (4.x, ZH)
## Test plan
- [x] Verified wording against Doris FE source:
`fe/fe-core/src/main/java/org/apache/doris/catalog/Column.java`
(`checkSchemaChangeAllowed`)
- [x] Aligned with existing doc example `MODIFY COLUMN col3 varchar(50)
KEY NULL`
- [x] Aligned with regression test
`regression-test/suites/schema_change_p0/test_alter_table_column_nullable.groovy`
Made with [Cursor](https://cursor.com)
---------
Co-authored-by: Cursor <[email protected]>
---
docs/table-design/schema-change.md | 20 +++++++++++++++-----
.../current/table-design/schema-change.md | 20 +++++++++++++++-----
.../version-3.x/table-design/schema-change.md | 22 ++++++++++++++++------
.../version-4.x/table-design/schema-change.md | 20 +++++++++++++++-----
.../version-3.x/table-design/schema-change.md | 22 ++++++++++++++++------
.../version-4.x/table-design/schema-change.md | 20 +++++++++++++++-----
6 files changed, 92 insertions(+), 32 deletions(-)
diff --git a/docs/table-design/schema-change.md
b/docs/table-design/schema-change.md
index a6442198b55..f0bcd05e50e 100644
--- a/docs/table-design/schema-change.md
+++ b/docs/table-design/schema-change.md
@@ -33,7 +33,7 @@ Doris supports two types of Schema Change operations:
**lightweight** and **heav
| Requires data rewrite | No, only metadata is modified
| Yes, involves rewriting data files
|
| System performance impact | Small impact
| May affect system performance, especially during data conversion
|
| Resource consumption | Low
| High, occupies compute resources; storage usage of table data
doubles during the process |
-| Typical operations | Add / drop value columns, rename columns, modify
VARCHAR length | Modify column data types, change primary keys, modify column
order, etc. |
+| Typical operations | Add / drop value columns, rename columns, modify
VARCHAR length | Modify column data types, change NOT NULL to NULL, change
primary keys, modify column order, etc. |
### Lightweight Schema Change
@@ -48,6 +48,7 @@ Doris supports two types of Schema Change operations:
**lightweight** and **heav
**Involves rewriting or converting data files**, with the actual modification
or reorganization performed by the Backend (BE) in the background. All
operations not in the lightweight category are heavyweight, for example:
- Modifying the data type of a column.
+- Changing a column from NOT NULL to NULL.
- Modifying the sort order of columns.
Execution flow:
@@ -201,7 +202,8 @@ Notes:
- When modifying a value column in an aggregate model, you must specify
`agg_type`.
- When modifying a key column in a non-aggregate model, you must specify the
`KEY` keyword.
-- You can only modify the type of a column. Other column attributes must
remain unchanged.
+- When modifying column **type**, the aggregation method and default value
must stay the same as the original column.
+- Changing a column from **NOT NULL to NULL** is supported and runs as a
heavyweight Schema Change. Changing from **NULL to NOT NULL** is not supported.
- **Partition columns and bucketing columns cannot be modified in any way.**
- Pay attention to precision loss when modifying columns. For supported type
conversions, see [Supported Type Conversions](#supported-type-conversions)
below.
@@ -228,7 +230,7 @@ Example:
MODIFY COLUMN col1 BIGINT KEY DEFAULT "1" AFTER col2;
```
-3. Modify the maximum length of the `col5` column in the base table. The
original `col5` is `VARCHAR(32) REPLACE DEFAULT "abc"` (you can only modify the
column type; other attributes must remain unchanged):
+3. Modify the maximum length of the `col5` column in the base table. The
original `col5` is `VARCHAR(32) REPLACE DEFAULT "abc"` (only the VARCHAR length
changes; aggregation method and default value must remain unchanged):
```sql
ALTER TABLE example_db.my_table
@@ -242,6 +244,13 @@ Example:
MODIFY COLUMN col3 varchar(50) KEY NULL COMMENT 'to 50';
```
+5. Change a column from NOT NULL to NULL (heavyweight Schema Change):
+
+ ```sql
+ ALTER TABLE example_db.my_table
+ MODIFY COLUMN col2 INT NULL;
+ ```
+
#### Supported Type Conversions
Pay attention to precision loss when modifying column types. The following
conversions are currently supported:
@@ -330,8 +339,9 @@ CANCEL ALTER TABLE COLUMN FROM tbl_name;
| **Immutable columns** | Partition columns and bucketing columns cannot be
modified |
| **Key column deletion** | When an aggregate table contains value columns
aggregated with REPLACE, key columns cannot be deleted; key columns of a Unique
table also cannot be deleted |
| **Aggregate default value** | When adding a SUM or REPLACE type value
column, because the historical data has lost its detail information, the
default value cannot actually reflect the post-aggregation value and is
meaningless for historical data |
-| **Type modification** | Only the column type can be modified; other fields
such as the aggregation method, Nullable, and default value must be filled in
according to the original column information |
-| **Unsupported modifications** | Modifying the aggregation type, Nullable
attribute, and default value is not supported |
+| **Type modification** | When modifying column type, the aggregation method
and default value must match the original column information |
+| **Nullable modification** | Changing NOT NULL to NULL is supported
(heavyweight Schema Change). Changing NULL to NOT NULL is not supported |
+| **Unsupported modifications** | Modifying the aggregation type or default
value is not supported |
## Related Configuration
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/table-design/schema-change.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/table-design/schema-change.md
index fda989a8873..0152a50a8ab 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/table-design/schema-change.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/table-design/schema-change.md
@@ -33,7 +33,7 @@ Doris 支持两种类型的 Schema Change 操作：**轻量级**与**重量级**
| 是否需要数据重写 | 不需要，仅修改元数据 | 需要，涉及数据文件的重写
|
| 系统性能影响 | 影响较小 |
可能影响系统性能，尤其在数据转换过程中 |
| 资源消耗 | 较低 |
较高，占用计算资源；过程中表数据占用的存储空间会翻倍 |
-| 典型操作 | 增加 / 删除 Value 列、修改列名、修改 VARCHAR 长度 | 修改列的数据类型、更改主键、修改列的顺序等
|
+| 典型操作 | 增加 / 删除 Value 列、修改列名、修改 VARCHAR 长度 | 修改列的数据类型、NOT NULL 改为
NULL、更改主键、修改列的顺序等 |
### 轻量级 Schema Change
@@ -48,6 +48,7 @@ Doris 支持两种类型的 Schema Change 操作：**轻量级**与**重量级**
**涉及数据文件的重写或转换**，由 Backend（BE）在后台完成实际修改或重新组织。所有不属于轻量级范围的操作都属于重量级，例如：
- 修改列的数据类型。
+- 将列从 NOT NULL 修改为 NULL。
- 修改列的排序顺序。
执行流程：
@@ -201,7 +202,8 @@ ALTER TABLE [database.]table RENAME COLUMN old_column_name
new_column_name;
- 聚合模型修改 Value 列时，需要指定 `agg_type`。
- 非聚合模型修改 Key 列时，需要指定 `KEY` 关键字。
-- 只能修改列的类型，列的其他属性需要维持原样。
+- 修改列**类型**时，聚合方式与默认值必须与原列保持一致。
+- 将列从 **NOT NULL 修改为 NULL** 支持，走重量级 Schema Change；从 **NULL 修改为 NOT NULL** 不支持。
- **分区列和分桶列不能做任何修改**。
- 修改列时需注意精度损失，支持的类型转换详见下文 [支持的类型转换](#支持的类型转换)。
@@ -228,7 +230,7 @@ ALTER TABLE [database.]table RENAME COLUMN old_column_name
new_column_name;
MODIFY COLUMN col1 BIGINT KEY DEFAULT "1" AFTER col2;
```
-3. 修改 Base Table 的 `col5` 列最大长度，原 `col5` 为 `VARCHAR(32) REPLACE DEFAULT
"abc"`（只能修改列的类型，其他属性需维持原样）：
+3. 修改 Base Table 的 `col5` 列最大长度，原 `col5` 为 `VARCHAR(32) REPLACE DEFAULT
"abc"`（仅修改 VARCHAR 长度；聚合方式与默认值需维持原样）：
```sql
ALTER TABLE example_db.my_table
@@ -242,6 +244,13 @@ ALTER TABLE [database.]table RENAME COLUMN old_column_name
new_column_name;
MODIFY COLUMN col3 varchar(50) KEY NULL COMMENT 'to 50';
```
+5. 将列从 NOT NULL 修改为 NULL（重量级 Schema Change）：
+
+ ```sql
+ ALTER TABLE example_db.my_table
+ MODIFY COLUMN col2 INT NULL;
+ ```
+
#### 支持的类型转换
修改列类型时请注意精度损失，目前支持以下转换：
@@ -330,8 +339,9 @@ CANCEL ALTER TABLE COLUMN FROM tbl_name;
| **不可变列** | 分区列和分桶列不能修改
|
| **Key 列删除** | 聚合表中含 REPLACE 方式聚合的 Value 列时，不允许删除 Key 列；Unique 表也不允许删除 Key
列 |
| **聚合默认值** | 新增 SUM 或 REPLACE 类型 Value
列时，因历史数据已失去明细信息，默认值无法实际反映聚合后的取值，对历史数据没有含义 |
-| **类型修改** | 只能修改列的 Type；聚合方式、Nullable、默认值等其余字段必须按原列信息补全
|
-| **不支持的修改** | 不支持修改聚合类型、Nullable 属性和默认值
|
+| **类型修改** | 修改列类型时，聚合方式与默认值必须与原列信息一致 |
+| **Nullable 修改** | 支持 NOT NULL 修改为 NULL（重量级 Schema Change）；不支持 NULL 修改为 NOT
NULL |
+| **不支持的修改** | 不支持修改聚合类型或默认值
|
## 相关配置
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/table-design/schema-change.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/table-design/schema-change.md
index 1845457be76..5b0fcc0623c 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/table-design/schema-change.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/table-design/schema-change.md
@@ -18,7 +18,7 @@ Doris 支持两种类型的 Schema Change 操作：轻量级 Schema Change 和
| 是否需要数据重写 | 不需要 | 需要，涉及数据文件的重写 |
| 系统性能影响 | 影响较小 | 可能影响系统性能，尤其是在数据转换过程中 |
| 资源消耗 | 较低 | 较高，会占用计算资源重新组织数据，过程中涉及到的表的数据占用的存储空间翻倍。
|
-| 操作类型 | 增加、删除 Value 列，修改列名，修改 VARCHAR 长度 | 修改列的数据类型、更改主键、修改列的顺序等 |
+| 操作类型 | 增加、删除 Value 列，修改列名，修改 VARCHAR 长度 | 修改列的数据类型、NOT NULL 改为
NULL、更改主键、修改列的顺序等 |
### 轻量级 Schema Change
@@ -33,6 +33,7 @@ Doris 支持两种类型的 Schema Change 操作：轻量级 Schema Change 和
重量级 Schema Change 涉及到数据文件的重写或转换，这些操作相对复杂，通常需要借助 Doris 的
Backend（BE）进行数据的实际修改或重新组织。重量级 Schema Change
操作通常涉及对表数据结构的深度变更，可能会影响到存储的物理布局。所有不支持轻量级 Schema Change 的操作，均属于重量级 Schema
Change，比如：
- 更改列的数据类型
+- 将列从 NOT NULL 修改为 NULL
- 修改列的排序顺序
重量级操作会在后台启动一个任务进行数据转换。后台任务会对表的每个 tablet 进行转换，按 tablet
为单位，将原始数据重写到新的数据文件中。数据转换过程中，可能会出现数据"双写"现象，即在转换期间，新数据同时写入新 tablet 旧 tablet
中。完成数据转换后，旧 tablet 会被删除，新 tablet 将取而代之。
@@ -199,7 +200,9 @@ ALTER TABLE example_db.my_table DROP COLUMN col4;
- 非聚合类型如果修改 Key 列，需要指定 **KEY** 关键字
-- 只能修改列的类型，列的其他属性维持原样
+- 修改列**类型**时，聚合方式与默认值必须与原列保持一致。
+
+- 将列从 **NOT NULL 修改为 NULL** 支持，走重量级 Schema Change；从 **NULL 修改为 NOT NULL** 不支持。
- 分区列和分桶列不能做任何修改
@@ -256,7 +259,7 @@ ALTER TABLE example_db.my_table
MODIFY COLUMN col5 VARCHAR(64) REPLACE DEFAULT "abc";
```
-注意：只能修改列的类型，列的其他属性需要维持原样
+注意：仅修改 VARCHAR 长度；聚合方式与默认值需维持原样
3. 修改 Key 列的某个字段的长度
@@ -265,6 +268,13 @@ ALTER TABLE example_db.my_table
MODIFY COLUMN col3 varchar(50) KEY NULL comment 'to 50';
```
+4. 将列从 NOT NULL 修改为 NULL（重量级 Schema Change）
+
+```sql
+ALTER TABLE example_db.my_table
+MODIFY COLUMN col2 INT NULL;
+```
+
### 重新排序
- 所有列都要写出来
@@ -304,11 +314,11 @@ ORDER BY (k3,k1,k2,k4,v2,v1);
- 因为历史数据已经失去明细信息，所以默认值的取值并不能实际反映聚合后的取值。
-- 当修改列类型时，除 Type 以外的字段都需要按原列上的信息补全。
+- 修改列类型时，聚合方式与默认值必须与原列信息一致。
-- 注意，除新的列类型外，如聚合方式，Nullable 属性，以及默认值都要按照原信息补全。
+- 支持 **NOT NULL 修改为 NULL**（重量级 Schema Change）；不支持 **NULL 修改为 NOT NULL**。
-- 不支持修改聚合类型、Nullable 属性和默认值。
+- 不支持修改聚合类型或默认值。
## 相关配置
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/table-design/schema-change.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/table-design/schema-change.md
index fda989a8873..0152a50a8ab 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/table-design/schema-change.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/table-design/schema-change.md
@@ -33,7 +33,7 @@ Doris 支持两种类型的 Schema Change 操作：**轻量级**与**重量级**
| 是否需要数据重写 | 不需要，仅修改元数据 | 需要，涉及数据文件的重写
|
| 系统性能影响 | 影响较小 |
可能影响系统性能，尤其在数据转换过程中 |
| 资源消耗 | 较低 |
较高，占用计算资源；过程中表数据占用的存储空间会翻倍 |
-| 典型操作 | 增加 / 删除 Value 列、修改列名、修改 VARCHAR 长度 | 修改列的数据类型、更改主键、修改列的顺序等
|
+| 典型操作 | 增加 / 删除 Value 列、修改列名、修改 VARCHAR 长度 | 修改列的数据类型、NOT NULL 改为
NULL、更改主键、修改列的顺序等 |
### 轻量级 Schema Change
@@ -48,6 +48,7 @@ Doris 支持两种类型的 Schema Change 操作：**轻量级**与**重量级**
**涉及数据文件的重写或转换**，由 Backend（BE）在后台完成实际修改或重新组织。所有不属于轻量级范围的操作都属于重量级，例如：
- 修改列的数据类型。
+- 将列从 NOT NULL 修改为 NULL。
- 修改列的排序顺序。
执行流程：
@@ -201,7 +202,8 @@ ALTER TABLE [database.]table RENAME COLUMN old_column_name
new_column_name;
- 聚合模型修改 Value 列时，需要指定 `agg_type`。
- 非聚合模型修改 Key 列时，需要指定 `KEY` 关键字。
-- 只能修改列的类型，列的其他属性需要维持原样。
+- 修改列**类型**时，聚合方式与默认值必须与原列保持一致。
+- 将列从 **NOT NULL 修改为 NULL** 支持，走重量级 Schema Change；从 **NULL 修改为 NOT NULL** 不支持。
- **分区列和分桶列不能做任何修改**。
- 修改列时需注意精度损失，支持的类型转换详见下文 [支持的类型转换](#支持的类型转换)。
@@ -228,7 +230,7 @@ ALTER TABLE [database.]table RENAME COLUMN old_column_name
new_column_name;
MODIFY COLUMN col1 BIGINT KEY DEFAULT "1" AFTER col2;
```
-3. 修改 Base Table 的 `col5` 列最大长度，原 `col5` 为 `VARCHAR(32) REPLACE DEFAULT
"abc"`（只能修改列的类型，其他属性需维持原样）：
+3. 修改 Base Table 的 `col5` 列最大长度，原 `col5` 为 `VARCHAR(32) REPLACE DEFAULT
"abc"`（仅修改 VARCHAR 长度；聚合方式与默认值需维持原样）：
```sql
ALTER TABLE example_db.my_table
@@ -242,6 +244,13 @@ ALTER TABLE [database.]table RENAME COLUMN old_column_name
new_column_name;
MODIFY COLUMN col3 varchar(50) KEY NULL COMMENT 'to 50';
```
+5. 将列从 NOT NULL 修改为 NULL（重量级 Schema Change）：
+
+ ```sql
+ ALTER TABLE example_db.my_table
+ MODIFY COLUMN col2 INT NULL;
+ ```
+
#### 支持的类型转换
修改列类型时请注意精度损失，目前支持以下转换：
@@ -330,8 +339,9 @@ CANCEL ALTER TABLE COLUMN FROM tbl_name;
| **不可变列** | 分区列和分桶列不能修改
|
| **Key 列删除** | 聚合表中含 REPLACE 方式聚合的 Value 列时，不允许删除 Key 列；Unique 表也不允许删除 Key
列 |
| **聚合默认值** | 新增 SUM 或 REPLACE 类型 Value
列时，因历史数据已失去明细信息，默认值无法实际反映聚合后的取值，对历史数据没有含义 |
-| **类型修改** | 只能修改列的 Type；聚合方式、Nullable、默认值等其余字段必须按原列信息补全
|
-| **不支持的修改** | 不支持修改聚合类型、Nullable 属性和默认值
|
+| **类型修改** | 修改列类型时，聚合方式与默认值必须与原列信息一致 |
+| **Nullable 修改** | 支持 NOT NULL 修改为 NULL（重量级 Schema Change）；不支持 NULL 修改为 NOT
NULL |
+| **不支持的修改** | 不支持修改聚合类型或默认值
|
## 相关配置
diff --git a/versioned_docs/version-3.x/table-design/schema-change.md
b/versioned_docs/version-3.x/table-design/schema-change.md
index af36fb49e09..1b276e3f6fe 100644
--- a/versioned_docs/version-3.x/table-design/schema-change.md
+++ b/versioned_docs/version-3.x/table-design/schema-change.md
@@ -18,7 +18,7 @@ Doris supports two types of schema change operations:
lightweight schema change
| Data Rewrite Needed | No | Yes, involves rewriting
data files |
| System Performance Impact | Minimal | May impact system
performance, especially during data conversion |
| Resource Consumption | Low | High, will consume
computing resources to reorganize data, and the storage space occupied by the
table's data involved in the process will double. |
-| Operation Types | Add, delete value columns, rename columns, modify
VARCHAR length | Modify column data types, change primary keys, modify column
order, etc. |
+| Operation Types | Add, delete value columns, rename columns, modify
VARCHAR length | Modify column data types, change NOT NULL to NULL, change
primary keys, modify column order, etc. |
### Lightweight Schema Change
@@ -33,6 +33,7 @@ Lightweight schema change refers to simple schema
modification operations that d
Heavyweight schema change involves rewriting or converting data files, and
these operations are relatively complex, usually requiring the assistance of
Doris's Backend (BE) to perform actual data modifications or reorganizations.
Heavyweight schema change operations typically involve deep changes to the
table's data structure and may affect the physical layout of storage. All
operations that do not support lightweight schema changes fall under
heavyweight schema changes, such as:
- Changing the data type of a column
+- Changing a column from NOT NULL to NULL
- Modifying the order of columns
Heavyweight operations will start a task in the background for data
conversion. The background task will convert each tablet of the table,
rewriting the original data into new data files on a tablet basis. During the
data conversion process, a "double write" phenomenon may occur, where new data
is simultaneously written to both the new tablet and the old tablet. After the
data conversion is complete, the old tablet will be deleted, and the new tablet
will replace it.
@@ -199,7 +200,9 @@ ALTER TABLE example_db.my_table DROP COLUMN col4;
- If a non-aggregate type modifies a key column, the **KEY** keyword must be
specified.
-- Only the type of the column can be modified; other attributes of the column
must remain the same.
+- When modifying column **type**, the aggregation method and default value
must stay the same as the original column.
+
+- Changing a column from **NOT NULL to NULL** is supported and runs as a
heavyweight Schema Change. Changing from **NULL to NOT NULL** is not supported.
- Partition columns and bucket columns cannot be modified.
@@ -255,7 +258,7 @@ ALTER TABLE example_db.my_table
MODIFY COLUMN col5 VARCHAR(64) REPLACE DEFAULT "abc";
```
-Note: Only the type of the column can be modified; other attributes of the
column must remain the same.
+Note: Only the VARCHAR length changes; aggregation method and default value
must remain unchanged.
4. Modify the length of a field in a key column
@@ -264,6 +267,13 @@ ALTER TABLE example_db.my_table
MODIFY COLUMN col3 varchar(50) KEY NULL comment 'to 50';
```
+5. Change a column from NOT NULL to NULL (heavyweight Schema Change)
+
+```sql
+ALTER TABLE example_db.my_table
+MODIFY COLUMN col2 INT NULL;
+```
+
### Reorder
- All columns must be listed.
@@ -303,11 +313,11 @@ ORDER BY (k3,k1,k2,k4,v2,v1);
- Because historical data has lost detailed information, the value of the
default cannot actually reflect the aggregated value.
-- When modifying column types, all fields except Type must be supplemented
with the original column's information.
+- When modifying column types, the aggregation method and default value must
match the original column information.
-- Note that, except for the new column type, aggregation method, Nullable
attribute, and default value must be supplemented according to the original
information.
+- Changing **NOT NULL to NULL** is supported (heavyweight Schema Change).
Changing **NULL to NOT NULL** is not supported.
-- Modifying aggregation types, Nullable attributes, and default values is not
supported.
+- Modifying aggregation types or default values is not supported.
## Related Configurations
diff --git a/versioned_docs/version-4.x/table-design/schema-change.md
b/versioned_docs/version-4.x/table-design/schema-change.md
index a6442198b55..f0bcd05e50e 100644
--- a/versioned_docs/version-4.x/table-design/schema-change.md
+++ b/versioned_docs/version-4.x/table-design/schema-change.md
@@ -33,7 +33,7 @@ Doris supports two types of Schema Change operations:
**lightweight** and **heav
| Requires data rewrite | No, only metadata is modified
| Yes, involves rewriting data files
|
| System performance impact | Small impact
| May affect system performance, especially during data conversion
|
| Resource consumption | Low
| High, occupies compute resources; storage usage of table data
doubles during the process |
-| Typical operations | Add / drop value columns, rename columns, modify
VARCHAR length | Modify column data types, change primary keys, modify column
order, etc. |
+| Typical operations | Add / drop value columns, rename columns, modify
VARCHAR length | Modify column data types, change NOT NULL to NULL, change
primary keys, modify column order, etc. |
### Lightweight Schema Change
@@ -48,6 +48,7 @@ Doris supports two types of Schema Change operations:
**lightweight** and **heav
**Involves rewriting or converting data files**, with the actual modification
or reorganization performed by the Backend (BE) in the background. All
operations not in the lightweight category are heavyweight, for example:
- Modifying the data type of a column.
+- Changing a column from NOT NULL to NULL.
- Modifying the sort order of columns.
Execution flow:
@@ -201,7 +202,8 @@ Notes:
- When modifying a value column in an aggregate model, you must specify
`agg_type`.
- When modifying a key column in a non-aggregate model, you must specify the
`KEY` keyword.
-- You can only modify the type of a column. Other column attributes must
remain unchanged.
+- When modifying column **type**, the aggregation method and default value
must stay the same as the original column.
+- Changing a column from **NOT NULL to NULL** is supported and runs as a
heavyweight Schema Change. Changing from **NULL to NOT NULL** is not supported.
- **Partition columns and bucketing columns cannot be modified in any way.**
- Pay attention to precision loss when modifying columns. For supported type
conversions, see [Supported Type Conversions](#supported-type-conversions)
below.
@@ -228,7 +230,7 @@ Example:
MODIFY COLUMN col1 BIGINT KEY DEFAULT "1" AFTER col2;
```
-3. Modify the maximum length of the `col5` column in the base table. The
original `col5` is `VARCHAR(32) REPLACE DEFAULT "abc"` (you can only modify the
column type; other attributes must remain unchanged):
+3. Modify the maximum length of the `col5` column in the base table. The
original `col5` is `VARCHAR(32) REPLACE DEFAULT "abc"` (only the VARCHAR length
changes; aggregation method and default value must remain unchanged):
```sql
ALTER TABLE example_db.my_table
@@ -242,6 +244,13 @@ Example:
MODIFY COLUMN col3 varchar(50) KEY NULL COMMENT 'to 50';
```
+5. Change a column from NOT NULL to NULL (heavyweight Schema Change):
+
+ ```sql
+ ALTER TABLE example_db.my_table
+ MODIFY COLUMN col2 INT NULL;
+ ```
+
#### Supported Type Conversions
Pay attention to precision loss when modifying column types. The following
conversions are currently supported:
@@ -330,8 +339,9 @@ CANCEL ALTER TABLE COLUMN FROM tbl_name;
| **Immutable columns** | Partition columns and bucketing columns cannot be
modified |
| **Key column deletion** | When an aggregate table contains value columns
aggregated with REPLACE, key columns cannot be deleted; key columns of a Unique
table also cannot be deleted |
| **Aggregate default value** | When adding a SUM or REPLACE type value
column, because the historical data has lost its detail information, the
default value cannot actually reflect the post-aggregation value and is
meaningless for historical data |
-| **Type modification** | Only the column type can be modified; other fields
such as the aggregation method, Nullable, and default value must be filled in
according to the original column information |
-| **Unsupported modifications** | Modifying the aggregation type, Nullable
attribute, and default value is not supported |
+| **Type modification** | When modifying column type, the aggregation method
and default value must match the original column information |
+| **Nullable modification** | Changing NOT NULL to NULL is supported
(heavyweight Schema Change). Changing NULL to NOT NULL is not supported |
+| **Unsupported modifications** | Modifying the aggregation type or default
value is not supported |
## Related Configuration
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
