バージョン: 2.1

Insert Into Values

INSERT INTO VALUES文は、SQLからDorisTableに値をインポートすることをサポートしています。INSERT INTO VALUESは同期インポート方法で、インポートの実行後にインポート結果が返されます。インポートが成功したかどうかは、返された結果に基づいて判断できます。INSERT INTO VALUESはインポートタスクの原子性を保証し、すべてのデータが正常にインポートされるか、まったくインポートされないかのいずれかを意味します。

適用シナリオ

ユーザーがDorisシステムの機能を検証するために少数のテストデータレコードのみをインポートしたい場合、INSERT INTO VALUES構文が適用できます。MySQL構文と似ています。ただし、本番環境でINSERT INTO VALUESを使用することは推奨されません。
並行INSERT INTO VALUESジョブのパフォーマンスは、コミット段階でボトルネックになります。大量のデータをロードする場合、group commitを有効にして高いパフォーマンスを実現できます。

実装

INSERT INTO VALUESを使用する場合、インポートジョブはMySQLプロトコルを使用してFEノードに開始され、送信される必要があります。FEは実行プランを生成し、これにはクエリ関連のオペレータが含まれ、最後のオペレータはOlapTableSinkです。OlapTableSinkオペレータは、クエリ結果をターゲットTableに書き込む役割を担います。実行プランは、その後BEノードに送信されて実行されます。DorisはBEノードの1つをCoordinatorとして指定し、データを受信して他のBEノードに配布します。

はじめに

INSERT INTO VALUESジョブはMySQLプロトコルを使用して送信および転送されます。以下の例は、MySQLコマンドラインインターフェースを通じてINSERT INTO VALUESを使用してインポートジョブを送信することを示しています。

準備

INSERT INTO VALUESには、ターゲットTableに対するINSERT権限が必要です。GRANTコマンドを使用してユーザーアカウントに権限を付与できます。

INSERT INTO VALUESジョブの作成

INSERT INTO VALUES

ソースTableの作成

CREATE TABLE testdb.test_table(
    user_id            BIGINT       NOT NULL COMMENT "User ID",
    name               VARCHAR(20)           COMMENT "User name",
    age                INT                   COMMENT "User age"
)
DUPLICATE KEY(user_id)
DISTRIBUTED BY HASH(user_id) BUCKETS 10;

INSERT INTO VALUES を使用してソースTableにデータをインポートします（本番環境では推奨されません）。

INSERT INTO testdb.test_table (user_id, name, age)
VALUES (1, "Emily", 25),
       (2, "Benjamin", 35),
       (3, "Olivia", 28),
       (4, "Alexander", 60),
       (5, "Ava", 17);

INSERT INTO VALUES は同期インポート方式であり、インポート結果が直接ユーザーに返されます。

Query OK, 5 rows affected (0.308 sec)
{'label':'label_26eebc33411f441c_b2b286730d495e2c', 'status':'VISIBLE', 'txnId':'61071'}

インポートされたデータを表示する。

MySQL> SELECT COUNT(*) FROM testdb.test_table;
+----------+
| count(*) |
+----------+
|        5 |
+----------+
1 row in set (0.179 sec)

INSERT INTO VALUES ジョブの表示

完了したINSERT INTO VALUESタスクを表示するには、SHOW LOADコマンドを使用できます。

mysql> SHOW LOAD FROM testdb\G
*************************** 1. row ***************************
         JobId: 77172
         Label: label_26eebc33411f441c_b2b286730d495e2c
         State: FINISHED
      Progress: Unknown id: 77172
          Type: INSERT
       EtlInfo: NULL
      TaskInfo: cluster:N/A; timeout(s):14400; max_filter_ratio:0.0
      ErrorMsg: NULL
    CreateTime: 2024-11-20 16:44:08
  EtlStartTime: 2024-11-20 16:44:08
 EtlFinishTime: 2024-11-20 16:44:08
 LoadStartTime: 2024-11-20 16:44:08
LoadFinishTime: 2024-11-20 16:44:08
           URL: 
    JobDetails: {"Unfinished backends":{},"ScannedRows":0,"TaskNumber":0,"LoadBytes":0,"All backends":{},"FileNumber":0,"FileSize":0}
 TransactionId: 61071
  ErrorTablets: {}
          User: root
       Comment: 
1 row in set (0.00 sec)

INSERT INTO VALUES ジョブのキャンセル

現在実行中のINSERT INTO VALUES ジョブは Ctrl-C でキャンセルできます。

マニュアル

構文

INSERT INTO VALUES は通常テスト目的で使用されます。本番環境での使用は推奨されません。

INSERT INTO target_table (col1, col2, ...)
VALUES (val1, val2, ...), (val3, val4, ...), ...;

パラメータ設定

FE Config

Name	デフォルト値	デスクリプション
insert_load_default_timeout_second	14400s (4 hours)	インポートタスクのタイムアウト（秒）。インポートタスクがこのタイムアウト期間内に完了しない場合、システムによってキャンセルされ、`CANCELLED`としてマークされます。

Session Variable

Name	デフォルト値	デスクリプション
insert_timeout	14400s (4 hours)	SQL文としてのINSERT INTOのタイムアウト（秒）。
enable_insert_strict	true	これがtrueに設定されている場合、無効なデータを含むタスクでINSERT INTOが失敗します。falseに設定されている場合、INSERT INTOは無効な行を無視し、少なくとも1行が正常にインポートされる限り、インポートは成功とみなされます。バージョン2.1.4まで、INSERT INTOはエラー率を制御できないため、このパラメータはデータ品質を厳密にチェックするか、無効なデータを完全に無視するかのいずれかに使用されます。データが無効になる一般的な理由には、ソースデータの列長が宛先列長を超える、列タイプの不一致、パーティションの不一致、列順序の不一致などがあります。
insert_max_filter_ratio	1.0	バージョン2.1.5以降。`enable_insert_strict`がfalseの場合のみ有効。`INSERT INTO FROM S3/HDFS/LOCAL()`を使用する際のエラー許容度を制御するために使用されます。デフォルト値は1.0で、すべてのエラーが許容されることを意味します。0から1の間の小数値を設定できます。エラー行数がこの比率を超えた場合、INSERTタスクは失敗することを意味します。

戻り値

INSERT INTO VALUESはSQL文であり、結果としてJSON文字列を返します。

JSON文字列内のパラメータ：

Parameter	デスクリプション
Label	インポートジョブのラベル：「INSERT INTO tbl WITH LABEL label...」を使用して指定可能
Status	インポートされたデータの可視性：可視の場合、「visible」と表示されます。そうでない場合、「committed」と表示されます。「committed」状態では、インポートは完了していますが、データが可視になるまでに遅延がある可能性があります。この場合、再試行の必要はありません。`visible`：インポートが成功し、データが可視です。`committed`：インポートは完了していますが、データが可視になるまでに遅延がある可能性があります。この場合、再試行の必要はありません。Label Already Exists：指定されたラベルが既に存在するため、別のラベルに変更する必要があります。Fail：インポートが失敗しました。
Err	エラーメッセージ
TxnId	インポートトランザクションのID

成功したINSERT

mysql> INSERT INTO test_table (user_id, name, age) VALUES (1, "Emily", 25), (2, "Benjamin", 35), (3, "Olivia", 28), (NULL, "Alexander", 60), (5, "Ava", 17);
Query OK, 5 rows affected (0.05 sec)
{'label':'label_26eebc33411f441c_b2b286730d495e2c', 'status':'VISIBLE', 'txnId':'61071'}

Query OKは実行が成功したことを示します。5 rows affectedは合計5行のデータがインポートされたことを示します。

警告付きの成功したINSERT

mysql> INSERT INTO test_table (user_id, name, age) VALUES (1, "Emily", 25), (2, "Benjamin", 35), (3, "Olivia", 28), (NULL, "Alexander", 60), (5, "Ava", 17);
Query OK, 4 rows affected, 1 warning (0.04 sec)
{'label':'label_a8d99ae931194d2b_93357aac59981a18', 'status':'VISIBLE', 'txnId':'61068'}

Query OK は正常に実行されたことを示します。4 rows affected は合計4行のデータがインポートされたことを示します。1 warnings はフィルタリングされた行数を示します。

SHOW LOAD文を使用してフィルタリングされた行を確認できます。

この文の結果には、エラーデータをクエリするために使用できるURLが含まれます。詳細については、下記の「エラー行の表示」セクションを参照してください。

mysql> SHOW LOAD WHERE label="label_a8d99ae931194d2b_93357aac59981a18"\G
*************************** 1. row ***************************
         JobId: 77158
         Label: label_a8d99ae931194d2b_93357aac59981a18
         State: FINISHED
      Progress: Unknown id: 77158
          Type: INSERT
       EtlInfo: NULL
      TaskInfo: cluster:N/A; timeout(s):14400; max_filter_ratio:0.0
      ErrorMsg: NULL
    CreateTime: 2024-11-20 16:35:40
  EtlStartTime: 2024-11-20 16:35:40
 EtlFinishTime: 2024-11-20 16:35:40
 LoadStartTime: 2024-11-20 16:35:40
LoadFinishTime: 2024-11-20 16:35:40
           URL: http://10.16.10.7:8743/api/_load_error_log?file=__shard_18/error_log_insert_stmt_a8d99ae931194d2b-93357aac59981a19_a8d99ae931194d2b_93357aac59981a19
    JobDetails: {"Unfinished backends":{},"ScannedRows":0,"TaskNumber":0,"LoadBytes":0,"All backends":{},"FileNumber":0,"FileSize":0}
 TransactionId: 61068
  ErrorTablets: {}
          User: root
       Comment: 
1 row in set (0.00 sec)

コミット済みステータスでの正常なINSERT

mysql> INSERT INTO test_table (user_id, name, age) VALUES (1, "Emily", 25), (2, "Benjamin", 35), (3, "Olivia", 28), (4, "Alexander", 60), (5, "Ava", 17);
Query OK, 5 rows affected (0.04 sec)
{'label':'label_78bf5396d9594d4d_a8d9a914af40f73d', 'status':'COMMITTED', 'txnId':'61074'}

データの不可視状態は一時的であり、データは最終的に可視状態になります。

SHOW TRANSACTION文を使用して、データのバッチの可視性ステータスを確認できます。

結果のTransactionStatus列がvisibleの場合、データが可視状態であることを示します。

mysql> SHOW TRANSACTION WHERE id=61074\G
*************************** 1. row ***************************
     TransactionId: 61074
             Label: label_78bf5396d9594d4d_a8d9a914af40f73d
       Coordinator: FE: 10.16.10.7
 TransactionStatus: VISIBLE
 LoadJobSourceType: INSERT_STREAMING
       PrepareTime: 2024-11-20 16:51:54
     PreCommitTime: NULL
        CommitTime: 2024-11-20 16:51:54
       PublishTime: 2024-11-20 16:51:54
        FinishTime: 2024-11-20 16:51:54
            Reason: 
ErrorReplicasCount: 0
        ListenerId: -1
         TimeoutMs: 14400000
            ErrMsg: 
1 row in set (0.00 sec)

空でない結果セットだがINSERTが失敗

実行の失敗は、データが正常にインポートされなかったことを意味します。エラーメッセージが返されます：

mysql> INSERT INTO test_table (user_id, name, age) VALUES (1, "Emily", 25), (2, "Benjamin", 35), (3, "Olivia", 28), (NULL, "Alexander", 60), (5, "Ava", 17);
ERROR 1105 (HY000): errCode = 2, detailMessage = Insert has too many filtered data 1/5 insert_max_filter_ratio is 0.100000. url: http://10.16.10.7:8747/api/_load_error_log?file=__shard_22/error_log_insert_stmt_5fafe6663e1a45e0-a666c1722ffc8c55_5fafe6663e1a45e0_a666c1722ffc8c55

ERROR 1105 (HY000): errCode = 2, detailMessage = Insert has too many filtered data 1/5 insert_max_filter_ratio is 0.100000. は失敗の根本原因を示しています。エラーメッセージに含まれるURLを使用して、エラーデータの場所を特定できます。詳細については、以下の「エラー行の確認」セクションを参照してください。

ベストプラクティス

データサイズ

INSERT INTO VALUES は通常、テストやデモに使用されます。大量のデータを INSERT INTO VALUES でロードすることは推奨されません。

エラー行の確認

INSERT INTO の結果にURLフィールドが含まれる場合、以下のコマンドを使用してエラー行を確認できます：

SHOW LOAD WARNINGS ON "url";

Example:

mysql> SHOW LOAD WARNINGS ON "http://10.16.10.7:8743/api/_load_error_log?file=__shard_18/error_log_insert_stmt_a8d99ae931194d2b-93357aac59981a19_a8d99ae931194d2b_93357aac59981a19"\G
*************************** 1. row ***************************
         JobId: -1
         Label: NULL
ErrorMsgDetail: Reason: column_name[user_id], null value for not null column, type=BIGINT. src line []; 
1 row in set (0.00 sec)

エラーの一般的な原因には以下が含まれます：ソースデータの列長が宛先列長を超過する場合、列タイプの不一致、パーティションの不一致、列順序の不一致。

INSERT INTO がエラー行を無視するかどうかは、環境変数 enable_insert_strict を設定することで制御できます。

さらなるヘルプ

INSERT INTO のより詳細な構文については、INSERT INTO コマンドマニュアルを参照してください。また、MySQL クライアントのコマンドラインで HELP INSERT と入力することで、さらなる情報を得ることができます。

適用シナリオ​

実装​

はじめに​

準備​

INSERT INTO VALUESジョブの作成​

INSERT INTO VALUES ジョブの表示​

INSERT INTO VALUES ジョブのキャンセル​

マニュアル​

構文​

パラメータ設定​

戻り値​

ベストプラクティス​

データサイズ​

エラー行の確認​

さらなるヘルプ​