インポート先

IMPORT INTOステートメントを使用すると、 TiDB Lightningの物理インポートモードを介して TiDB にデータをインポートできます。 IMPORT INTO次の 2 つの方法で使用できます。

• IMPORT INTO ... FROM FILE : CSV SQLの形式のデータ ファイルPARQUET TiDB の空のテーブルにインポートします。
• IMPORT INTO ... FROM SELECT : SELECTステートメントのクエリ結果を TiDB の空のテーブルにインポートします。4 AS OF TIMESTAMPクエリされた履歴データをインポートするためにも使用できます。

制限

• IMPORT INTO 、データベース内の既存の空のテーブルへのデータのインポートのみをサポートします。
• IMPORT INTOトランザクションやロールバックをサポートしていません。明示的なトランザクション ( BEGIN / END ) 内でIMPORT INTOを実行すると、エラーが返されます。
• IMPORT INTO 、 復元する 、 FLASHBACK CLUSTER 、 インデックス追加の高速化 、 TiDB Lightningを使用したデータのインポート、 TiCDC を使用したデータのレプリケーション、 ポイントインタイムリカバリ (PITR)などの機能と同時に動作することはサポートされていません。
• データのインポート プロセス中は、ターゲット テーブルに対して DDL または DML 操作を実行しないでください。また、ターゲット データベースに対してFLASHBACK DATABASE実行しないでください。これらの操作は、インポートの失敗やデータの不整合につながる可能性があります。また、読み取られるデータに不整合がある可能性があるため、インポート プロセス中に読み取り操作を実行することは推奨されません。読み取りおよび書き込み操作は、インポートが完了した後にのみ実行してください。
• インポート プロセスはシステム リソースを大量に消費します。TiDB Self-Hosted の場合、パフォーマンスを向上させるには、少なくとも 32 個のコアと 64 GiB のメモリを備えた TiDB ノードを使用することをお勧めします。TiDB はインポート中にソートされたデータを TiDB 一時ディレクトリに書き込むため、フラッシュメモリなどの高性能なstorageメディアを TiDB Self-Hosted 用に構成することをお勧めします。詳細については、 物理インポートモードの制限を参照してください。
• TiDB セルフホストの場合、TiDB 一時ディレクトリ少なくとも 90 GiB の使用可能スペースがあることが予想されます。インポートするデータの量以上のstorageスペースを割り当てることをお勧めします。
• 1 つのインポート ジョブでは、1 つのターゲット テーブルへのデータのインポートのみがサポートされます。
• IMPORT INTO 、TiDB クラスターのアップグレード中はサポートされません。
• インポートするデータに、主キーまたは null 以外の一意のインデックスの競合があるレコードが含まれていないことを確認してください。そうでない場合、競合によりインポート タスクが失敗する可能性があります。
• 既知の問題: TiDB ノード構成ファイル内の PD アドレスがクラスターの現在の PD トポロジと一致しない場合、タスクIMPORT INTOが失敗する可能性があります。この不一致は、PD が以前にスケールインされたが、TiDB 構成ファイルがそれに応じて更新されなかった場合や、構成ファイルの更新後に TiDB ノードが再起動されなかった場合などに発生する可能性があります。

IMPORT INTO ... FROM FILE制限

• TiDB セルフホストの場合、各IMPORT INTOタスクは 10 TiB 以内のデータのインポートをサポートしますグローバルソート機能を有効にすると、各IMPORT INTOタスクは 40 TiB 以内のデータのインポートをサポートします。
• TiDB専用の場合、インポートするデータが 500 GiB を超える場合は、少なくとも 16 個のコアを持つ TiDB ノードを使用し、 グローバルソート機能を有効にすることをお勧めします。これにより、各IMPORT INTOタスクは 40 TiB 以内のデータのインポートをサポートします。インポートするデータが 500 GiB 以内の場合、または TiDB ノードのコアが 16 未満の場合、 グローバルソート機能を有効にすることはお勧めしません。
• IMPORT INTO ... FROM FILEを実行すると、インポートが完了するまで現在の接続がブロックされます。ステートメントを非同期で実行するには、 DETACHEDオプションを追加できます。
• 各クラスターでは最大 16 IMPORT INTOタスクを同時に実行できます ( TiDB 分散実行フレームワーク (DXF) の使用制限を参照)。クラスターに十分なリソースが不足しているか、タスクの最大数に達すると、新しく送信されたインポート タスクは実行キューに入れられます。
• グローバルソート機能をデータのインポートに使用する場合、 THREADオプションの値は少なくとも16である必要があります。
• グローバルソート機能をデータのインポートに使用する場合、エンコード後の 1 行のデータ サイズは 32 MiB を超えてはなりません。
• TiDB 分散実行フレームワーク (DXF)が有効になっていない場合に作成されるIMPORT INTOタスクはすべて、タスクが送信されたノードで直接実行され、後で DXF が有効になった後でも、これらのタスクは他の TiDB ノードでの実行がスケジュールされません。DXF が有効になると、S3 または GCS からデータをインポートする新しく作成されたIMPORT INTOタスクのみが自動的にスケジュールされるか、他の TiDB ノードにフェイルオーバーされて実行されます。

IMPORT INTO ... FROM SELECT制限

• IMPORT INTO ... FROM SELECT 、現在のユーザーが接続している TiDB ノードでのみ実行でき、インポートが完了するまで現在の接続をブロックします。
• IMPORT INTO ... FROM SELECT インポートオプション : THREADとDISABLE_PRECHECK 2 つのみをサポートします。
• IMPORT INTO ... FROM SELECT SHOW IMPORT JOB(s)やCANCEL IMPORT JOB <job-id>などのタスク管理ステートメントをサポートしていません。
• TiDB の一時ディレクトリは、 SELECTステートメントのクエリ結果全体を格納するのに十分なスペースが必要です ( DISK_QUOTAオプションの構成は現在サポートされていません)。
• tidb_snapshotを使用した履歴データのインポートはサポートされていません。

インポートの前提条件

IMPORT INTO使用してデータをインポートする前に、次の要件が満たされていることを確認してください。

• インポート対象のテーブルは TiDB にすでに作成されており、空です。
• ターゲット クラスターには、インポートするデータを保存するのに十分なスペースがあります。
• TiDB セルフホストの場合、現在のセッションに接続されている TiDB ノードの一時ディレクトリ 、少なくとも 90 GiB の使用可能なスペースがあります。3 tidb_enable_dist_task有効になっていて、インポートするデータが S3 または GCS からのものである場合は、クラスター内の各 TiDB ノードの一時ディレクトリに十分なディスク容量があることも確認してください。

必要な権限

IMPORT INTOを実行するには、対象テーブルに対するSELECT 、 UPDATE 、 INSERT 、 DELETE 、およびALTER権限が必要です。TiDB ローカルstorageにファイルをインポートするには、 FILE権限も必要です。

概要

ImportIntoStmt ::=
    'IMPORT' 'INTO' TableName ColumnNameOrUserVarList? SetClause? FROM fileLocation Format? WithOptions?
    |
    'IMPORT' 'INTO' TableName ColumnNameList? FROM SelectStatement WithOptions?

ColumnNameOrUserVarList ::=
    '(' ColumnNameOrUserVar (',' ColumnNameOrUserVar)* ')'

ColumnNameList ::=
    '(' ColumnName (',' ColumnName)* ')'

SetClause ::=
    'SET' SetItem (',' SetItem)*

SetItem ::=
    ColumnName '=' Expr

Format ::=
    'CSV' | 'SQL' | 'PARQUET'

WithOptions ::=
    'WITH' OptionItem (',' OptionItem)*

OptionItem ::=
    optionName '=' optionVal | optionName

パラメータの説明

列名またはユーザー変数リスト

これは、データ ファイル内の各フィールドがターゲット テーブルの列とどのように対応するかを指定します。また、フィールドを変数にマップしてインポート時に特定のフィールドをスキップしたり、 SetClauseで使用したりすることもできます。

• このパラメータを指定しない場合は、データ ファイルの各行のフィールド数がターゲット テーブルの列数と一致する必要があり、フィールドは対応する列に順番にインポートされます。
• このパラメータを指定する場合、指定された列または変数の数は、データ ファイルの各行のフィールドの数と一致する必要があります。

節の設定

対象列の値の計算方法を指定します。 SET式の右側では、 ColumnNameOrUserVarListで指定した変数を参照できます。

SET式の左側では、 ColumnNameOrUserVarListに含まれていない列名のみを参照できます。対象の列名がColumnNameOrUserVarListにすでに存在する場合、 SET式は無効です。

ファイルの場所

データ ファイルのstorage場所を指定します。保存場所は、Amazon S3 または GCS URI パス、あるいは TiDB ローカル ファイル パスにすることができます。

• Amazon S3 または GCS URI パス: URI 設定の詳細については、 外部ストレージサービスの URI 形式参照してください。

• TiDB ローカル ファイル パス: 絶対パスで、ファイル拡張子は.csv 、 .sql 、または.parquetである必要があります。このパスに対応するファイルが現在のユーザーが接続している TiDB ノードに保存されていること、およびユーザーがFILE権限を持っていることを確認してください。

注記：

ターゲット クラスターで検索エンジン最適化有効になっている場合、 fileLocationローカル ファイル パスとして指定することはできません。

fileLocationパラメータでは、単一のファイルを指定するか、 *と[]ワイルドカードを使用して複数のファイルをインポート対象として指定できます。ワイルドカードは、ディレクトリと一致したり、サブディレクトリ内のファイルを再帰的に一致したりしないため、ファイル名でのみ使用できることに注意してください。Amazon S3 に保存されているファイルを例にとると、次のようにパラメータを設定できます。

• 1つのファイルをインポートする: s3://<bucket-name>/path/to/data/foo.csv
• 指定されたパス内のすべてのファイルをインポート: s3://<bucket-name>/path/to/data/*
• 指定されたパス内のサフィックスが.csvであるすべてのファイルをインポートします: s3://<bucket-name>/path/to/data/*.csv
• 指定されたパス内のプレフィックスがfooであるすべてのファイルをインポートします: s3://<bucket-name>/path/to/data/foo*
• 指定されたパスにあるfooプレフィックスと.csvサフィックスを持つすべてのファイルをインポートします: s3://<bucket-name>/path/to/data/foo*.csv
• 指定されたパスに1.csvと2.csvをインポート: s3://<bucket-name>/path/to/data/[12].csv

フォーマット

IMPORT INTOステートメントは、 CSV 、 SQL 、 PARQUET 3 つのデータ ファイル形式をサポートします。指定しない場合は、デフォルトの形式はCSVになります。

オプション付き

WithOptions使用してインポート オプションを指定し、データのインポート プロセスを制御できます。たとえば、バックエンドでデータ ファイルのインポートを非同期的に実行するには、 IMPORT INTOステートメントにWITH DETACHEDオプションを追加して、インポートのDETACHEDモードを有効にできます。

サポートされているオプションは次のとおりです。

IMPORT INTO ... FROM FILE使用法

注記：

IMPORT INTO ... FROM FILE TiDB サーバーレスクラスターでは使用できません。

TiDB Self-Hosted の場合、 IMPORT INTO ... FROM FILE Amazon S3、GCS、および TiDB ローカルstorageに保存されているファイルからのデータのインポートをサポートします。3 のTiDB専用 、 IMPORT INTO ... FROM FILE Amazon S3 および GCS に保存されているファイルからのデータのインポートをサポートします。

• Amazon S3 または GCS に保存されているデータ ファイルの場合、 IMPORT INTO ... FROM FILE TiDB 分散実行フレームワーク (DXF)での実行をサポートします。

  • DXF が有効になっている場合 ( tidb_enable_dist_taskがON )、 IMPORT INTOデータ インポート ジョブを複数のサブジョブに分割し、これらのサブジョブを異なる TiDB ノードに分散して実行することで、インポート効率を向上させます。
  • DXF が無効になっている場合、 IMPORT INTO ... FROM FILE現在のユーザーが接続している TiDB ノードでの実行のみをサポートします。

• TiDB にローカルに保存されているデータ ファイルの場合、 IMPORT INTO ... FROM FILE現在のユーザーが接続している TiDB ノードでの実行のみをサポートします。したがって、データ ファイルは現在のユーザーが接続している TiDB ノードに配置する必要があります。プロキシまたはロード バランサーを介して TiDB にアクセスする場合、TiDB にローカルに保存されているデータ ファイルをインポートすることはできません。

圧縮ファイル

IMPORT INTO ... FROM FILE 、圧縮されたCSVおよびSQLファイルのインポートをサポートします。ファイル拡張子に基づいて、ファイルが圧縮されているかどうか、および圧縮形式を自動的に判断できます。

注記：

• Snappy 圧縮ファイルは公式Snappyフォーマットである必要があります。Snappy 圧縮の他のバリエーションはサポートされていません。
• TiDB Lightning は1 つの大きな圧縮ファイルを同時に解凍できないため、圧縮ファイルのサイズがインポート速度に影響します。解凍後のソース ファイルは 256 MiB 以下にすることをお勧めします。

グローバルソート

IMPORT INTO ... FROM FILE 、ソース データ ファイルのデータ インポート ジョブを複数のサブジョブに分割し、各サブジョブはインポート前にデータを個別にエンコードおよびソートします。これらのサブジョブのエンコードされた KV 範囲に大幅な重複がある場合 (TiDB がデータを KV にエンコードする方法については、 TiDBコンピューティングを参照)、TiKV はインポート中に圧縮を維持する必要があり、インポートのパフォーマンスと安定性が低下します。

次のシナリオでは、KV 範囲に大きな重複が生じる可能性があります。

• 各サブジョブに割り当てられたデータ ファイル内の行の主キー範囲が重複している場合、各サブジョブのエンコードによって生成されるデータ KV も重複します。
  • IMPORT INTO 、データ ファイルのトラバース順序に基づいてサブジョブを分割します。通常はファイル名で辞書順にソートされます。
• 対象テーブルに多数のインデックスがある場合、またはインデックス列の値がデータ ファイル内に分散している場合、各サブジョブのエンコードによって生成されるインデックス KV も重複します。

TiDB 分散実行フレームワーク (DXF)が有効になっている場合、 IMPORT INTOステートメントでCLOUD_STORAGE_URIオプションを指定するか、システム変数tidb_cloud_storage_uriを使用してエンコードされた KV データのターゲットstorageアドレスを指定することでグローバルソート有効にできます。現在、グローバル ソートでは、storageアドレスとして Amazon S3 の使用がサポートされています。グローバル ソートを有効にすると、 IMPORT INTOエンコードされた KV データをクラウドstorageに書き込み、クラウドstorageでグローバル ソートを実行してから、グローバルにソートされたインデックスとテーブル データを TiKV に並列インポートします。これにより、KV の重複によって発生する問題が防止され、インポートの安定性とパフォーマンスが向上します。

グローバルソートは大量のメモリリソースを消費します。データのインポート前に、 tidb_server_memory_limit_gc_triggerとtidb_server_memory_limit変数を設定することをお勧めします。これにより、golang GC が頻繁にトリガーされ、インポートの効率に影響が及ぶのを回避できます。

SET GLOBAL tidb_server_memory_limit_gc_trigger=1;
SET GLOBAL tidb_server_memory_limit='75%';

注記：

• ソース データ ファイル内の KV 範囲の重複が少ない場合、グローバル ソートを有効にするとインポートのパフォーマンスが低下する可能性があります。これは、グローバル ソートを有効にすると、TiDB がグローバル ソート操作とそれに続くインポートを続行する前に、すべてのサブジョブでのローカル ソートの完了を待機する必要があるためです。
• グローバル ソートを使用したインポート ジョブが完了すると、グローバル ソートのクラウドstorageに保存されたファイルは、バックグラウンド スレッドで非同期的にクリーンアップされます。

出力

IMPORT INTO ... FROM FILEインポートを完了するか、 DETACHEDモードが有効になっている場合、TiDB は次の例に示すように、出力に現在のジョブ情報を返します。各フィールドの説明については、 SHOW IMPORT JOB(s)を参照してください。

IMPORT INTO ... FROM FILEインポートを完了すると、出力例は次のようになります。

IMPORT INTO t FROM '/path/to/small.csv';
+--------+--------------------+--------------+----------+-------+----------+------------------+---------------+----------------+----------------------------+----------------------------+----------------------------+------------+
| Job_ID | Data_Source        | Target_Table | Table_ID | Phase | Status   | Source_File_Size | Imported_Rows | Result_Message | Create_Time                | Start_Time                 | End_Time                   | Created_By |
+--------+--------------------+--------------+----------+-------+----------+------------------+---------------+----------------+----------------------------+----------------------------+----------------------------+------------+
|  60002 | /path/to/small.csv | `test`.`t`   |      363 |       | finished | 16B              |             2 |                | 2023-06-08 16:01:22.095698 | 2023-06-08 16:01:22.394418 | 2023-06-08 16:01:26.531821 | root@%     |
+--------+--------------------+--------------+----------+-------+----------+------------------+---------------+----------------+----------------------------+----------------------------+----------------------------+------------+

DETACHEDモードが有効になっている場合、 IMPORT INTO ... FROM FILEステートメントを実行すると、出力にジョブ情報がすぐに返されます。出力から、ジョブのステータスがpendingであり、実行を待機していることがわかります。

IMPORT INTO t FROM '/path/to/small.csv' WITH DETACHED;
+--------+--------------------+--------------+----------+-------+---------+------------------+---------------+----------------+----------------------------+------------+----------+------------+
| Job_ID | Data_Source        | Target_Table | Table_ID | Phase | Status  | Source_File_Size | Imported_Rows | Result_Message | Create_Time                | Start_Time | End_Time | Created_By |
+--------+--------------------+--------------+----------+-------+---------+------------------+---------------+----------------+----------------------------+------------+----------+------------+
|  60001 | /path/to/small.csv | `test`.`t`   |      361 |       | pending | 16B              |          NULL |                | 2023-06-08 15:59:37.047703 | NULL       | NULL     | root@%     |
+--------+--------------------+--------------+----------+-------+---------+------------------+---------------+----------------+----------------------------+------------+----------+------------+

インポートジョブのビューと管理

DETACHEDモードが有効になっているインポート ジョブの場合、 SHOW IMPORTを使用して現在のジョブの進行状況を表示できます。

インポート ジョブが開始された後は、 CANCEL IMPORT JOB <job-id>使用してキャンセルできます。

例

ヘッダー付きのCSVファイルをインポートする

IMPORT INTO t FROM '/path/to/file.csv' WITH skip_rows=1;

DETACHEDモードでファイルを非同期にインポートする

IMPORT INTO t FROM '/path/to/file.csv' WITH DETACHED;

データファイル内の特定のフィールドのインポートをスキップする

データ ファイルが CSV 形式であり、その内容が次のとおりであると仮定します。

id,name,age
1,Tom,23
2,Jack,44

インポートのターゲット テーブル スキーマがCREATE TABLE t(id int primary key, name varchar(100))であると仮定します。データ ファイルのageフィールドをテーブルtにインポートするのをスキップするには、次の SQL ステートメントを実行します。

IMPORT INTO t(id, name, @1) FROM '/path/to/file.csv' WITH skip_rows=1;

ワイルドカードを使用して複数のデータファイルをインポートする

/path/to/ディレクトリにfile-01.csv 、 file-02.csv 、 file-03.csvという名前の 3 つのファイルがあるとします。 IMPORT INTOを使用してこれらの 3 つのファイルをターゲット テーブルtにインポートするには、次の SQL ステートメントを実行します。

IMPORT INTO t FROM '/path/to/file-*.csv';

file-01.csvとfile-03.csvのみをターゲット テーブルにインポートする必要がある場合は、次の SQL ステートメントを実行します。

IMPORT INTO t FROM '/path/to/file-0[13].csv';

Amazon S3 または GCS からデータファイルをインポートする

• Amazon S3 からデータ ファイルをインポートします。

  IMPORT INTO t FROM 's3://bucket-name/test.csv?access-key=XXX&secret-access-key=XXX';
  

• GCS からデータ ファイルをインポートします。

  IMPORT INTO t FROM 'gs://import/test.csv?credentials-file=${credentials-file-path}';
  

Amazon S3 または GCS の URI パス設定の詳細については、 外部ストレージサービスの URI 形式参照してください。

SetClauseを使用して列の値を計算する

データ ファイルが CSV 形式であり、その内容が次のとおりであると仮定します。

id,name,val
1,phone,230
2,book,440

インポートのターゲット テーブル スキーマがCREATE TABLE t(id int primary key, name varchar(100), val int)であると仮定します。インポート中にval列の値を 100 倍にしたい場合は、次の SQL ステートメントを実行できます。

IMPORT INTO t(id, name, @1) SET val=@1*100 FROM '/path/to/file.csv' WITH skip_rows=1;

SQL形式のデータファイルをインポートする

IMPORT INTO t FROM '/path/to/file.sql' FORMAT 'sql';

書き込み速度をTiKVに制限する

TiKV ノードへの書き込み速度を 10 MiB/s に制限するには、次の SQL ステートメントを実行します。

IMPORT INTO t FROM 's3://bucket/path/to/file.parquet?access-key=XXX&secret-access-key=XXX' FORMAT 'parquet' WITH MAX_WRITE_SPEED='10MiB';

IMPORT INTO ... FROM SELECT使用法

IMPORT INTO ... FROM SELECT使用すると、 SELECTステートメントのクエリ結果を TiDB の空のテーブルにインポートできます。また、 AS OF TIMESTAMPでクエリされた履歴データをインポートするためにも使用できます。

SELECTのクエリ結果をインポートする

インポートの同時実行性を8に指定し、重要でない項目の事前チェックを無効にして、 UNION結果をターゲット テーブルtにインポートするには、次の SQL ステートメントを実行します。

IMPORT INTO t FROM SELECT * FROM src UNION SELECT * FROM src2 WITH THREAD = 8, DISABLE_PRECHECK;

指定した時点の履歴データをインポートする

指定した時点の履歴データをターゲット テーブルtにインポートするには、次の SQL ステートメントを実行します。

IMPORT INTO t FROM SELECT * FROM src AS OF TIMESTAMP '2024-02-27 11:38:00';

MySQL 互換性

このステートメントは、MySQL 構文に対する TiDB 拡張です。

参照

• SHOW IMPORT JOB(s)
• CANCEL IMPORT JOB