にインポート

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

注記:

このステートメントは TiDB セルフホスト型にのみ適用され、 TiDB Cloudでは使用できません。

IMPORT INTO Amazon S3、GCS、TiDB ローカルstorageに保存されているファイルからのデータのインポートをサポートします。

  • Amazon S3、GCS、または Azure Blob Storage に保存されているデータ ファイルの場合、 IMPORT INTO TiDB バックエンド タスク分散実行フレームワークでの実行をサポートします。

    • このフレームワークが有効な場合 ( tidb_enable_dist_taskON )、 IMPORT INTOデータ インポート ジョブを複数のサブジョブに分割し、これらのサブジョブを異なる TiDB ノードに分散して実行し、インポート効率を向上させます。
    • このフレームワークが無効になっている場合、 IMPORT INTO現在のユーザーが接続している TiDB ノードでの実行のみをサポートします。
  • TiDB にローカルに保存されているデータ ファイルの場合、 IMPORT INTO現在のユーザーが接続している TiDB ノードでの実行のみをサポートします。したがって、データ ファイルは、現在のユーザーが接続している TiDB ノードに配置する必要があります。プロキシまたはロード バランサ経由で TiDB にアクセスする場合、TiDB にローカルに保存されているデータ ファイルをインポートできません。

制限

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

インポートの前提条件

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

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

必要な権限

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

あらすじ

ImportIntoStmt
IMPORTINTOTableNameColumnNameOrUserVarListSetClauseFROMfileLocationFormatWithOptions
ColumnNameOrUserVarList
(ColumnNameOrUserVar,)
SetClause
SETSetItem,
SetItem
ColumnName=Expr
Format
CSVSQLPARQUET
WithOptions
WITHOptionItem,
OptionItem
optionName=optionValoptionName

パラメータの説明

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

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

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

SetClause

ターゲット列の値がどのように計算されるかを指定します。 SETの式の右側では、 ColumnNameOrUserVarListで指定した変数を参照できます。

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

ファイルの場所

データ ファイルのstorage場所を指定します。Amazon S3、GCS、Azure Blob Storage の URI パス、または TiDB ローカル ファイル パスを指定できます。

  • Amazon S3、GCS、または Azure Blob Storage 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ステートメントは、 CSVSQL 、およびPARQUETの 3 つのデータ ファイル形式をサポートします。指定しない場合、デフォルトの形式はCSVです。

オプションあり

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

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

オプション名サポートされるデータ形式説明
CHARACTER_SET='<string>'CSVデータファイルの文字セットを指定します。デフォルトの文字セットはutf8mb4です。サポートされている文字セットにはbinaryutf8utf8mb4gb18030gbklatin1 、およびasciiが含まれます。
FIELDS_TERMINATED_BY='<string>'CSVフィールド区切り文字を指定します。デフォルトの区切り文字は,です。
FIELDS_ENCLOSED_BY='<char>'CSVフィールド区切り文字を指定します。デフォルトの区切り文字は"です。
FIELDS_ESCAPED_BY='<char>'CSVフィールドのエスケープ文字を指定します。デフォルトのエスケープ文字は\です。
FIELDS_DEFINED_NULL_BY='<string>'CSVフィールドにNULLを表す値を指定します。デフォルト値は\Nです。
LINES_TERMINATED_BY='<string>'CSV行末文字を指定します。デフォルトでは、 IMPORT INTO \n\r 、または\r\nを行終端記号として自動的に識別します。行終端文字がこれら 3 つのいずれかである場合、このオプションを明示的に指定する必要はありません。
SKIP_ROWS=<number>CSVスキップする行数を指定します。デフォルト値は0です。このオプションを使用すると、CSV ファイルのヘッダーをスキップできます。ワイルドカードを使用してインポートするソース ファイルを指定する場合、このオプションはfileLocationのワイルドカードに一致するすべてのソース ファイルに適用されます。
SPLIT_FILECSV単一の CSV ファイルを約 256 MiB の複数の小さなチャンクに分割して並列処理し、インポート効率を向上させます。このパラメータは非圧縮CSV ファイルに対してのみ機能し、 TiDB Lightning strict-formatと同じ使用制限があります。
DISK_QUOTA='<string>'すべてのフォーマットデータの並べ替え中に使用できるディスク容量のしきい値を指定します。デフォルト値は、TiDB 一時ディレクトリのディスク容量の 80% です。合計ディスク サイズを取得できない場合、デフォルト値は 50 GiB です。明示的にDISK_QUOTAを指定する場合は、その値が TiDB 一時ディレクトリのディスク容量の 80% を超えないようにしてください。
DISABLE_TIKV_IMPORT_MODEすべてのフォーマットインポート プロセス中に TiKV をインポート モードに切り替えることを無効にするかどうかを指定します。デフォルトでは、TiKV をインポート モードに切り替えることは無効になっていません。クラスター内で読み取り/書き込み操作が進行中の場合は、このオプションを有効にして、インポート プロセスによる影響を回避できます。
THREAD=<number>すべてのフォーマットインポートの同時実行性を指​​定します。デフォルト値は CPU コアの 50% で、最小値は 1 です。このオプションを明示的に指定してリソース使用量を制御できますが、値が CPU コアの数を超えないようにしてください。データをまったく含まない新しいクラスターにデータをインポートするには、この同時実行数を適切に増やしてインポートのパフォーマンスを向上させることをお勧めします。ターゲット クラスターが本番環境ですでに使用されている場合は、アプリケーションの要件に応じてこの同時実行性を調整することをお勧めします。
MAX_WRITE_SPEED='<string>'すべてのフォーマットTiKV ノードへの書き込み速度を制御します。デフォルトでは、速度制限はありません。たとえば、このオプションを1MiBに指定すると、書き込み速度を 1 MiB/s に制限できます。
CHECKSUM_TABLE='<string>'すべてのフォーマットインポート後にターゲットテーブルに対してチェックサムチェックを実行して、インポートの整合性を検証するかどうかを構成します。サポートされている値には、 "required" (デフォルト)、 "optional" 、および"off"が含まれます。 "required"インポート後にチェックサム チェックを実行することを意味します。チェックサム チェックが失敗した場合、TiDB はエラーを返し、インポートは終了します。 "optional"インポート後にチェックサム チェックを実行することを意味します。エラーが発生した場合、TiDB は警告を返し、エラーを無視します。 "off"インポート後にチェックサム チェックを実行しないことを意味します。
DETACHEDすべてのフォーマットIMPORT INTO非同期で実行するかどうかを制御します。このオプションが有効な場合、 IMPORT INTOを実行するとインポート ジョブ ( Job_IDなど) の情報がすぐに返され、ジョブはバックエンドで非同期的に実行されます。
CLOUD_STORAGE_URIすべてのフォーマットグローバルソートのエンコードされたKVデータが格納されるターゲットアドレスを指定します。 CLOUD_STORAGE_URIが指定されていない場合、 IMPORT INTOシステム変数tidb_cloud_storage_uriの値に基づいてグローバル ソートを使用するかどうかを決定します。このシステム変数がターゲットstorageアドレスを指定している場合、 IMPORT INTOこのアドレスをグローバル ソートに使用します。 CLOUD_STORAGE_URI空ではない値で指定された場合、 IMPORT INTOその値をターゲットstorageアドレスとして使用します。空の値でCLOUD_STORAGE_URI指定すると、ローカル ソートが適用されます。現在、ターゲットstorageアドレスは S3 のみをサポートしています。 URI設定の詳細については、 Amazon S3 URI 形式を参照してください。この機能を使用する場合、すべての TiDB ノードはターゲット S3 バケットに対する読み取りおよび書き込みアクセス権を持っている必要があります。

圧縮ファイル

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

拡大圧縮形式
.gz .gzipgzip圧縮形式
.zstd .zstZStd圧縮形式
.snappyきびきびとした圧縮フォーマット

注記:

Snappy 圧縮ファイルは公式の Snappy フォーマットに存在する必要があります。 Snappy 圧縮の他のバリアントはサポートされていません。

グローバルソート

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

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

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

バックエンドタスク分散実行フレームワークが有効な場合、 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_triggertidb_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 &#x3C;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.csvfile-02.csv 、およびfile-03.csvという名前の 3 つのファイルがあると仮定します。 IMPORT INTOを使用してこれら 3 つのファイルをターゲット テーブルtにインポートするには、次の SQL ステートメントを実行できます。

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

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

  • 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}';
  • Azure Blob Storage からデータ ファイルをインポートします。

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

Amazon S3、GCS、または Azure Blob Storage の 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 拡張機能です。

こちらも参照

このページは役に立ちましたか?

Playground
新規
登録なしで TiDB の機能をワンストップでインタラクティブに体験できます。
製品
TiDB Cloud
TiDB
価格
PoC お問い合わせ
エコシステム
TiKV
TiFlash
OSS Insight
© 2024 PingCAP. All Rights Reserved.
Privacy Policy.