diff --git a/docs/en/sql-reference/sql-functions/dict-functions/dict_mapping.md b/docs/en/sql-reference/sql-functions/dict-functions/dict_mapping.md index 58e409e1..31ca0492 100644 --- a/docs/en/sql-reference/sql-functions/dict-functions/dict_mapping.md +++ b/docs/en/sql-reference/sql-functions/dict-functions/dict_mapping.md @@ -6,7 +6,7 @@ displayed_sidebar: docs Returns the value mapped to the specified key in a dictionary table. -This function is mainly used to simplify the application of a global dictionary table. During data loading into a target table, StarRocks automatically obtains the value mapped to the specified key from the dictionary table by using the input parameters in this function, and then loads the value into the target table. +This function simplifies the application of a global dictionary table. During data loading into a target table, StarRocks automatically obtains the value mapped to the specified key from the dictionary table by using the input parameters in this function, and then loads the value into the target table. Since v3.2.5, StarRocks supports this function. Also, note that currently StarRocks's shared-data mode does not support this function. diff --git a/docs/ja/sql-reference/sql-functions/dict-functions/dict_mapping.md b/docs/ja/sql-reference/sql-functions/dict-functions/dict_mapping.md new file mode 100644 index 00000000..a407d77f --- /dev/null +++ b/docs/ja/sql-reference/sql-functions/dict-functions/dict_mapping.md @@ -0,0 +1,211 @@ +--- +displayed_sidebar: docs +--- + +# dict_mapping + +辞書テーブルで指定されたキーにマッピングされている値を返します。 + +この関数は、グローバル辞書テーブルの適用を簡素化します。ターゲットテーブルへのデータロード中に、StarRocks はこの関数の入力パラメータを使用して、辞書テーブルから指定されたキーにマッピングされた値を自動的に取得し、その値をターゲットテーブルにロードします。 + +v3.2.5 以降、StarRocks はこの関数をサポートしています。また、現在の StarRocks の共有データモードでは、この関数はサポートされていないことに注意してください。 +## 構文 + +```SQL +dict_mapping("[.]", key_column_expr_list [, ] [, ] ) + +key_column_expr_list ::= key_column_expr [, key_column_expr ... ] + +key_column_expr ::= | +``` +## パラメータ + +- 必須パラメータ: + - `[.]`: 辞書テーブルの名前。主キーテーブルである必要があります。サポートされているデータ型は VARCHAR です。 + - `key_column_expr_list`: 辞書テーブル内のキーカラムの式リスト。1つまたは複数の `key_column_exprs` が含まれます。 `key_column_expr` は、辞書テーブル内のキーカラムの名前、または特定のキーもしくはキー式にすることができます。 + + この式リストには、辞書テーブルのすべての主キーカラムを含める必要があります。つまり、式の総数は、辞書テーブルの主キーカラムの総数と一致する必要があります。したがって、辞書テーブルが複合主キーを使用する場合、このリストの式は、テーブルスキーマで定義された主キーカラムに順番に対応する必要があります。このリストの複数の式は、カンマ (`,`) で区切られます。また、`key_column_expr` が特定のキーまたはキー式である場合、その型は辞書テーブル内の対応する主キーカラムの型と一致する必要があります。 + +- オプションのパラメータ: + - ``: 値カラムの名前。これはマッピングカラムでもあります。値カラムが指定されていない場合、デフォルトの値カラムは辞書テーブルの AUTO_INCREMENT カラムです。値カラムは、自動インクリメントカラムと主キーを除く、辞書テーブル内の任意のカラムとして定義することもできます。カラムのデータ型に制限はありません。 + - `` (オプション): キーが辞書テーブルに存在しない場合に NULL を返すかどうか。有効な値: + - `true`: キーが存在しない場合、NULL が返されます。 + - `false` (デフォルト): キーが存在しない場合、例外がスローされます。 +## 戻り値 + +戻り値のデータ型は、value カラムのデータ型と一致します。value カラムが辞書テーブルの自動増分カラムである場合、戻り値のデータ型は BIGINT になります。 + +ただし、指定されたキーにマッピングされた value が見つからない場合、`` パラメータが `true` に設定されていると、`NULL` が返されます。パラメータが `false` (デフォルト) に設定されている場合、`query failed if record not exist in dict table` というエラーが返されます。 +## 例 + +**例1：辞書テーブルからキーにマッピングされた値を直接クエリする。** + +1. 辞書テーブルを作成し、シミュレートされたデータをロードします。 + + ```SQL + MySQL [test]> CREATE TABLE dict ( + order_uuid STRING, + order_id_int BIGINT AUTO_INCREMENT + ) + PRIMARY KEY (order_uuid) + DISTRIBUTED BY HASH (order_uuid); + Query OK, 0 rows affected (0.02 sec) + + MySQL [test]> INSERT INTO dict (order_uuid) VALUES ('a1'), ('a2'), ('a3'); + Query OK, 3 rows affected (0.12 sec) + {'label':'insert_9e60b0e4-89fa-11ee-a41f-b22a2c00f66b', 'status':'VISIBLE', 'txnId':'15029'} + + MySQL [test]> SELECT * FROM dict; + +------------+--------------+ + | order_uuid | order_id_int | + +------------+--------------+ + | a1 | 1 | + | a3 | 3 | + | a2 | 2 | + +------------+--------------+ + 3 rows in set (0.01 sec) + ``` + + > **注意** + > + > 現在、`INSERT INTO` ステートメントは部分的な更新をサポートしていません。したがって、`dict` のキーカラムに挿入される値が重複していないことを確認してください。そうしないと、同じキーカラムの値を辞書テーブルに複数回挿入すると、値カラム内のマッピングされた値が変更されます。 + +2. 辞書テーブル内のキー `a1` にマッピングされた値をクエリします。 + + ```SQL + MySQL [test]> SELECT dict_mapping('dict', 'a1'); + +----------------------------+ + | dict_mapping('dict', 'a1') | + +----------------------------+ + | 1 | + +----------------------------+ + 1 row in set (0.01 sec) + ``` + +**例2：テーブル内のマッピングカラムは、`dict_mapping` 関数を使用して生成列として構成されています。したがって、StarRocks は、このテーブルにデータをロードするときに、キーにマッピングされた値を自動的に取得できます。** + +1. データテーブルを作成し、`dict_mapping('dict', order_uuid)` を使用してマッピングカラムを生成列として構成します。 + + ```SQL + CREATE TABLE dest_table1 ( + id BIGINT, + -- このカラムは、例1の dict テーブルの order_uuid カラムに対応する、STRING 型の注文番号を記録します。 + order_uuid STRING, + batch int comment '異なるバッチロードを区別するために使用', + -- このカラムは、order_uuid カラムにマッピングされた BIGINT 型の注文番号を記録します。 + -- このカラムは dict_mapping で構成された生成列であるため、このカラムの値は、データロード中に例1の dict テーブルから自動的に取得されます。 + -- その後、このカラムは、重複排除および JOIN クエリに直接使用できます。 + order_id_int BIGINT AS dict_mapping('dict', order_uuid) + ) + DUPLICATE KEY (id, order_uuid) + DISTRIBUTED BY HASH(id); + ``` + +2. `order_id_int` カラムが `dict_mapping('dict', 'order_uuid')` として構成されているこのテーブルにシミュレートされたデータをロードすると、StarRocks は `dict` テーブル内のキーと値の間のマッピング関係に基づいて、`order_id_int` カラムに値を自動的にロードします。 + + ```SQL + MySQL [test]> INSERT INTO dest_table1(id, order_uuid, batch) VALUES (1, 'a1', 1), (2, 'a1', 1), (3, 'a3', 1), (4, 'a3', 1); + Query OK, 4 rows affected (0.05 sec) + {'label':'insert_e191b9e4-8a98-11ee-b29c-00163e03897d', 'status':'VISIBLE', 'txnId':'72'} + + MySQL [test]> SELECT * FROM dest_table1; + +------+------------+-------+--------------+ + | id | order_uuid | batch | order_id_int | + +------+------------+-------+--------------+ + | 1 | a1 | 1 | 1 | + | 4 | a3 | 1 | 3 | + | 2 | a1 | 1 | 1 | + | 3 | a3 | 1 | 3 | + +------+------------+-------+--------------+ + 4 rows in set (0.02 sec) + ``` + + この例での `dict_mapping` の使用は、[重複排除の計算と JOIN クエリ](../../../using_starrocks/query_acceleration_with_auto_increment.md) を高速化できます。正確な重複排除を高速化するためにグローバル辞書を構築するための以前のソリューションと比較して、`dict_mapping` を使用したソリューションは、より柔軟でユーザーフレンドリーです。マッピング値は、「キーと値の間のマッピング関係をテーブルにロードする」段階で辞書テーブルから直接取得されるためです。マッピング値を取得するために辞書テーブルをジョインするステートメントを作成する必要はありません。さらに、このソリューションはさまざまなデータロード方法をサポートしています。 + +**例3：テーブル内のマッピングカラムが生成列として構成されていない場合は、テーブルにデータをロードするときに、マッピングカラムの `dict_mapping` 関数を明示的に構成し、キーにマッピングされた値を取得する必要があります。** + +> **注意** +> +> 例3と例2の違いは、データテーブルにインポートするときに、インポートコマンドを変更して、マッピングカラムの `dict_mapping` 式を明示的に構成する必要があることです。 + +1. テーブルを作成します。 + + ```SQL + CREATE TABLE dest_table2 ( + id BIGINT, + order_uuid STRING, + order_id_int BIGINT NULL, + batch int comment '異なるバッチロードを区別するために使用' + ) + DUPLICATE KEY (id, order_uuid, order_id_int) + DISTRIBUTED BY HASH(id); + ``` + +2. シミュレートされたデータがこのテーブルにロードされると、`dict_mapping` を構成することにより、辞書テーブルからマッピングされた値を取得します。 + + ```SQL + MySQL [test]> INSERT INTO dest_table2 VALUES (1, 'a1', dict_mapping('dict', 'a1'), 1); + Query OK, 1 row affected (0.35 sec) + {'label':'insert_19872ab6-8a96-11ee-b29c-00163e03897d', 'status':'VISIBLE', 'txnId':'42'} + + MySQL [test]> SELECT * FROM dest_table2; + +------+------------+--------------+-------+ + | id | order_uuid | order_id_int | batch | + +------+------------+--------------+-------+ + | 1 | a1 | 1 | 1 | + +------+------------+--------------+-------+ + 1 row in set (0.02 sec) + ``` + +**例4：null_if_not_exist モードを有効にする** + +`` モードが無効になっており、辞書テーブルに存在しないキーにマッピングされた値がクエリされると、`NULL` ではなくエラーが返されます。これにより、データ行のキーが最初に辞書テーブルにロードされ、そのマッピングされた値（辞書 ID）が、そのデータ行がターゲットテーブルにロードされる前に生成されることが保証されます。 + +```SQL +MySQL [test]> SELECT dict_mapping('dict', 'b1', true); +ERROR 1064 (HY000): Query failed if record not exist in dict table. +``` + +**例5：辞書テーブルが複合主キーを使用する場合、クエリ時にすべての主キーを指定する必要があります。** + +1. 複合主キーを持つ辞書テーブルを作成し、シミュレートされたデータをロードします。 + + ```SQL + MySQL [test]> CREATE TABLE dict2 ( + order_uuid STRING, + order_date DATE, + order_id_int BIGINT AUTO_INCREMENT + ) + PRIMARY KEY (order_uuid,order_date) -- 複合主キー + DISTRIBUTED BY HASH (order_uuid,order_date) + ; + Query OK, 0 rows affected (0.02 sec) + + MySQL [test]> INSERT INTO dict2 VALUES ('a1','2023-11-22',default), ('a2','2023-11-22',default), ('a3','2023-11-22',default); + Query OK, 3 rows affected (0.12 sec) + {'label':'insert_9e60b0e4-89fa-11ee-a41f-b22a2c00f66b', 'status':'VISIBLE', 'txnId':'15029'} + + + MySQL [test]> select * from dict2; + +------------+------------+--------------+ + | order_uuid | order_date | order_id_int | + +------------+------------+--------------+ + | a1 | 2023-11-22 | 1 | + | a3 | 2023-11-22 | 3 | + | a2 | 2023-11-22 | 2 | + +------------+------------+--------------+ + 3 rows in set (0.01 sec) + ``` + +2. 辞書テーブル内のキーにマッピングされた値をクエリします。辞書テーブルには複合主キーがあるため、`dict_mapping` ですべての主キーを指定する必要があります。 + + ```SQL + SELECT dict_mapping('dict2', 'a1', cast('2023-11-22' as DATE)); + ``` + + 主キーが1つしか指定されていない場合、エラーが発生することに注意してください。 + + ```SQL + MySQL [test]> SELECT dict_mapping('dict2', 'a1'); + ERROR 1064 (HY000): Getting analyzing error. Detail message: dict_mapping function param size should be 3 - 5. + ``` \ No newline at end of file diff --git a/docs/zh/sql-reference/sql-functions/dict-functions/dict_mapping.md b/docs/zh/sql-reference/sql-functions/dict-functions/dict_mapping.md index 105f7c21..58c6d833 100644 --- a/docs/zh/sql-reference/sql-functions/dict-functions/dict_mapping.md +++ b/docs/zh/sql-reference/sql-functions/dict-functions/dict_mapping.md @@ -6,10 +6,9 @@ displayed_sidebar: docs 返回字典表中与指定键映射的值。 -此函数主要用于简化全局字典表的应用。在将数据加载到目标表期间，StarRocks 会通过使用此函数中的输入参数，自动从字典表中获取与指定键映射的值，然后将该值加载到目标表中。 - -自 v3.2.5 起，StarRocks 支持此功能。另请注意，目前 StarRocks 的存算分离模式不支持此功能。 +此函数简化了全局字典表的应用。在将数据导入到目标表期间，StarRocks 会通过使用此函数中的输入参数，自动从字典表中获取与指定键映射的值，然后将该值加载到目标表中。 +自 v3.2.5 起，StarRocks 支持此函数。另请注意，目前 StarRocks 的存算分离模式不支持此函数。 ## 语法 ```SQL @@ -19,30 +18,27 @@ key_column_expr_list ::= key_column_expr [, key_column_expr ... ] key_column_expr ::= | ``` - ## 参数 -- 必需参数： - - `[.]`：字典表的名称，需要是 Primary Key table。支持的数据类型为 VARCHAR。 - - `key_column_expr_list`：字典表中键列的表达式列表，包括一个或多个 `key_column_exprs`。`key_column_expr` 可以是字典表中键列的名称，也可以是特定的键或键表达式。 +- 必选参数： + - `[.]`：字典表的名称，必须是主键表。支持的数据类型为 VARCHAR。 + - `key_column_expr_list`：字典表中键列的表达式列表，包括一个或多个 `key_column_expr`。`key_column_expr` 可以是字典表中键列的名称，也可以是特定的键或键表达式。 - 此表达式列表需要包括字典表的所有 Primary Key 列，这意味着表达式的总数需要与字典表中 Primary Key 列的总数匹配。因此，当字典表使用组合主键时，此列表中的表达式需要按顺序与表结构中定义的 Primary Key 列相对应。此列表中的多个表达式用逗号 (`,`) 分隔。如果 `key_column_expr` 是特定的键或键表达式，则其类型必须与字典表中相应 Primary Key 列的类型匹配。 + 此表达式列表需要包含字典表的所有主键列，这意味着表达式的总数需要与字典表中的主键列总数相匹配。因此，当字典表使用组合主键时，此列表中的表达式需要按顺序与表结构中定义的主键列相对应。此列表中的多个表达式用逗号 (`,`) 分隔。并且如果 `key_column_expr` 是特定的键或键表达式，则其类型必须与字典表中相应主键列的类型相匹配。 - 可选参数： - - ``：值列的名称，也就是映射列。如果未指定值列，则默认值列是字典表的 AUTO_INCREMENT 列。值列也可以定义为字典表中的任何列，不包括自增列和主键。该列的数据类型没有限制。 - - ``（可选）：如果键在字典表中不存在，是否返回 Null。有效值： - - `true`：如果键不存在，则返回 Null。 + - ``：值列的名称，也就是映射列。如果未指定值列，则默认值列是字典表的自增列。值列也可以定义为字典表中的任何列，但自增列和主键除外。该列的数据类型没有限制。 + - ``（可选）：如果字典表中不存在键，是否返回 NULL。有效值： + - `true`：如果键不存在，则返回 NULL。 - `false`（默认）：如果键不存在，则抛出异常。 - ## 返回值 -返回的数据类型与值列的数据类型保持一致。如果值列是字典表的自增列，则返回的数据类型为 BIGINT。 - -但是，当未找到与指定键映射的值时，如果 `` 参数设置为 `true`，则返回 `NULL`。如果参数设置为 `false`（默认），则返回错误 `query failed if record not exist in dict table`。 +返回值的数据类型与值列的数据类型保持一致。如果值列是字典表的自增列，则返回的数据类型为 BIGINT。 +但是，当找不到指定 key 映射的值时，如果将 `` 参数设置为 `true`，则返回 `NULL`。如果该参数设置为 `false`（默认），则返回错误 `query failed if record not exist in dict table`。 ## 示例 -**示例 1：直接查询字典表中与键映射的值。** +**示例 1：直接从字典表中查询 key 映射的值。** 1. 创建一个字典表并加载模拟数据。 @@ -72,9 +68,9 @@ key_column_expr ::= | > **注意** > - > 目前，`INSERT INTO` 语句不支持部分更新。因此，请确保插入到 `dict` 的键列中的值不重复。否则，在字典表中多次插入相同的键列值会导致其在值列中映射的值发生更改。 + > 目前 `INSERT INTO` 语句不支持部分更新。因此，请确保插入到 `dict` 的 key 列中的值不重复。否则，在字典表中多次插入相同的 key 列值会导致其在 value 列中的映射值发生变化。 -2. 查询字典表中与键 `a1` 映射的值。 +2. 查询字典表中 key `a1` 映射的值。 ```SQL MySQL [test]> SELECT dict_mapping('dict', 'a1'); @@ -86,7 +82,7 @@ key_column_expr ::= | 1 row in set (0.01 sec) ``` -**示例 2：表中的映射列配置为使用 `dict_mapping` 函数生成的列。因此，在将数据加载到此表时，StarRocks 可以自动获取与键映射的值。** +**示例 2：表中的映射列配置为使用 `dict_mapping` 函数的生成列。因此，在将数据加载到此表中时，StarRocks 可以自动获取 key 映射的值。** 1. 创建一个数据表，并通过使用 `dict_mapping('dict', order_uuid)` 将映射列配置为生成列。 @@ -95,9 +91,9 @@ key_column_expr ::= | id BIGINT, -- 此列记录 STRING 类型的订单号，对应于示例 1 中 dict 表中的 order_uuid 列。 order_uuid STRING, - batch int comment 'used to distinguish different batch loading', + batch int comment '用于区分不同的批量加载', -- 此列记录与 order_uuid 列映射的 BIGINT 类型的订单号。 - -- 因为此列是使用 dict_mapping 配置的生成列，所以此列中的值在数据加载期间会自动从示例 1 中的 dict 表中获取。 + -- 因为此列是使用 dict_mapping 配置的生成列，所以此列中的值在数据加载期间自动从示例 1 中的 dict 表中获取。 -- 随后，此列可以直接用于去重和 JOIN 查询。 order_id_int BIGINT AS dict_mapping('dict', order_uuid) ) @@ -105,7 +101,7 @@ key_column_expr ::= | DISTRIBUTED BY HASH(id); ``` -2. 当将模拟数据加载到此表中时，其中 `order_id_int` 列配置为 `dict_mapping('dict', 'order_uuid')`，StarRocks 会根据 `dict` 表中键和值之间的映射关系自动将值加载到 `order_id_int` 列中。 +2. 当将模拟数据加载到此表中（其中 `order_id_int` 列配置为 `dict_mapping('dict', 'order_uuid')`）时，StarRocks 会根据 `dict` 表中 key 和值之间的映射关系自动将值加载到 `order_id_int` 列中。 ```SQL MySQL [test]> INSERT INTO dest_table1(id, order_uuid, batch) VALUES (1, 'a1', 1), (2, 'a1', 1), (3, 'a3', 1), (4, 'a3', 1); @@ -124,22 +120,22 @@ key_column_expr ::= | 4 rows in set (0.02 sec) ``` - 在此示例中使用 `dict_mapping` 可以加速 [去重计算和 JOIN 查询](../../../using_starrocks/query_acceleration_with_auto_increment.md)。与之前构建全局字典以加速精确去重的解决方案相比，使用 `dict_mapping` 的解决方案更加灵活和用户友好。因为映射值是在“将键和值之间的映射关系加载到表”的阶段直接从字典表中获取的。您无需编写语句来连接字典表以获取映射值。此外，此解决方案支持各种数据导入方法。 + 本示例中 `dict_mapping` 的使用可以加速 [去重计算和 JOIN 查询](../../../using_starrocks/query_acceleration_with_auto_increment.md)。与之前构建全局字典来加速精准去重的解决方案相比，使用 `dict_mapping` 的解决方案更加灵活和用户友好。因为映射值是在“将 key 和值之间的映射关系加载到表”的阶段直接从字典表中获取的。您无需编写语句来连接字典表以获取映射值。此外，此解决方案支持各种数据导入方法。 -**示例 3：如果表中的映射列未配置为生成列，则在将数据加载到表时，您需要为映射列显式配置 `dict_mapping` 函数，以获取与键映射的值。** +**示例 3：如果表中的映射列未配置为生成列，则在将数据加载到表中时，您需要为映射列显式配置 `dict_mapping` 函数，以获取 key 映射的值。** > **注意** > -> 示例 3 和示例 2 之间的区别在于，在导入到数据表时，您需要修改导入命令，以便为映射列显式配置 `dict_mapping` 表达式。 +> 示例 3 和示例 2 之间的区别在于，导入到数据表时，您需要修改导入命令，以便为映射列显式配置 `dict_mapping` 表达式。 -1. 创建一个表。 +1. 创建表。 ```SQL CREATE TABLE dest_table2 ( id BIGINT, order_uuid STRING, order_id_int BIGINT NULL, - batch int comment 'used to distinguish different batch loading' + batch int comment '用于区分不同的批量加载' ) DUPLICATE KEY (id, order_uuid, order_id_int) DISTRIBUTED BY HASH(id); @@ -163,16 +159,16 @@ key_column_expr ::= | **示例 4：启用 null_if_not_exist 模式** -当 `` 模式被禁用，并且查询了字典表中不存在的键所映射的值时，将返回一个错误，而不是 `NULL`。它确保数据行的键首先被加载到字典表中，并且在将该数据行加载到目标表之前，会生成其映射的值（字典 ID）。 +当禁用 `` 模式并且查询在字典表中不存在的 key 映射的值时，将返回错误而不是 `NULL`。它确保数据行的 key 首先加载到字典表中，并且在将该数据行加载到目标表之前生成其映射的值（字典 ID）。 ```SQL MySQL [test]> SELECT dict_mapping('dict', 'b1', true); ERROR 1064 (HY000): Query failed if record not exist in dict table. ``` -**示例 5：如果字典表使用组合主键，则在查询时必须指定所有主键。** +**示例 5：如果字典表使用复合主键，则查询时必须指定所有主键。** -1. 创建一个具有组合主键的字典表，并将模拟数据加载到其中。 +1. 创建一个具有复合主键的字典表，并将模拟数据加载到其中。 ```SQL MySQL [test]> CREATE TABLE dict2 ( @@ -180,7 +176,7 @@ ERROR 1064 (HY000): Query failed if record not exist in dict table. order_date DATE, order_id_int BIGINT AUTO_INCREMENT ) - PRIMARY KEY (order_uuid,order_date) -- 组合主键 + PRIMARY KEY (order_uuid,order_date) -- 复合主键 DISTRIBUTED BY HASH (order_uuid,order_date) ; Query OK, 0 rows affected (0.02 sec) @@ -201,7 +197,7 @@ ERROR 1064 (HY000): Query failed if record not exist in dict table. 3 rows in set (0.01 sec) ``` -2. 查询字典表中与键映射的值。由于字典表具有组合主键，因此需要在 `dict_mapping` 中指定所有主键。 +2. 查询字典表中 key 映射的值。由于字典表具有复合主键，因此需要在 `dict_mapping` 中指定所有主键。 ```SQL SELECT dict_mapping('dict2', 'a1', cast('2023-11-22' as DATE));