にインポート

IMPORT INTOステートメントは、 TiDB Lightningの物理インポートモードを介して、 CSV 、 SQL 、 PARQUETなどの形式のデータを TiDB の空のテーブルにインポートするために使用されます。

注記：

この機能はTiDB サーバーレスクラスターでは使用できません。

TiDB セルフホストの場合、 IMPORT INTO 、Amazon S3、GCS、および TiDB ローカルstorageに保存されているファイルからのデータのインポートをサポートします。 TiDB専用ではIMPORT INTO Amazon S3 および GCS に保存されているファイルからのデータのインポートがサポートされています。

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

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

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

制限

• TiDB セルフホストの場合、 IMPORT INTO 10 TiB 以内のデータのインポートをサポートします。 TiDB専用 、 IMPORT INTOの場合、50 GiB 以内のデータのインポートがサポートされます。
• IMPORT INTOデータベース内の既存の空のテーブルへのデータのインポートのみをサポートします。
• IMPORT INTOはトランザクションやロールバックをサポートしません。明示的なトランザクション ( BEGIN / END ) 内でIMPORT INTOを実行すると、エラーが返されます。
• IMPORT INTOを実行すると、インポートが完了するまで現在の接続がブロックされます。ステートメントを非同期的に実行するには、 DETACHEDオプションを追加します。
• IMPORT INTO 復元する 、 FLASHBACK CLUSTER 、 インデックス追加の高速化 、 TiDB Lightningを使用したデータ インポート、 TiCDC を使用したデータ レプリケーション、またはポイントインタイムリカバリ (PITR)などの機能との同時作業をサポートしていません。
• クラスター上で一度に実行できるジョブはIMPORT INTOつだけです。 IMPORT INTO実行中のジョブの事前チェックを実行しますが、これは厳密な制限ではありません。複数のインポート ジョブを開始すると、複数のクライアントが同時に実行される場合に機能する可能性がありますが、データの不整合やインポートの失敗IMPORT INTO発生する可能性があるため、それを回避する必要があります。
• データ インポート プロセス中は、ターゲット テーブルに対して DDL または DML 操作を実行しないでください。また、ターゲット データベースに対してFLASHBACK DATABASEを実行しないでください。これらの操作により、インポートの失敗やデータの不整合が発生する可能性があります。また、読み取られるデータに一貫性がない可能性があるため、インポート プロセス中に読み取り操作を実行することはお勧めできません。インポートが完了した後にのみ、読み取りおよび書き込み操作を実行してください。
• インポート プロセスはシステム リソースを大幅に消費します。 TiDB セルフホストの場合、パフォーマンスを向上させるために、少なくとも 32 コアと 64 GiB のメモリを備えた TiDB ノードを使用することをお勧めします。 TiDB はインポート中にソートされたデータを TiDB 一時ディレクトリに書き込むため、TiDB セルフホスト用にフラッシュメモリなどの高性能storageメディアを構成することをお勧めします。詳細については、 物理インポートモードの制限事項を参照してください。
• TiDB セルフホストの場合、TiDB 一時ディレクトリには少なくとも 90 GiB の利用可能なスペースが必要です。インポートするデータの量と同じかそれ以上のstorageスペースを割り当てることをお勧めします。
• 1 つのインポート ジョブは、1 つのターゲット テーブルへのデータのみのインポートをサポートします。複数のターゲット テーブルにデータをインポートするには、ターゲット テーブルのインポートが完了した後、次のターゲット テーブルの新しいジョブを作成する必要があります。
• IMPORT INTOは、TiDB クラスターのアップグレード中はサポートされません。
• グローバルソート機能を使用してデータをインポートする場合、エンコード後の 1 行のデータ サイズは 32 MiB を超えてはなりません。
• データのインポートにグローバル ソート機能を使用する場合、インポート タスクが完了する前にターゲット TiDB クラスターが削除されると、グローバル ソートに使用された一時データが Amazon S3 に残る可能性があります。この場合、S3storageコストの増加を避けるために、残留データを手動で削除する必要があります。
• インポートするデータに、主キーまたは NULL 以外の一意のインデックスが競合するレコードが含まれていないことを確認してください。そうしないと、競合によりインポート タスクが失敗する可能性があります。
• Distributed eXecution Framework (DXF) によってスケジュールされたIMPORT INTOがすでに実行されている場合、そのタスクを新しい TiDB ノードにスケジュールすることはできません。データ インポート タスクを実行する TiDB ノードが再起動されると、データ インポート タスクは実行されなくなりますが、タスクを別の TiDB ノードに転送して実行を継続します。ただし、インポートされたデータがローカル ファイルからのものである場合、タスクは別の TiDB ノードに転送されて実行を継続しません。
• 既知の問題: TiDB ノード構成ファイル内の PD アドレスがクラスターの現在の PD トポロジーと一致しない場合、 IMPORT INTOタスクが失敗する可能性があります。この不一致は、PD が以前にスケールインされたが、それに応じて TiDB 構成ファイルが更新されなかったり、構成ファイルの更新後に TiDB ノードが再起動されなかった場合などに発生する可能性があります。

インポートの前提条件

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

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

必要な権限

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

あらすじ

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

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

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

SetItem ::=
    ColumnName '=' Expr

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

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

OptionItem ::=
    optionName '=' optionVal | optionName

パラメータの説明

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

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

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

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権限を持っていることを確認してください。

注記：

対象クラスタでSEMが有効な場合、 fileLocationローカルファイルパスとして指定できません。

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

• 単一のファイルをインポートする: 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

フォーマット

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

オプションあり

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

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

圧縮ファイル

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

注記：

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

グローバルソート

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

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

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

TiDB 分散実行フレームワーク (DXF)が有効な場合、 IMPORT INTOステートメントでCLOUD_STORAGE_URIオプションを指定するか、システム変数tidb_cloud_storage_uriを使用してエンコードされた KV データのターゲットstorageアドレスを指定することにより、 グローバルソート有効にできます。現在、グローバル ソートstorageアドレスとしてサポートされているのは 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=0.99;
SET GLOBAL tidb_server_memory_limit='88%';

注記：

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

出力

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

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

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ステートメントを実行すると、出力でジョブ情報がすぐに返されます。出力から、ジョブのステータスが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'

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';

MySQLの互換性

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

こちらも参照

• SHOW IMPORT JOB(s)
• CANCEL IMPORT JOB