update flexible partial update docs

docs/data-operate/update/update-of-unique-model.md

@@ -119,15 +119,14 @@ Performance optimization suggestions:
 
 Currently, all rows in the same batch data writing task (whether a load task or `INSERT INTO`) can only update the same columns. To update data with different columns, write in different batches.
 
-## Flexible Partial Column Updates (Experimental Feature)
+## Flexible Partial Column Updates
 
-Previously, Doris's partial update feature required that every row in an import update the same columns. Now, Doris supports a more flexible partial update method that allows each row in a single import to update different columns(only supported on the master branch).
+Previously, Doris's partial update feature required that every row in an import update the same columns. Now, Doris supports a more flexible partial update method that allows each row in a single import to update different columns(supported since 3.1.0).
 
 :::caution Note:
 
-1. The flexible partial update feature is still in the internal testing.
-2. Currently, only the Stream Load import method and tools using Stream Load (e.g. Doris-Flink-Connector) support this feature.
-3. The import file must be in JSON format when using flexible column updates.
+1. Currently, only the Stream Load import method and tools using Stream Load (e.g. Doris-Flink-Connector) support this feature.
+2. The import file must be in JSON format when using flexible column updates.
 :::
 
 ### Applicable Scenarios

docs/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md

@@ -368,7 +368,7 @@ The functionality of creating synchronized materialized views with rollup is lim
 | group_commit_data_bytes | Configures the Group Commit batch data size for this table. The unit is bytes, with a default value of 134217728, i.e., 128MB. The timing of Group Commit depends on which of `group_commit_interval_ms` and `group_commit_data_bytes` reaches the set value first. |
 | enable_mow_light_delete | Whether to enable writing Delete predicate with Delete statements on Unique tables with Mow. If enabled, it will improve the performance of Delete statements, but partial column updates after Delete may result in some data errors. If disabled, it will reduce the performance of Delete statements to ensure correctness. The default value of this property is `false`. This property can only be enabled on Unique Merge-on-Write tables. |
 | Dynamic Partitioning Related Properties | For dynamic partitioning, refer to [Data Partitioning - Dynamic Partitioning](../../../../table-design/data-partitioning/dynamic-partitioning) |
-
+| enable_unique_key_skip_bitmap_column | Whether to enable the [Flexible Column Update feature](../../../../data-operate/update/update-of-unique-model.md#flexible-partial-column-updates) on Unique Merge-on-Write tables. This property can only be enabled on Unique Merge-on-Write tables. |
 
 ## Access Control Requirements
 

i18n/zh-CN/docusaurus-plugin-content-docs/current/data-operate/update/update-of-unique-model.md

@@ -119,15 +119,14 @@ INSERT INTO order_tbl (order_id, order_status) VALUES (1, '待发货');
 
 目前，同一批次数据写入任务（无论是导入任务还是 `INSERT INTO`）的所有行只能更新相同的列。如果需要更新不同列的数据，则需要分不同批次进行写入。
 
-## 灵活部分列更新（实验性功能）
+## 灵活部分列更新
 
-此前，doris 支持的部分列更新功能限制了一次导入中每一行必须更新相同的列。现在，doris 支持一种更加灵活的更新方式，它使得一次导入中的每一行可以更新不同的列（仅 master 分支支持）。
+此前，doris 支持的部分列更新功能限制了一次导入中每一行必须更新相同的列。现在，doris 支持一种更加灵活的更新方式，它使得一次导入中的每一行可以更新不同的列（3.1.0版本及以上支持）。
 
 :::caution 注意：
 
-1. 灵活列更新这一功能还在内测中
-2. 目前只有 stream load 这一种导入方式以及使用 stream load 作为其导入方式的工具 (如 doris-flink-connector) 支持灵活列更新功能
-3. 在使用灵活列更新时导入文件必须为 json 格式的数据
+1. 目前只有 stream load 这一种导入方式以及使用 stream load 作为其导入方式的工具 (如 doris-flink-connector) 支持灵活列更新功能
+2. 在使用灵活列更新时导入文件必须为 json 格式的数据
 :::
 
 ### 适用场景

i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md

@@ -369,7 +369,7 @@ rollup 可以创建的同步物化视图功能有限。已不再推荐使用。
 | group_commit_data_bytes                       | 配置这个表的 Group Commit 攒批数据大小。单位为 bytes，默认值为 134217728，即 128MB。Group Commit 的下刷时机取决于 `group_commit_interval_ms`以及`group_commit_data_bytes` 哪个先到设置的值。 |
 | enable_mow_light_delete                       | 是否在 Unique 表 Mow 上开启 Delete 语句写 Delete predicate。若开启，会提升 Delete 语句的性能，但 Delete 后进行部分列更新可能会出现部分数据错误的情况。若关闭，会降低 Delete 语句的性能来保证正确性。此属性的默认值为 `false`。此属性只能在 Unique Merge-on-Write 表上开启。 |
 | 动态分区相关属性                              | 动态分区相关参考[数据划分 - 动态分区](../../../../table-design/data-partitioning/dynamic-partitioning) |
-
+| enable_unique_key_skip_bitmap_column | 是否在 Unique Merge-on-Write 表上开启[灵活列更新功能](../../../../data-operate/update/update-of-unique-model.md#灵活部分列更新)。此属性只能在 Unique Merge-on-Write 表上开启。 |
 ## 权限控制
 
 执行此 SQL 命令的[用户](../../../../admin-manual/auth/authentication-and-authorization.md)必须至少具有以下[权限](../../../../admin-manual/auth/authentication-and-authorization.md)：

i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/data-operate/update/update-of-unique-model.md

@@ -120,3 +120,274 @@ INSERT INTO order_tbl (order_id, order_status) VALUES (1, '待发货');
 目前，同一批次数据写入任务（无论是导入任务还是 `INSERT INTO`）的所有行只能更新相同的列。如果需要更新不同列的数据，则需要分不同批次进行写入。
 
 在未来版本中，将支持灵活的列更新，用户可以在同一批导入中，每一行更新不同的列。
+
+## 灵活部分列更新
+
+> 该功能自 3.1.0 版本支持
+
+此前，doris 支持的部分列更新功能限制了一次导入中每一行必须更新相同的列。现在，doris 支持一种更加灵活的更新方式，它使得一次导入中的每一行可以更新不同的列。
+
+:::caution 注意：
+
+1. 目前只有 stream load 这一种导入方式以及使用 stream load 作为其导入方式的工具 (如 doris-flink-connector) 支持灵活列更新功能
+2. 在使用灵活列更新时导入文件必须为 json 格式的数据
+:::
+
+### 适用场景
+
+在使用 CDC 的方式将某个数据系统的数据实时同步到 Doris 中时，源端系统输出的记录可能并不是完整的行数据，而是只有主键和被更新的列的数据。在这种情况下，某个时间窗口内的一批数据中每一行更新的列可能都是不同的。此时，可以使用灵活列更新的方式来将数据导入到 Doris 中。
+
+### 使用方式
+
+**存量表开启灵活列更新功能**
+
+对于在旧版本 Doris 中已经建好的存量 Merge-On-Write 表，在升级 Doris 之后如果想要使用灵活列更新的功能，可以使用 `ALTER TALBE db1.tbl1 ENABLE FEATURE "UPDATE_FLEXIBLE_COLUMNS";` 来开启这一功能。执行完上述语句后使用 `show create table db1.tbl1` 的结果中如果包含 `"enable_unique_key_skip_bitmap_column" = "true"` 则表示功能开启成功。注意，使用这一方式之前需要确保目标表已经开启了 light-schema-change 的功能。
+
+**新建表使用灵活列更新功能**
+
+对于新建的表，如果需要使用灵活列更新功能，建表时需要指定如下表属性，以开启 Merge-on-Write 实现，开启 light-schema-change，同时使得表具有灵活列更新所需要的 `bitmap` 隐藏列。
+
+```Plain
+"enable_light_schema_change" = "true"
+"enable_unique_key_merge_on_write" = "true"
+"enable_unique_key_skip_bitmap_column" = "true"
+```
+
+**StreamLoad**
+
+在使用 Stream Load 导入时添加如下 header
+
+```Plain
+unique_key_update_mode:UPDATE_FLEXIBLE_COLUMNS
+```
+
+**Flink Doris Connector**
+
+如果使用 Flink Doris Connector, 需要添加如下配置：
+
+```Plain
+'sink.properties.unique_key_update_mode' = 'UPDATE_FLEXIBLE_COLUMNS'
+```
+
+### 示例
+
+假设有如下表
+
+```sql
+CREATE TABLE t1 (
+  `k` int(11) NULL, 
+  `v1` BIGINT NULL,
+  `v2` BIGINT NULL DEFAULT "9876",
+  `v3` BIGINT NOT NULL,
+  `v4` BIGINT NOT NULL DEFAULT "1234",
+  `v5` BIGINT NULL
+) UNIQUE KEY(`k`) DISTRIBUTED BY HASH(`k`) BUCKETS 1
+PROPERTIES(
+"replication_num" = "3",
+"enable_unique_key_merge_on_write" = "true",
+"enable_light_schema_change" = "true",
+"enable_unique_key_skip_bitmap_column" = "true");
+```
+
+表中有如下原始数据
+
+```sql
+MySQL [email protected]:d1> select * from t1;
++---+----+----+----+----+----+
+| k | v1 | v2 | v3 | v4 | v5 |
++---+----+----+----+----+----+
+| 0 | 0  | 0  | 0  | 0  | 0  |
+| 1 | 1  | 1  | 1  | 1  | 1  |
+| 2 | 2  | 2  | 2  | 2  | 2  |
+| 3 | 3  | 3  | 3  | 3  | 3  |
+| 4 | 4  | 4  | 4  | 4  | 4  |
+| 5 | 5  | 5  | 5  | 5  | 5  |
++---+----+----+----+----+----+
+```
+
+现在通过灵活列更新导入来更新其中的一些行的字段
+
+```shell
+$ cat test1.json
+```
+```json
+{"k": 0, "__DORIS_DELETE_SIGN__": 1}
+{"k": 1, "v1": 10}
+{"k": 2, "v2": 20, "v5": 25}
+{"k": 3, "v3": 30}
+{"k": 4, "v4": 20, "v1": 43, "v3": 99}
+{"k": 5, "v5": null}
+{"k": 6, "v1": 999, "v3": 777}
+{"k": 2, "v4": 222}
+{"k": 1, "v2": 111, "v3": 111}
+```
+```shell
+curl --location-trusted -u root: \
+-H "strict_mode:false" \
+-H "format:json" \
+-H "read_json_by_line:true" \
+-H "unique_key_update_mode:UPDATE_FLEXIBLE_COLUMNS" \
+-T test1.json \
+-XPUT http://<host>:<http_port>/api/d1/t1/_stream_load
+```
+
+更新后表中的数据如下：
+
+```sql
+MySQL [email protected]:d1> select * from t1;
++---+-----+------+-----+------+--------+
+| k | v1  | v2   | v3  | v4   | v5     |
++---+-----+------+-----+------+--------+
+| 1 | 10  | 111  | 111 | 1    | 1      |
+| 2 | 2   | 20   | 2   | 222  | 25     |
+| 3 | 3   | 3    | 30  | 3    | 3      |
+| 4 | 43  | 4    | 99  | 20   | 4      |
+| 5 | 5   | 5    | 5   | 5    | <null> |
+| 6 | 999 | 9876 | 777 | 1234 | <null> |
++---+-----+------+-----+------+--------+
+```
+
+### 限制与注意事项
+
+1. 和之前的部分列更新相同，灵活列更新要求导入的每一行数据需要包括所有的 Key 列，不满足这一要求的行数据将被过滤掉，同时计入 `filter rows` 的计数中，如果 `filtered rows` 的数量超过了本次导入 `max_filter_ratio` 所能容忍的上限，则整个导入将会失败。同时，被过滤的数据会在 error log 留下一条日志。
+
+2. 灵活列更新导入中每一个 json 对象中的键值对只有当它的 Key 和目标表中某一列的列名一致时才是有效的，不满足这一要求的键值对将被忽略。同时，Key 为 `__DORIS_VERSION_COL__`/`__DORIS_ROW_STORE_COL__`/`__DORIS_SKIP_BITMAP_COL__` 的键值对也将被忽略。
+
+3. 当目标表的表属性中设置了 `function_column.sequence_type` 这一属性时，灵活列更新的导入可以通过在 json 对象中包括 Key 为 `__DORIS_SEQUENCE_COL__` 的键值对来指定目标表中 `__DORIS_SEQUENCE_COL__` 列的值。对于不指定 `__DORIS_SEQUENCE_COL__` 列的值的行，如果这一行的 Key 在原表中存在，则这一行 `__DORIS_SEQUENCE_COL__` 列的值将被填充为旧行中对应的值，否则该列的值将被填充为 `null` 值
+
+例如，对于下表：
+```sql
+CREATE TABLE t2 (
+  `k` int(11) NULL, 
+  `v1` BIGINT NULL,
+  `v2` BIGINT NULL DEFAULT "9876",
+  `v3` BIGINT NOT NULL,
+  `v4` BIGINT NOT NULL DEFAULT "1234",
+  `v5` BIGINT NULL
+) UNIQUE KEY(`k`) DISTRIBUTED BY HASH(`k`) BUCKETS 1
+PROPERTIES(
+"replication_num" = "3",
+"enable_unique_key_merge_on_write" = "true",
+"enable_light_schema_change" = "true",
+"enable_unique_key_skip_bitmap_column" = "true",
+"function_column.sequence_type" = "int");
+```
+
+表中有如下原始数据：
+```sql
++---+----+----+----+----+----+----------------------+
+| k | v1 | v2 | v3 | v4 | v5 |__DORIS_SEQUENCE_COL__|
++---+----+----+----+----+----+----------------------+
+| 0 | 0  | 0  | 0  | 0  | 0  | 0                    |
+| 1 | 1  | 1  | 1  | 1  | 10 | 10                   |
+| 2 | 2  | 2  | 2  | 2  | 20 | 20                   |
+| 3 | 3  | 3  | 3  | 3  | 30 | 30                   |
+| 4 | 4  | 4  | 4  | 4  | 40 | 40                   |
+| 5 | 5  | 5  | 5  | 5  | 50 | 50                   |
++---+----+----+----+----+----+----------------------+
+```
+
+通过灵活列更新导入如下数据：
+```json
+{"k": 1, "v1": 111, "v5": 9, "__DORIS_SEQUENCE_COL__": 9}
+{"k": 2, "v2": 222, "v5": 25, "__DORIS_SEQUENCE_COL__": 25}
+{"k": 3, "v3": 333}
+{"k": 4, "v4": 444, "v5": 50, "v1": 411, "v3": 433, "v2": null, "__DORIS_SEQUENCE_COL__": 50}
+{"k": 5, "v5": null, "__DORIS_SEQUENCE_COL__": null}
+{"k": 6, "v1": 611, "v3": 633}
+{"k": 7, "v3": 733, "v5": 300, "__DORIS_SEQUENCE_COL__": 300}
+```
+
+最终表中的数据如下：
+```sql
++---+--------+--------+-----+------+--------+
+| k | v1     | v2     | v3  | v4   | v5     |
++---+--------+--------+-----+------+--------+
+| 0 | 0      | 0      | 0   | 0    | 0      |
+| 1 | 1      | 1      | 1   | 1    | 1      |
+| 5 | 5      | 5      | 5   | 5    | 5      |
+| 2 | 2      | 222    | 2   | 2    | 25     |
+| 3 | 3      | 3      | 333 | 3    | 3      |
+| 4 | 411    | <null> | 433 | 444  | 50     |
+| 6 | 611    | 9876   | 633 | 1234 | <null> |
+| 7 | <null> | 9876   | 733 | 1234 | 300    |
++---+--------+--------+-----+------+--------+
+```
+
+4. 当目标表的表属性中设置了 `function_column.sequence_col` 这一属性时，灵活列更新导入数据的 json 对象中 Key 为 `__DORIS_SEQUENCE_COL__` 的键值对将被忽略，导入中某一行 `__DORIS_SEQUENCE_COL__` 列的值将与这一行中表属性 `function_column.sequence_col` 所指定的列最终的值完全一致。
+
+例如，对于下表：
+```sql
+CREATE TABLE t3 (
+  `k` int(11) NULL, 
+  `v1` BIGINT NULL,
+  `v2` BIGINT NULL DEFAULT "9876",
+  `v3` BIGINT NOT NULL,
+  `v4` BIGINT NOT NULL DEFAULT "1234",
+  `v5` BIGINT NULL DEFAULT "31"
+) UNIQUE KEY(`k`) DISTRIBUTED BY HASH(`k`) BUCKETS 1
+PROPERTIES(
+"replication_num" = "3",
+"enable_unique_key_merge_on_write" = "true",
+"enable_light_schema_change" = "true",
+"enable_unique_key_skip_bitmap_column" = "true",
+"function_column.sequence_col" = "v5");
+```
+
+表中有如下原始数据：
+```sql
++---+----+----+----+----+----+----------------------+
+| k | v1 | v2 | v3 | v4 | v5 |__DORIS_SEQUENCE_COL__|
++---+----+----+----+----+----+----------------------+
+| 0 | 0  | 0  | 0  | 0  | 0  | 0                    |
+| 1 | 1  | 1  | 1  | 1  | 10 | 10                   |
+| 2 | 2  | 2  | 2  | 2  | 20 | 20                   |
+| 3 | 3  | 3  | 3  | 3  | 30 | 30                   |
+| 4 | 4  | 4  | 4  | 4  | 40 | 40                   |
+| 5 | 5  | 5  | 5  | 5  | 50 | 50                   |
++---+----+----+----+----+----+----------------------+
+```
+
+通过灵活列更新导入如下数据：
+```json
+{"k": 1, "v1": 111, "v5": 9}
+{"k": 2, "v2": 222, "v5": 25}
+{"k": 3, "v3": 333}
+{"k": 4, "v4": 444, "v5": 50, "v1": 411, "v3": 433, "v2": null}
+{"k": 5, "v5": null}
+{"k": 6, "v1": 611, "v3": 633}
+{"k": 7, "v3": 733, "v5": 300}
+```
+
+最终表中的数据如下：
+```sql
++---+--------+--------+-----+------+-----+
+| k | v1     | v2     | v3  | v4   | v5  |
++---+--------+--------+-----+------+-----+
+| 0 | 0      | 0      | 0   | 0    | 0   |
+| 1 | 1      | 1      | 1   | 1    | 10  |
+| 5 | 5      | 5      | 5   | 5    | 50  |
+| 2 | 2      | 222    | 2   | 2    | 25  |
+| 3 | 3      | 3      | 333 | 3    | 30  |
+| 4 | 411    | <null> | 433 | 444  | 50  |
+| 6 | 611    | 9876   | 633 | 1234 | 31  |
+| 7 | <null> | 9876   | 733 | 1234 | 300 |
++---+--------+--------+-----+------+-----+
+```
+
+5. 使用灵活列更新时不能指定或开启如下一些导入属参数：
+    - 不能指定 `merge_type` 参数
+    - 不能指定 `delete` 参数
+    - 不能开启 `fuzzy_parse` 参数
+    - 不能指定 `columns` 参数
+    - 不能指定 `jsonpaths` 参数
+    - 不能指定 `hidden_columns` 参数
+    - 不能指定 `function_column.sequence_col` 参数
+    - 不能指定 `sql` 参数
+    - 不能开启 `memtable_on_sink_node` 前移
+    - 不能指定 `group_commit` 参数
+    - 不能指定 `where` 参数
+
+6. 不支持在有 Variant 列的表上进行灵活列更新。
+
+7. 不支持在有同步物化视图的表上进行灵活列更新。

i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md

@@ -369,6 +369,7 @@ rollup 可以创建的同步物化视图功能有限。已不再推荐使用。
 | group_commit_data_bytes                       | 配置这个表的 Group Commit 攒批数据大小。单位为 bytes，默认值为 134217728，即 128MB。Group Commit 的下刷时机取决于 `group_commit_interval_ms`以及`group_commit_data_bytes` 哪个先到设置的值。 |
 | enable_mow_light_delete                       | 是否在 Unique 表 Mow 上开启 Delete 语句写 Delete predicate。若开启，会提升 Delete 语句的性能，但 Delete 后进行部分列更新可能会出现部分数据错误的情况。若关闭，会降低 Delete 语句的性能来保证正确性。此属性的默认值为 `false`。此属性只能在 Unique Merge-on-Write 表上开启。 |
 | 动态分区相关属性                              | 动态分区相关参考[数据划分 - 动态分区](../../../../table-design/data-partitioning/dynamic-partitioning) |
+| enable_unique_key_skip_bitmap_column | 是否在 Unique Merge-on-Write 表上开启[灵活列更新功能](../../../../data-operate/update/update-of-unique-model.md#灵活部分列更新)。此属性只能在 Unique Merge-on-Write 表上开启。(自 3.1.0 版本起支持) |
 
 ## 权限控制