From 35e9835036e0696e2b1d027d6c2128531eb3b914 Mon Sep 17 00:00:00 2001 From: Dan Roscigno Date: Wed, 4 Mar 2026 12:39:11 -0500 Subject: [PATCH 1/4] Fix formatting for dictionary table parameter description --- .../sql-reference/sql-functions/dict-functions/dict_mapping.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 e2ddc975..404edeb0 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 @@ -23,7 +23,7 @@ key_column_expr ::= | ## Parameters - Required parameters: - - `[.]`: The name of the dictionary table, which needs to be a Primary Key table. The supported data type is VARCHAR. + - `[.]`: The name of the dictionary table, which needs to be a Primary Key table. The supported data type is `VARCHAR`. - `key_column_expr_list`: The expression list for key columns in the dictionary table, including one or multiple `key_column_exprs`. The `key_column_expr` can be the name of a key column in the dictionary table, or a specific key or key expression. This expression list needs to include all Primary Key columns of the dictionary table, which means the total number of expressions needs to match the total number of Primary Key columns in the dictionary table. So when the dictionary table uses composite primary key, the expressions in this list needs to correspond to the Primary Key columns defined in the table schema by sequence. Multiple expressions in this list are separated by commas (`,`). And if a `key_column_expr` is a specific key or key expression, its type must match the type of the corresponding Primary Key column in the dictionary table. From 3f269bcc974710a8c13540299fa67aae106069ff Mon Sep 17 00:00:00 2001 From: DanRoscigno Date: Wed, 4 Mar 2026 12:48:23 -0500 Subject: [PATCH 2/4] remove comment Signed-off-by: DanRoscigno --- .../sql-reference/sql-functions/dict-functions/dict_mapping.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 404edeb0..5e50ac50 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 @@ -124,7 +124,7 @@ However, when the value mapped to the specified key is not found, if the ` + The usage of `dict_mapping` in this example can accelerate [deduplication calculations and JOIN queries](../../../using_starrocks/query_acceleration_with_auto_increment.md). Compared to the previous solutions for building a global dictionary to accelerate precise deduplication, the solution by using `dict_mapping` is more flexible and user-friendly. Because the mapping values are directly obtained from the dictionary table at the stage "loading mapping relationships between keys and values into the table". You do not need to write statements to join the dictionary table to obtain mapping values. Additionally, this solution supports various data loading methods. **Example 3: If the mapping column in the table is not configured as a generated column, you need to explicitly configure the `dict_mapping` function for the mapping column when loading data into the table, obtain the values mapped to the keys.** From 1f0dc633f3441cb1ece80b36f5cad0c5ba988c61 Mon Sep 17 00:00:00 2001 From: "docs-automation[bot]" Date: Wed, 4 Mar 2026 17:52:03 +0000 Subject: [PATCH 3/4] docs: automated translation via Gemini --- .../dict-functions/dict_mapping.md | 215 ++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 docs/ja/sql-reference/sql-functions/dict-functions/dict_mapping.md 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..3e4b4ec0 --- /dev/null +++ b/docs/ja/sql-reference/sql-functions/dict-functions/dict_mapping.md @@ -0,0 +1,215 @@ +--- +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列です。値列は、自動インクリメント列とプライマリキーを除く辞書テーブル内の任意の列として定義することもできます。列のデータ型に制限はありません。 + - `` (オプション): キーが辞書テーブルに存在しない場合に何を返すか。有効な値: + - `true`: キーが存在しない場合、Nullが返されます。 + - `false` (デフォルト): キーが存在しない場合、例外がスローされます。 + +## 戻り値 + +返される値のデータ型は、値列のデータ型と一貫しています。値列が辞書テーブルの自動インクリメント列である場合、返される値のデータ型はBIGINTです。 + +ただし、指定されたキーにマッピングされた値が見つからない場合、``パラメータが`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, + -- この列には、STRING型の注文番号が記録されており、これは例1のdictテーブルのorder_uuid列に対応します。 + order_uuid STRING, + batch int comment 'used to distinguish different batch loading', + -- この列には、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 'used to distinguish different batch loading' + ) + 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) -- composite primary Key + 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. + ``` From ea2387aef52db57e05b9fee129e98acdf1883205 Mon Sep 17 00:00:00 2001 From: "docs-automation[bot]" Date: Wed, 4 Mar 2026 17:56:18 +0000 Subject: [PATCH 4/4] docs: automated translation via Gemini --- .../dict-functions/dict_mapping.md | 347 +++++++++--------- 1 file changed, 172 insertions(+), 175 deletions(-) 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 dbdf43b4..f5e7ea54 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 @@ -2,13 +2,13 @@ displayed_sidebar: docs --- -# `dict_mapping` +# 字典映射 -返回字典表中与指定键映射的值。 +返回字典表中指定键对应的值。 -此函数主要用于简化全局字典表的应用。在将数据加载到目标表期间，StarRocks 会通过使用此函数中的输入参数，自动从字典表中获取与指定键映射的值，然后将该值加载到目标表中。 +此函数主要用于简化全局字典表的应用。在数据加载到目标表时，StarRocks 会根据此函数的输入参数，自动从字典表中获取指定键对应的值，然后将该值加载到目标表中。 -自 v3.2.5 起，StarRocks 支持此功能。另请注意，目前 StarRocks 的存算分离模式不支持此功能。 +自 v3.2.5 版本起，StarRocks 支持此函数。此外，请注意，目前 StarRocks 的共享数据模式不支持此函数。 ## 语法 @@ -22,197 +22,194 @@ key_column_expr ::= | ## 参数 -- 必需参数： - - `[.]`：字典表的名称，需要是 Primary Key table。支持的数据类型为 VARCHAR。 - - `key_column_expr_list`：字典表中键列的表达式列表，包括一个或多个 `key_column_exprs`。`key_column_expr` 可以是字典表中键列的名称，也可以是特定的键或键表达式。 +- 必选参数： + - `[.]`：字典表的名称，必须是主键表。支持的数据类型为 `VARCHAR`。 + - `key_column_expr_list`：字典表中键列的表达式列表，包含一个或多个 `key_column_exprs`。`key_column_expr` 可以是字典表中键列的名称，也可以是特定的键或键表达式。 - 此表达式列表需要包括字典表的所有 Primary Key 列，这意味着表达式的总数需要与字典表中 Primary Key 列的总数匹配。因此，当字典表使用组合主键时，此列表中的表达式需要按顺序与表结构中定义的 Primary Key 列相对应。此列表中的多个表达式用逗号 (`,`) 分隔。如果 `key_column_expr` 是特定的键或键表达式，则其类型必须与字典表中相应 Primary Key 列的类型匹配。 + 此表达式列表需要包含字典表的所有主键列，这意味着表达式的总数需要与字典表的主键列总数匹配。因此，当字典表使用复合主键时，此列表中的表达式需要按顺序与表 schema 中定义的主键列对应。此列表中的多个表达式用逗号 (`,`) 分隔。如果 `key_column_expr` 是特定的键或键表达式，其类型必须与字典表中对应主键列的类型匹配。 - 可选参数： - - ``：值列的名称，也就是映射列。如果未指定值列，则默认值列是字典表的 AUTO_INCREMENT 列。值列也可以定义为字典表中的任何列，不包括自增列和主键。该列的数据类型没有限制。 - - ``（可选）：如果键在字典表中不存在，是否返回 Null。有效值： + - ``：值列的名称，也是映射列。如果未指定值列，则默认值列为字典表的 AUTO_INCREMENT 列。值列也可以定义为字典表中除自增列和主键之外的任何列。该列的数据类型没有限制。 + - ``（可选）：当字典表中不存在键时是否返回。有效值： - `true`：如果键不存在，则返回 Null。 - `false`（默认）：如果键不存在，则抛出异常。 ## 返回值 -返回的数据类型与值列的数据类型保持一致。如果值列是字典表的自增列，则返回的数据类型为 BIGINT。 +返回值的类型与值列的数据类型保持一致。如果值列是字典表的自增列，则返回值的类型为 BIGINT。 -但是，当未找到与指定键映射的值时，如果 `` 参数设置为 `true`，则返回 `NULL`。如果参数设置为 `false`（默认），则返回错误 `query failed if record not exist in dict table`。 +但是，当未找到指定键对应的值时，如果 `` 参数设置为 `true`，则返回 `NULL`。如果参数设置为 `false`（默认），则返回错误 `query failed if record not exist in dict table`。 ## 示例 -**示例 1：直接查询字典表中与键映射的值。** - -1. 创建一个字典表并加载模拟数据。 - - ```SQL - 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) - - 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'} - - SELECT * FROM dict; - ``` - - ```sql - +------------+--------------+ - | order_uuid | order_id_int | - +------------+--------------+ - | a1 | 1 | - | a3 | 3 | - | a2 | 2 | - +------------+--------------+ - 3 rows in set (0.01 sec) - ``` - - > **注意** - > - > 目前，`INSERT INTO` 语句不支持部分更新。因此，请确保插入到 `dict` 的键列中的值不重复。否则，在字典表中多次插入相同的键列值会导致其在值列中映射的值发生更改。 - -2. 查询字典表中与键 `a1` 映射的值。 - - ```SQL - 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, - -- 此列记录 STRING 类型的订单号，对应于示例 1 中 dict 表中的 order_uuid 列。 - order_uuid STRING, - batch int comment 'used to distinguish different batch loading', - -- 此列记录与 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 - 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'} - - 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` 函数，以获取与键映射的值。** +**示例 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, + -- 此列记录STRING类型的订单号，对应示例1中dict表中的order_uuid列。 + order_uuid STRING, + batch int comment 'used to distinguish different batch loading', + -- 此列记录与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 'used to distinguish different batch loading' - ) - DUPLICATE KEY (id, order_uuid, order_id_int) - DISTRIBUTED BY HASH(id); - ``` - -2. 当模拟数据加载到此表中时，您可以通过配置 `dict_mapping` 从字典表中获取映射的值。 - - ```SQL - 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'} - - SELECT * FROM dest_table2; - +------+------------+--------------+-------+ - | id | order_uuid | order_id_int | batch | - +------+------------+--------------+-------+ - | 1 | a1 | 1 | 1 | - +------+------------+--------------+-------+ - 1 row in set (0.02 sec) - ``` +> 示例 3 和示例 2 的区别在于，当导入数据表时，您需要修改导入命令，为映射列显式配置 `dict_mapping` 表达式。 + +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' + ) + 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）。 +当 `` 模式被禁用且查询字典表中不存在的键对应的值时，将返回错误而不是 `NULL`。这确保了数据行的键首先加载到字典表中并生成其映射值（字典 ID），然后该数据行才加载到目标表中。 ```SQL -SELECT dict_mapping('dict', 'b1', true); +MySQL [test]> SELECT dict_mapping('dict', 'b1', true); ERROR 1064 (HY000): Query failed if record not exist in dict table. ``` -**示例 5：如果字典表使用组合主键，则在查询时必须指定所有主键。** - -1. 创建一个具有组合主键的字典表，并将模拟数据加载到其中。 - - ```SQL - 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) - - 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'} - - - 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)); - ``` - - 请注意，如果仅指定一个主键，则会发生错误。 - - ```SQL - SELECT dict_mapping('dict2', 'a1'); - ERROR 1064 (HY000): Getting analyzing error. Detail message: dict_mapping function param size should be 3 - 5. - ``` +**示例 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) -- composite primary Key + 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)); + ``` + + 请注意，当只指定一个主键时会发生错误。 + + ```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. + ```