Skip to content

Commit

Permalink
[Docs](merge-on-write) Add more docs for partial update using native …
Browse files Browse the repository at this point in the history
…insert statement (apache#25356)
  • Loading branch information
bobhan1 authored Oct 13, 2023
1 parent 6298f90 commit 96f31ae
Show file tree
Hide file tree
Showing 6 changed files with 9 additions and 2 deletions.
2 changes: 1 addition & 1 deletion docs/en/docs/advanced/variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -694,7 +694,7 @@ Note that the comment must start with /*+ and can only follow the SELECT.
* `enable_unique_key_partial_update`
<version since="2.0.2">
Whether to enable partial columns update semantics for native insert into statement, default is false.
Whether to enable partial columns update semantics for native insert into statement, default is false. Please note that the default value of the session variable `enable_insert_strict`, which controls whether the insert statement operates in strict mode, is true. In other words, the insert statement is in strict mode by default, and in this mode, updating non-existing keys in partial column updates is not allowed. Therefore, when using the insert statement for partial columns update and wishing to insert non-existing keys, it is necessary to set both `enable_unique_key_partial_update` and `enable_insert_strict` to true.
</version>
***
Expand Down
2 changes: 2 additions & 0 deletions docs/en/docs/data-operate/update-delete/partial-update.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,8 @@ In all data models, by default, when you use `INSERT INTO` with a given set of c
set enable_unique_key_partial_update=true
```

Please note that the default value of the session variable `enable_insert_strict`, which controls whether the insert statement operates in strict mode, is true. In other words, the insert statement is in strict mode by default, and in this mode, updating non-existing keys in partial column updates is not allowed. Therefore, when using the insert statement for partial columns update and wishing to insert non-existing keys, it is necessary to set both `enable_unique_key_partial_update` and `enable_insert_strict` to true.

#### Example

Suppose there is an order table `order_tbl` in Doris, where the order ID is the Key column, and the order status and order amount are Value columns. The data status is as follows:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@ INSERT INTO table_name
For a Unique table with merge-on-write enabled, you can also perform partial columns updates using the insert statement. To perform partial column updates with the insert statement, you need to set the session variable enable_unique_key_partial_update to true (the default value for this variable is false, meaning partial columns updates with the insert statement are not allowed by default). When performing partial columns updates, the columns being inserted must contain at least all the Key columns and specify the columns you want to update. If the Key column values for the inserted row already exist in the original table, the data in the row with the same key column values will be updated. If the Key column values for the inserted row do not exist in the original table, a new row will be inserted into the table. In this case, columns not specified in the insert statement must either have default values or be nullable. These missing columns will first attempt to be populated with default values, and if a column has no default value, it will be filled with null. If a column cannot be null, the insert operation will fail.
Please note that the default value of the session variable `enable_insert_strict`, which controls whether the insert statement operates in strict mode, is true. In other words, the insert statement is in strict mode by default, and in this mode, updating non-existing keys in partial column updates is not allowed. Therefore, when using the insert statement for partial columns update and wishing to insert non-existing keys, it is necessary to set both `enable_unique_key_partial_update` and `enable_insert_strict` to true.
Notice:
Expand Down
2 changes: 1 addition & 1 deletion docs/zh-CN/docs/advanced/variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -682,7 +682,7 @@ try (Connection conn = DriverManager.getConnection("jdbc:mysql://127.0.0.1:9030/
* `enable_unique_key_partial_update`
<version since="2.0.2">
是否在对insert into语句启用部分列更新的语义,默认为 false
是否在对insert into语句启用部分列更新的语义,默认为 false。需要注意的是,控制insert语句是否开启严格模式的会话变量`enable_insert_strict`的默认值为true,即insert语句默认开启严格模式,而在严格模式下进行部分列更新不允许更新不存在的key。所以,在使用insert语句进行部分列更新的时候如果希望能插入不存在的key,需要在`enable_unique_key_partial_update`设置为true的基础上同时将`enable_insert_strict`也设置为true。
</version>
***
Expand Down
2 changes: 2 additions & 0 deletions docs/zh-CN/docs/data-operate/update-delete/partial-update.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,8 @@ partial_columns:true
set enable_unique_key_partial_update=true
```

需要注意的是,控制insert语句是否开启严格模式的会话变量`enable_insert_strict`的默认值为true,即insert语句默认开启严格模式,而在严格模式下进行部分列更新不允许更新不存在的key。所以,在使用insert语句进行部分列更新的时候如果希望能插入不存在的key,需要在`enable_unique_key_partial_update`设置为true的基础上同时将`enable_insert_strict`也设置为true。

#### 示例

假设 Doris 中存在一张订单表order_tbl,其中 订单id 是 Key 列,订单状态,订单金额是 Value 列。数据状态如下:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,8 @@ INSERT INTO table_name
对于开启了merge-on-write的Unique表,还可以使用insert语句进行部分列更新的操作。要使用insert语句进行部分列更新,需要将会话变量enable_unique_key_partial_update的值设置为true(该变量默认值为false,即默认无法通过insert语句进行部分列更新)。进行部分列更新时,插入的列必须至少包含所有的Key列,同时指定需要更新的列。如果插入行Key列的值在原表中存在,则将更新具有相同key列值那一行的数据。如果插入行Key列的值在原表中不存在,则将向表中插入一条新的数据,此时insert语句中没有指定的列必须有默认值或可以为null,这些缺失列会首先尝试用默认值填充,如果该列没有默认值,则尝试使用null值填充,如果该列不能为null,则本次插入失败。

需要注意的是,控制insert语句是否开启严格模式的会话变量`enable_insert_strict`的默认值为true,即insert语句默认开启严格模式,而在严格模式下进行部分列更新不允许更新不存在的key。所以,在使用insert语句进行部分列更新的时候如果希望能插入不存在的key,需要在`enable_unique_key_partial_update`设置为true的基础上同时将`enable_insert_strict`也设置为true。

注意:

当前执行 `INSERT` 语句时,对于有不符合目标表格式的数据,默认的行为是过滤,比如字符串超长等。但是对于有要求数据不能够被过滤的业务场景,可以通过设置会话变量 `enable_insert_strict``true` 来确保当有数据被过滤掉的时候,`INSERT` 不会被执行成功。
Expand Down

0 comments on commit 96f31ae

Please sign in to comment.