Revise dict_mapping function documentation

docs/en/sql-reference/sql-functions/dict-functions/dict_mapping.md

@@ -8,7 +8,12 @@ Returns 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.
 
-Since v3.2.5, StarRocks supports this function. Also, note that currently StarRocks's shared-data mode does not support this function.
+:::note
+
+- Since v3.2.5, StarRocks supports this function
+- Currently StarRocks's shared-data mode does not support this function.
+
+:::
 
 ## Syntax
 
@@ -124,7 +129,7 @@ However, when the value mapped to the specified key is not found, if the `<null_
       4 rows in set (0.02 sec)
       ```
 
-    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.<!--For detailed usage, please refer to xxx.-->
+    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.**
 

docs/ja/sql-reference/sql-functions/dict-functions/dict_mapping.md

@@ -0,0 +1,220 @@
+---
+displayed_sidebar: docs
+---
+
+# 辞書マッピング
+
+辞書テーブル内の指定されたキーにマッピングされた値を返します。
+
+この関数は、主にグローバル辞書テーブルの適用を簡素化するために使用されます。ターゲットテーブルへのデータロード中に、StarRocksはこの関数の入力パラメータを使用して、辞書テーブルから指定されたキーにマッピングされた値を自動的に取得し、その値をターゲットテーブルにロードします。
+
+:::note
+
+- v3.2.5以降、StarRocksはこの関数をサポートしています。
+- 現在、StarRocksの共有データモードはこの関数をサポートしていません。
+
+:::
+
+## 構文
+
+```SQL
+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 ... ]
+
+key_column_expr ::= <column_name> | <expr>
+```
+
+## パラメータ
+
+- 必須パラメータ:
+  - `[<db_name>.]<dict_table>`: 辞書テーブルの名前。プライマリキーテーブルである必要があります。サポートされるデータ型はVARCHARです。
+  - `key_column_expr_list`: 辞書テーブルのキー列の式リスト。1つまたは複数の`key_column_exprs`を含みます。`key_column_expr`は、辞書テーブルのキー列の名前、または特定のキーやキー式であることができます。
+
+    この式リストには、辞書テーブルのすべてのプライマリキー列を含める必要があります。つまり、式の総数は辞書テーブルのプライマリキー列の総数と一致する必要があります。したがって、辞書テーブルが複合プライマリキーを使用する場合、このリストの式は、テーブルスキーマで定義されたプライマリキー列に順序通りに対応する必要があります。このリスト内の複数の式はカンマ (`,`) で区切られます。また、`key_column_expr`が特定のキーまたはキー式である場合、その型は辞書テーブルの対応するプライマリキー列の型と一致する必要があります。
+
+- オプションパラメータ:
+  - `<value_column>`: 値列の名前。これはマッピング列でもあります。値列が指定されていない場合、デフォルトの値列は辞書テーブルのAUTO_INCREMENT列です。値列は、自動インクリメント列とプライマリキーを除く辞書テーブル内の任意の列として定義することもできます。列のデータ型に制限はありません。
+  - `<null_if_not_exist>` (オプション): キーが辞書テーブルに存在しない場合に何を返すか。有効な値:
+    - `true`: キーが存在しない場合、Nullが返されます。
+    - `false` (デフォルト): キーが存在しない場合、例外がスローされます。
+
+## 戻り値
+
+戻り値のデータ型は、値列のデータ型と一貫しています。値列が辞書テーブルの自動インクリメント列である場合、戻り値のデータ型はBIGINTです。
+
+ただし、指定されたキーにマッピングされた値が見つからない場合、`<null_if_not_exist>`パラメータが`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_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.
+   ```