Skip to content

Commit

Permalink
[Doc] Change dict_mapping parameter (#53742)
Browse files Browse the repository at this point in the history
Signed-off-by: 絵空事スピリット <[email protected]>
(cherry picked from commit d6f2f45)
  • Loading branch information
EsoragotoSpirit authored and mergify[bot] committed Dec 13, 2024
1 parent 22b3a73 commit 913fd1c
Show file tree
Hide file tree
Showing 2 changed files with 16 additions and 12 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Since v3.2.5, StarRocks supports this function. Also, note that currently StarRo
## Syntax

```SQL
dict_mapping("[<db_name>.]<dict_table>", key_column_expr_list [, <value_column> ] [, <strict_mode>] )
dict_mapping("[<db_name>.]<dict_table>", key_column_expr_list [, <value_column> ] [, <null_if_not_exist>] )

key_column_expr_list ::= key_column_expr [, key_column_expr ... ]

Expand All @@ -32,13 +32,15 @@ key_column_expr ::= <column_name> | <expr>

- Optional parameters:
- `<value_column>`: The name of the value column, which is also the mapping column. If the value column is not specified, the default value column is the AUTO_INCREMENT column of the dictionary table. The value column can also be defined as any column in the dictionary table excluding auto-incremented columns and primary keys. The column's data type has no restrictions.
- `<strict_mode>`: Whether to enable strict mode, that is, whether to return an error when the value mapped to the specified key is not found. If the parameter is set to `TRUE`, an error is returned. If the parameter is set to `FALSE` (default), `NULL` is returned.
- `<null_if_not_exist>` (Optional): Whether to return if the key does not exist in the dictionary table. Valid values:
- `true`: Null is returned if the key does not exist.
- `false` (Default): An exception is thrown if the key does not exist.

## Return Value

The data type of the returned values remains consistent with the data type of the value column. If the value column is the auto-incremented column of the dictionary table, the data type of the returned values is BIGINT.

However, when the value mapped to the specified key is not found, if the `strict_mode` parameter is set to `FALSE` (default), `NULL` is returned. If the parameter is set to `TRUE`, an error `ERROR 1064 (HY000): In strict mode, query failed if the record does not exist in the dict table` is returned.
However, when the value mapped to the specified key is not found, if the `<null_if_not_exist>` parameter is set to `true`, `NULL` is returned. If the parameter is set to `false`(default), an error `query failed if record not exist in dict table` is returned.

## Example

Expand Down Expand Up @@ -161,13 +163,13 @@ However, when the value mapped to the specified key is not found, if the `strict
1 row in set (0.02 sec)
```
**Example 4: Enable strict mode**
**Example 4: Enable null_if_not_exist mode**
When strict mode is enabled and the value mapped to the key that doesn't exist in the dictionary table is queried , an error, instead of `NULL`, is returned . It makes sure that a data row's key is first loaded into the dictionary table and its mapped value (dictionary ID) is generated before that data row is loaded into the target table.
When `<null_if_not_exist>` mode is disabled and the value mapped to the key that doesn't exist in the dictionary table is queried , an error, instead of `NULL`, is returned. It makes sure that a data row's key is first loaded into the dictionary table and its mapped value (dictionary ID) is generated before that data row is loaded into the target table.
```SQL
MySQL [test]> SELECT dict_mapping('dict', 'b1', true);
ERROR 1064 (HY000): In strict mode, query failed if record not exist in dict table.
ERROR 1064 (HY000): Query failed if record not exist in dict table.
```
**Example 5: If the dictionary table uses composite primary keys, all primary keys must be specified when querying.**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ displayed_sidebar: docs
## 语法

```SQL
dict_mapping([<db_name>.]<dict_table>, key_column_expr_list [, <value_column> ] [, <strict_mode>] )
dict_mapping("[<db_name>.]<dict_table>", key_column_expr_list [, <value_column> ] [, <null_if_not_exist>] )

key_column_expr_list ::= key_column_expr [, key_column_expr ... ]

Expand All @@ -31,13 +31,15 @@ key_column_expr ::= <column_name> | <expr>
该表达式列表必须包括字典表的所有主键列,即表达式的个数必须和字典表中所有主键列的个数相同。所以如果字典表使用联合主键,则该表达式列表中的表达式和字典表表结构中定义的主键列必须按位置一一对应,多个表达式之间用英文逗号分隔(`,`)。并且如果 `key_column_expr`是一个具体的 key 或 key 表达式,则其类型必须和对应的字典表中的列的类型相同。
- 可选参数:
- `<value_column>`:value 列名,也就是映射列名。如果不指定,则默认为字典表的自增列。value 列也可以定义为字典表中除自增列和主键以外的列,并且对列的数据类型无限制。
- `<strict_mode>`:是否启用严格模式,即在未找到与该 key 呈映射关系的 value 时,是否返回报错。如果为 `TRUE`,则返回报错。如果为 `FALSE`(默认),则返回 `NULL`
- `<null_if_not_exist>`(选填):当字典表中不存在该 key 时,是否返回 NULL。
- `true`:Key 不存在时 返回 NULL。
- `false` (默认):Key 不存在时返回错误。

## 返回值说明

返回值的数据类型与 value 列的数据类型保持一致。如果 value 列为字典表的自增列,则返回值的数据类型为 BIGINT。

然而当未找到与该 key 呈映射关系的 value 时,如果为 `strict_mode` 参数为默认的 `FALSE`,则返回 `NULL`如果为 `TRUE`,则返回报错 `ERROR 1064 (HY000): In strict mode, query failed if record not exist in dict table.`
然而当未找到与该 key 呈映射关系的 value 时,如果为 `<null_if_not_exist>` 参数为 `true`,则返回 `NULL`如果为默认的 `false`,则返回报错 `query failed if record not exist in dict table`

## 示例

Expand Down Expand Up @@ -161,13 +163,13 @@ key_column_expr ::= <column_name> | <expr>
1 row in set (0.02 sec)
```

**示例四:启用严格模式**
**示例四:启用 null_if_not_exist 模式**

启用严格模式,并且使用字典表中不存在的 key,查询与其呈映射关系的 value,此时直接返回报错而不是 `NULL`。从而可以确保导入至数据表之前,相关 key 已经先导入至字典表并生成与其映射的value
禁用 `<null_if_not_exist>` 模式,并且使用字典表中不存在的 key,查询与其呈映射关系的 value,此时直接返回报错而不是 `NULL`。从而可以确保导入至数据表之前,相关 key 已经先导入至字典表并生成与其映射的 value

```SQL
MySQL [test]> SELECT dict_mapping('dict', 'b1', true);
ERROR 1064 (HY000): In strict mode, query failed if record not exist in dict table.
ERROR 1064 (HY000): Query failed if record not exist in dict table.
```

**示例五:如果字典表使用联合主键,则查询时候必须指定所有主键**
Expand Down

0 comments on commit 913fd1c

Please sign in to comment.