インポート先
IMPORT INTOステートメントを使用すると、 TiDB Lightningの物理輸入モードを介して TiDB にデータをインポートできます。 IMPORT INTO 、次の 2 つの方法で使用できます。
IMPORT INTO ... FROM FILE:CSV、SQL、PARQUETなどの形式のデータファイルを TiDB の空のテーブルにインポートします。IMPORT INTO ... FROM SELECT:SELECTステートメントのクエリ結果を TiDB の空のテーブルにインポートします。また、AS OF TIMESTAMPでクエリされた履歴データをインポートするためにも使用できます。
注記：
TiDB Lightningと比較して、
IMPORT INTOTiDBノード上で直接実行でき、自動分散タスクスケジューリングとTiDB グローバルソートグローバルをサポートし、デプロイ、リソース利用率、タスク構成の利便性、呼び出しと統合の容易さ、高可用性、スケーラビリティにおいて大幅な改善を提供します。適切なシナリオでは、 TiDB Lightningの代わりにIMPORT INTOの使用を検討することをお勧めします。
制限
IMPORT INTOデータベース内の既存の空のテーブルへのデータのインポートのみをサポートしています。IMPORT INTO、同じテーブルの他のパーティションに既にデータが含まれている場合、空のパーティションへのデータインポートをサポートしていません。インポート操作を行うには、対象テーブルが完全に空である必要があります。IMPORT INTO一時テーブルまたはキャッシュキャッシュされたテーブルへのデータのインポートをサポートしていません。IMPORT INTOトランザクションまたはロールバックをサポートしていません。明示的なトランザクション (IMPORT INTO/ {BEGIN内) でENDを実行するとエラーが返されます。IMPORT INTOバックアップと復元、FLASHBACK CLUSTER、 インデックス追加処理の高速化、 TiDB Lightning を使用したデータ インポート、TiCDC を使用したデータ レプリケーション、または特定時点復旧（PITR）などの機能との同時作業をサポートしていません。互換性の詳細については、 TiDB LightningとIMPORT INTOのTiCDCおよびログバックアップとの互換性参照してください。- データインポート処理中は、対象テーブルに対してDDLまたはDML操作を実行したり、対象データベースに対して
FLASHBACK DATABASEを実行したりしないでください。これらの操作は、インポートの失敗やデータの不整合を引き起こす可能性があります。また、インポート処理中に読み取り操作を実行することも推奨されません。読み取られるデータに不整合が生じる可能性があるためです。読み取りおよび書き込み操作は、インポートが完了した後にのみ実行してください。 - インポート プロセスはシステム リソースを大幅に消費します。 TiDB セルフマネージドの場合、パフォーマンスを向上させるために、少なくとも 32 コアと 64 GiB のメモリを備えた TiDB ノードを使用することをお勧めします。 TiDB はインポート中にソートされたデータを TiDB 一時ディレクトリに書き込むため、フラッシュメモリなどの TiDB 自己管理用の高性能storageメディアを構成することをお勧めします。詳細については、 物理輸入モードの制限を参照してください。
- TiDB Self-Managedの場合、TiDB 一時ディレクトリは少なくとも90 GiBの空き容量が必要です。インポートするデータ量と同等以上のstorage容量を割り当てることをお勧めします。
- 1つのインポートジョブは、1つのターゲットテーブルへのデータインポートのみをサポートします。
IMPORT INTOTiDB クラスタのアップグレード時にはサポートされません。- インポートするデータに、主キーまたはNULL以外の一意インデックスの競合が発生するレコードが含まれていないことを確認してください。競合が発生すると、インポート処理が失敗する可能性があります。
- 既知の問題: TiDBノード構成ファイル内のPDアドレスがクラスタの現在のPDトポロジと一致しない場合
IMPORT INTOタスクが失敗する可能性があります。この不一致は、PDが以前にスケールインされたものの、TiDB構成ファイルがそれに応じて更新されなかった場合や、構成ファイルの更新後にTiDBノードが再起動されなかった場合などに発生する可能性があります。
IMPORT INTO ... FROM FILE制限
- TiDB Self-Managedの場合、各
IMPORT INTOタスクは10 TiB以内のデータインポートをサポートします。 機能を有効にすると、各IMPORT INTOタスクグローバルソート40 TiB以内のデータインポートをサポートします。 - TiDB Cloud Dedicatedの場合、インポートするデータが 500 GiB を超える場合は、少なくとも 16 コアの TiDB ノードを使用し、グローバルソート機能を有効にすることをお勧めします。そうすると、各
IMPORT INTOタスクは 40 TiB 以内のデータのインポートをサポートします。インポートするデータが 500 GiB 以内である場合、または TiDB ノードのコア数が 16 未満の場合は、グローバルソート機能を有効にしないことをお勧めします。 IMPORT INTO ... FROM FILEの実行は、インポートが完了するまで現在の接続をブロックします。ステートメントを非同期で実行するには、DETACHEDオプションを追加してください。- 最大 16 個の
IMPORT INTOタスクを各クラスターで同時に実行できます ( TiDB分散実行フレームワーク（DXF）の使用制限を参照)。クラスターに十分なリソースが不足している場合、またはタスクの最大数に達している場合、新しく送信されたインポート タスクは実行のためにキューに入れられます。 - データのインポートにグローバルソート機能を使用する場合、
THREADオプションの値は少なくとも8である必要があります。 - グローバルソート機能を使用してデータをインポートする場合、エンコード後の 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_PRECHECK2 つのインポートインポートオプションのみをサポートします。IMPORT INTO ... FROM SELECTSHOW IMPORT JOB(s)やCANCEL IMPORT JOB <job-id>などのタスク管理ステートメントをサポートしていません。- TiDB では、
SELECTステートメントのクエリ結果全体を格納するのに十分なスペースが必要です (DISK_QUOTAオプション一時ディレクトリ設定は現在サポートされていません)。 tidb_snapshotを使用した履歴データのインポートはサポートされていません。SELECT句の構文は複雑なため、WITH内のIMPORT INTOパラメーターがこれと競合し、GROUP BY ... [WITH ROLLUP]のような解析エラーが発生する可能性があります。複雑なSELECTステートメント用にビューを作成し、インポートにはIMPORT INTO ... FROM SELECT * FROM view_nameを使用することをお勧めします。または、SELECTIMPORT INTO ... FROM (SELECT ...) WITH ...句のスコープを明確にすることもできます。
インポートの前提条件
IMPORT INTOを使用してデータをインポートする前に、以下の要件を満たしていることを確認してください。
- インポート対象のテーブルは既にTiDB内に作成されており、空の状態です。
- 対象クラスターには、インポートするデータを保存するのに十分な空き容量があります。
- TiDB Self-Managed の場合、 現在のセッションに接続されている TiDB ノードの空き容量一時ディレクトリ90 GiB 以上必要です
tidb_enable_dist_taskが有効になっており、インポートするデータが S3 または GCS から取得される場合は、クラスタ内の各 TiDB ノードの一時ディレクトリに十分なディスク容量があることを確認してください。
必要な権限
IMPORT INTOを実行するには、対象テーブルに対するSELECT 、 UPDATE 、 INSERT 、 DELETE 、およびALTERの権限。TiDB ローカルstorageにファイルをインポートするには、 FILE権限も必要です。
あらすじ
- ImportIntoStmt
- ColumnNameOrUserVarList
- ColumnNameList
- SetClause
- SetItem
- Format
- WithOptions
- OptionItem
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 ::=
'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権限を持っていることを確認してください。
注記：
ターゲット クラスターで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 1.csvと2.csvを指定されたパスs3://<bucket-name>/path/to/data/[12].csvにインポートします。
形式
IMPORT INTOステートメントは、 CSV 、 SQL 、およびPARQUETデータ ファイル形式をサポートしています。指定しない場合、デフォルトの形式はCSVです。
オプション付き
WithOptionsを使用すると、インポートオプションを指定し、データインポートプロセスを制御できます。たとえば、バックエンドでデータファイルのインポートを非同期で実行するには、 DETACHEDステートメントにWITH DETACHEDオプションを追加して、インポートのIMPORT INTOモードを有効にします。
サポートされているオプションは以下のとおりです。
IMPORT INTO ... FROM FILE方法
TiDB Self-Managed の場合、 IMPORT INTO ... FROM FILEは Amazon S3、GCS、および TiDB ローカルstorageに保存されているファイルからのデータインポートをサポートしています。 TiDB Cloud Dedicatedの場合、 IMPORT INTO ... FROM FILEは Amazon S3 および GCS に保存されているファイルからのデータインポートをサポートしています。 TiDB Cloud StarterおよびTiDB Cloud Essentialの場合、 IMPORT INTO ... FROM FILEは Amazon S3 および Alibaba Cloud OSS に保存されているファイルからのデータインポートをサポートしています。
Amazon S3 または GCS に保存されているデータ ファイルの場合、
IMPORT INTO ... FROM FILETiDB分散実行フレームワーク（DXF）での実行をサポートしています。- DXF が有効になっている場合 ( tidb_enable_dist_taskが
ONの場合)、IMPORT INTOデータインポートジョブを複数のサブジョブに分割し、これらのサブジョブを異なる TiDB ノードに分散して実行することで、インポート効率を向上させます。 - DXF が無効になっている場合、
IMPORT INTO ... FROM FILE現在のユーザーが接続している TiDB ノードでの実行のみをサポートします。
- DXF が有効になっている場合 ( tidb_enable_dist_taskが
TiDBにローカルに保存されているデータファイルについては、
IMPORT INTO ... FROM FILE現在ユーザーが接続しているTiDBノードでのみ実行がサポートされます。そのため、データファイルは現在ユーザーが接続しているTiDBノードに配置する必要があります。プロキシまたはロードバランサー経由でTiDBにアクセスする場合、TiDBにローカルに保存されているデータファイルをインポートすることはできません。
圧縮ファイル
IMPORT INTO ... FROM FILEは、圧縮されたCSVおよびSQLファイルのインポートをサポートしています。ファイル拡張子に基づいて、ファイルが圧縮されているかどうか、および圧縮形式を自動的に判別できます。
注記：
- Snappy 圧縮ファイルは公式Snappyフォーマットに存在する必要があります。 Snappy 圧縮の他のバリアントはサポートされていません。
- TiDB Lightningは単一の大きな圧縮ファイルを同時に解凍できないため、圧縮ファイルのサイズがインポート速度に影響します。解凍後のソースファイルのサイズは256MiB以下にすることをお勧めします。
グローバルソート
注記：
TiDB Cloud StarterおよびTiDB Cloud Essentialインスタンスでは、グローバルソートは利用できません。
IMPORT INTO ... FROM FILE 、ソースデータファイルのデータインポートジョブを複数のサブジョブに分割し、各サブジョブはインポート前にデータを個別にエンコードおよびソートします。これらのサブジョブのエンコードされた KV 範囲に大きな重複がある場合 (TiDB がデータを KV にエンコードする方法については、 TiDBコンピューティング参照)、TiKV はインポート中に圧縮を維持する必要があり、インポートのパフォーマンスと安定性が低下します。
以下のシナリオでは、KV値の範囲が大きく重複する可能性があります。
- 各サブジョブに割り当てられたデータファイルの行に重複する主キー範囲がある場合、各サブジョブのエンコードによって生成されるデータKVも重複します。
IMPORT INTO、データファイルの走査順序に基づいてサブジョブを分割します。通常は、ファイル名で辞書順にソートされます。
- 対象テーブルに多数のインデックスが存在する場合、またはインデックス列の値がデータファイル内に分散している場合、各サブジョブのエンコードによって生成されるインデックスKVも重複します。
TiDB分散実行フレームワーク（DXF）が有効になっている場合、 CLOUD_STORAGE_URI IMPORT INTOを指定するか、システム変数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変数を設定することをお勧めします。これにより、Go言語のガベージコレクションが頻繁にトリガーされることを防ぎ、インポート効率への影響を軽減できます。
SET GLOBAL tidb_server_memory_limit_gc_trigger=1;
SET GLOBAL tidb_server_memory_limit='75%';
注記：
- ソースデータファイル内のキーバリュー範囲の重複が少ない場合、グローバルソートを有効にするとインポートのパフォーマンスが低下する可能性があります。これは、グローバルソートを有効にすると、TiDB はグローバルソート操作とそれに続くインポートに進む前に、すべてのサブジョブにおけるローカルソートの完了を待つ必要があるためです。
- Global Sortを使用したインポート処理が完了すると、Global Sort用にクラウド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;
ワイルドカードを使用して複数のデータファイルをインポートする
file-01.csvディレクトリにfile-02.csv 、 file-03.csv 、 /path/to/ -PLACEHOLDER-E}} という名前のファイルが 3 つあるとします。これらの 3 つのファイルをtを使用してターゲット テーブルIMPORT INTOにインポートするには、次の 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クエリの結果をインポートします
UNIONの結果をターゲットテーブルtにインポートするには、インポート同時実行数を8に指定し、重要でない項目の事前チェックを無効に設定して、次の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の拡張機能です。