インポート先

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

注記：

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

TiDB Self-Managed の場合、 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 Self-Managed の場合、 IMPORT INTO 10 TiB 以内のデータのインポートをサポートします。3 TiDB専用場合、 IMPORT INTO 50 GiB 以内のデータのインポートをサポートします。
• IMPORT INTO 、データベース内の既存の空のテーブルへのデータのインポートのみをサポートします。
• 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 Self-Managed では、パフォーマンスを向上させるために、少なくとも 32 個のコアと 64 GiB のメモリを備えた TiDB ノードを使用することをお勧めします。TiDB はインポート中にソートされたデータを TiDB 一時ディレクトリに書き込むため、フラッシュメモリなどの高性能なstorageメディアを TiDB Self-Managed 用に構成することをお勧めします。詳細については、 物理インポートモードの制限参照してください。
• TiDB Self-Managed の場合、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 Self-Managed の場合、現在のセッションに接続されている 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で使用したりすることもできます。

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

節の設定

対象列の値の計算方法を指定します。 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

形式

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

オプション付き

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

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

圧縮ファイル

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

注記：

• Snappy 圧縮ファイルは公式Snappyフォーマットである必要があります。Snappy 圧縮の他のバリエーションはサポートされていません。
• TiDB Lightning は1 つの大きな圧縮ファイルを同時に解凍できないため、圧縮ファイルのサイズがインポート速度に影響します。解凍後のソース ファイルは 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 がグローバル ソート操作とそれに続くインポートを続行する前に、すべてのサブジョブでのローカル ソートの完了を待機する必要があるためです。
• グローバル ソートを使用したインポート ジョブが完了すると、グローバル ソートのクラウド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