インポート先

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

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

注記：

TiDB Lightningと比較して、 IMPORT INTO TiDB ノード上で直接実行でき、自動化された分散タスクスケジューリングとTiDB グローバルソートサポートし、デプロイメント、リソース利用率、タスク設定の利便性、呼び出しと統合の容易さ、高可用性、スケーラビリティにおいて大幅な改善をもたらします。適切なシナリオでは、TiDB LightningではなくIMPORT INTO使用を検討することをお勧めします。

制限

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

IMPORT INTO ... FROM FILE制限

• TiDBセルフマネージドの場合、 IMPORT INTOタスクあたり10TiB以内のデータのインポートをサポートします。3機能を有効にすると、 グローバルソートタスクIMPORT INTO 40TiB以内のデータのインポートをサポートします。
• TiDB Cloud専用について、インポートするデータが 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_PRECHECK 2 つだけをサポートします。
• IMPORT INTO ... FROM SELECT 、 SHOW IMPORT JOB(s)やCANCEL IMPORT JOB <job-id>などのタスク管理ステートメントをサポートしていません。
• TiDB の一時ディレクトリは、 SELECTステートメントのクエリ結果全体を格納するのに十分なスペースが必要です ( DISK_QUOTAオプションの構成は現在サポートされていません)。
• tidb_snapshot使用した履歴データのインポートはサポートされていません。
• SELECT節の構文は複雑なため、 IMPORT INTOのWITHパラメータが 1 節と競合し、 GROUP BY ... [WITH ROLLUP]ような解析エラーが発生する可能性があります。複雑なSELECT文についてはビューを作成し、インポートにはIMPORT INTO ... FROM SELECT * FROM view_name使用することをお勧めします。あるいは、 SELECTのスコープをIMPORT INTO ... FROM (SELECT ...) WITH ...ように括弧で囲んで明確にすることもできます。

インポートの前提条件

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

• インポート対象のテーブルはすでに TiDB に作成されており、空です。
• ターゲット クラスターには、インポートするデータを保存するのに十分なスペースがあります。
• TiDBセルフマネージドの場合、現在のセッションに接続されているTiDBノードの一時ディレクトリ 90GiB以上の空き容量が必要です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で使用したりすることもできます。

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

SetClause

対象列の値の計算方法を指定します。1 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に保存されているファイルを例にとると、パラメータは次のように設定できます。

• 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使用法

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

• 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は単一の大きな圧縮ファイルを同時に解凍できないため、圧縮ファイルのサイズはインポート速度に影響します。解凍後のソースファイルは256MiB以下にすることをお勧めします。

グローバルソート

注記：

グローバルソートはTiDB Cloudサーバーレスクラスターでは使用できません。

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つのファイルがあるとします。これらの3つのファイルをIMPORT INTOを使用してターゲットテーブル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 拡張です。

参照

• ADMIN CHECKSUM TABLE
• CANCEL IMPORT JOB
• SHOW IMPORT JOB(s)
• TiDB 分散実行フレームワーク (DXF)