Amazon S3 または GCS からTiDB Cloudに CSV ファイルをインポート

このドキュメントでは、CSV ファイルを Amazon Simple Storage Service (Amazon S3) または Google Cloud Storage (GCS) からTiDB Cloudにインポートする方法について説明します。

制限事項

• データの一貫性を確保するために、 TiDB Cloud空のテーブルにのみ CSV ファイルをインポートできます。すでにデータが含まれている既存のテーブルにデータをインポートするには、このドキュメントに従ってTiDB Cloudを使用して一時的な空のテーブルにデータをインポートし、その後INSERT SELECTステートメントを使用してデータをターゲットの既存のテーブルにコピーします。

• TiDB 専用クラスターでチェンジフィードまたはポイントインタイム復元が有効になっている場合、現在のデータ インポート機能では物理インポートモードが使用されているため、クラスターにデータをインポートできません ([**データのインポート]**ボタンが無効になります)。このモードでは、インポートされたデータは変更ログを生成しないため、変更フィードとポイントインタイム リストアはインポートされたデータを検出できません。

ステップ 1. CSV ファイルを準備する

1. CSV ファイルが 256 MB より大きい場合は、それぞれのサイズが 256 MB 程度の小さなファイルに分割することを検討してください。

   TiDB Cloudは非常に大きな CSV ファイルのインポートをサポートしていますが、サイズが約 256 MB の複数の入力ファイルで最高のパフォーマンスを発揮します。これは、 TiDB Cloud が複数のファイルを並行して処理できるため、インポート速度が大幅に向上する可能性があります。

2. CSV ファイルに次の名前を付けます。

   • CSV ファイルにテーブル全体のすべてのデータが含まれている場合は、ファイルに${db_name}.${table_name}.csv形式で名前を付けます。これは、データをインポートするときに${db_name}.${table_name}テーブルにマップされます。

   • 1 つのテーブルのデータが複数の CSV ファイルに分割されている場合は、これらの CSV ファイルに数字のサフィックスを追加します。たとえば、 ${db_name}.${table_name}.000001.csvと${db_name}.${table_name}.000002.csvです。数値接尾辞は連続していなくてもかまいませんが、昇順である必要があります。また、すべての接尾辞が同じ長さになるように、数値の前にゼロを追加する必要があります。

   • TiDB Cloud は、次の形式の圧縮ファイルのインポートをサポートしています: .gzip 、 .gz 、 .zstd 、 .zstおよび.snappy 。圧縮された CSV ファイルをインポートする場合は、ファイルに${db_name}.${table_name}.${suffix}.csv.${compress}形式で名前を付けます${suffix}はオプションで、「000001」などの任意の整数を指定できます。たとえば、 trips.000001.csv.gzファイルをbikeshare.tripsテーブルにインポートする場合は、ファイルの名前をbikeshare.trips.000001.csv.gzに変更する必要があります。

   注記：

   • 圧縮する必要があるのはデータ ファイルだけであり、データベースやテーブル スキーマ ファイルは圧縮する必要はありません。
   • より良いパフォーマンスを実現するには、各圧縮ファイルのサイズを 100 MiB に制限することをお勧めします。
   • Snappy 圧縮ファイルは公式の Snappy フォーマットに存在する必要があります。 Snappy 圧縮の他のバリアントはサポートされていません。
   • 非圧縮ファイルの場合、場合によっては前述のルールに従って CSV ファイル名を更新できない場合 (たとえば、CSV ファイルのリンクが他のプログラムでも使用されている場合)、ファイル名を変更せずに、 ステップ4のマッピング設定を使用して、ソース データを単一のターゲット テーブルにインポートします。

ステップ 2. ターゲットテーブルスキーマを作成する

CSV ファイルにはスキーマ情報が含まれていないため、CSV ファイルからTiDB Cloudにデータをインポートする前に、次のいずれかの方法を使用してテーブル スキーマを作成する必要があります。

• 方法 1: TiDB Cloudで、ソース データのターゲット データベースとテーブルを作成します。

• 方法 2: CSV ファイルが配置されている Amazon S3 または GCS ディレクトリに、次のようにソース データのターゲット テーブル スキーマ ファイルを作成します。

  1. ソース データのデータベース スキーマ ファイルを作成します。

     CSV ファイルがステップ1の命名規則に従っている場合、データベース スキーマ ファイルはデータ インポートのオプションになります。それ以外の場合、データベース スキーマ ファイルは必須です。

     各データベース スキーマ ファイルは${db_name}-schema-create.sql形式であり、 CREATE DATABASE DDL ステートメントが含まれている必要があります。データをインポートするときに、このファイルを使用して、 TiDB Cloud はデータを保存する${db_name}を作成します。

     たとえば、次のステートメントを含むmydb-scehma-create.sqlファイルを作成すると、データのインポート時にTiDB Cloud はmydbデータベースを作成します。

     CREATE DATABASE mydb;
     

  2. ソース データのテーブル スキーマ ファイルを作成します。

     CSV ファイルが配置されている Amazon S3 または GCS ディレクトリにテーブル スキーマ ファイルを含めない場合、データのインポート時にTiDB Cloudは対応するテーブルを作成しません。

     各テーブル スキーマ ファイルは${db_name}.${table_name}-schema.sql形式であり、 CREATE TABLE DDL ステートメントが含まれている必要があります。データをインポートすると、このファイルを使用して、 TiDB Cloud は${db_name}データベースに${db_table}テーブルを作成します。

     たとえば、次のステートメントを含むmydb.mytable-schema.sqlファイルを作成すると、データをインポートすると、 TiDB Cloud はmydbデータベースにmytableテーブルを作成します。

     CREATE TABLE mytable (
     ID INT,
     REGION VARCHAR(20),
     COUNT INT );
     

     注記：

     各ファイルには${db_name}.${table_name}-schema.sqlつの DDL ステートメントのみを含める必要があります。ファイルに複数の DDL ステートメントが含まれている場合、最初の DDL ステートメントのみが有効になります。

ステップ 3. クロスアカウント アクセスを構成する

TiDB Cloud がAmazon S3 または GCS バケット内の CSV ファイルにアクセスできるようにするには、次のいずれかを実行します。

• CSV ファイルが Amazon S3 にある場合、 Amazon S3 アクセスを設定する .

  AWS アクセス キーまたはロール ARN を使用してバケットにアクセスできます。完了したら、アクセス キー (アクセス キー ID とシークレット アクセス キーを含む) またはロール ARN 値をメモします ( ステップ4で必要になります)。

• CSV ファイルが GCS にある場合は、 GCS アクセスを構成する 。

ステップ 4. CSV ファイルをTiDB Cloudにインポートする

CSV ファイルをTiDB Cloudにインポートするには、次の手順を実行します。

1. ターゲットクラスターのインポートページを開きます。

   1. TiDB Cloudコンソールにログインし、プロジェクトのクラスターページに移動します。

      ヒント：

      複数のプロジェクトがある場合は、左下隅の をクリックして、別のプロジェクトに切り替えます。

   2. ターゲット クラスターの名前をクリックして概要ページに移動し、左側のナビゲーション ペインで[インポート]をクリックします。

2. インポートページで:

   • TiDB 専用クラスターの場合は、右上隅にある「データのインポート」をクリックします。
   • TiDB サーバーレス クラスターの場合は、アップロード領域の上にある[S3 からデータをインポート]リンクをクリックします。

3. ソース CSV ファイルに次の情報を指定します。

   クラスターが配置されている場所に応じて、Amazon S3 または GCS からデータをインポートすることを選択できます。

   • Amazon S3
   • GCS

   • 場所: Amazon S3を選択します。

   • データ形式: CSVを選択します。 CSV 構成を編集する必要がある場合は、 「CSV 構成の編集」をクリックして CSV 固有の構成を更新します。詳細については、 データをインポートするための CSV 構成を参照してください。

     注記：

     区切り文字と区切り文字の設定には、英数字と特定の特殊文字の両方を使用できます。サポートされている特殊文字には、 \t 、 \b 、 \n 、 \r 、 \f 、および\u0001が含まれます。

   • バケット URI : CSV ファイルが配置されているバケット URI を選択します。 URI の末尾に/含める必要があることに注意してください (例: s3://sampledate/ingest/ )。

   • バケット アクセス(このフィールドは AWS S3 でのみ表示されます): AWS アクセス キーまたは AWS ロール ARN を使用してバケットにアクセスできます。詳細については、 Amazon S3 アクセスを構成するを参照してください。

     • AWS アクセス キー: AWS アクセス キー ID と AWS シークレット アクセス キーを入力します。
     • AWS ロール ARN : AWS ロール ARN 値を入力します。

   • 場所: Google Cloudを使用します。

   • データ形式: CSVを選択します。 CSV 構成を編集する必要がある場合は、 「CSV 構成の編集」をクリックして CSV 固有の構成を更新します。詳細については、 データをインポートするための CSV 構成を参照してください。

     注記：

     区切り文字と区切り文字の設定には、英数字と特定の特殊文字の両方を使用できます。サポートされている特殊文字には、 \t 、 \b 、 \n 、 \r 、 \f 、および\u0001が含まれます。

   • バケット gsutil URI : CSV ファイルが配置されているバケット gsutil URI を選択します。 URI の末尾に/含める必要があることに注意してください (例: gs://sampledate/ingest/ )。

   • バケット アクセス: GCS IAMロールを使用してバケットにアクセスできます。詳細については、 GCS アクセスを構成するを参照してください。

4. 事前に作成したテーブルにインポートするか、ソースからスキーマとデータをインポートするかを選択できます。

   • 事前に作成されたテーブルにインポートすると、事前に TiDB にテーブルを作成し、データをインポートするテーブルを選択できます。この場合、インポートするテーブルを最大 1000 個選択できます。テーブルを作成するには、左側のナビゲーション ウィンドウで[Chat2Query]をクリックします。 Chat2Query の使用方法の詳細については、 AI を活用した Chat2Query でデータを探索するを参照してください。
   • S3 からスキーマとデータをインポート(このフィールドは AWS S3 でのみ表示されます) により、S3 に保存されている対応するデータとともにテーブルを作成する SQL スクリプトを TiDB に直接インポートできます。
   • GCS からスキーマとデータをインポート(このフィールドは GCS でのみ表示されます) により、GCS に保存されている対応するデータとともにテーブルを作成する SQL スクリプトを TiDB に直接インポートできます。

5. ソース ファイルが命名規則を満たしていない場合は、各ターゲット テーブルとそれに対応する CSV ファイルに対してカスタム マッピング ルールを定義できます。その後、提供されたカスタム マッピング ルールを使用してデータ ソース ファイルが再スキャンされます。マッピングを変更するには、 「詳細設定」に移動し、 「マッピング設定」をクリックします。マッピング設定は、事前に作成されたテーブルにインポートすることを選択した場合にのみ使用できることに注意してください。

   • ターゲット データベース: 選択したターゲット データベースの名前を入力します。

   • ターゲット テーブル: 選択したターゲット テーブルの名前を入力します。このフィールドは 1 つの特定のテーブル名のみを受け入れるため、ワイルドカードはサポートされていないことに注意してください。

   • ソース ファイルの URI と名前: ソース ファイルの URI と名前を次の形式で入力します。 s3://[bucket_name]/[data_source_folder]/[file_name].csv .たとえば、 s3://sampledate/ingest/TableName.01.csv 。ワイルドカードを使用してソース ファイルと一致させることもできます。詳細については、 マッピング設定を参照してください。

6. [インポートの開始]をクリックします。

7. インポートの進行状況にCompletedと表示されたら、インポートされたテーブルを確認します。

インポート タスクを実行するときに、サポートされていない変換または無効な変換が検出された場合、 TiDB Cloudはインポート ジョブを自動的に終了し、インポート エラーを報告します。

インポート エラーが発生した場合は、次の手順を実行します。

1. 部分的にインポートされたテーブルを削除します。
2. テーブルスキーマファイルを確認してください。エラーがある場合は、テーブル スキーマ ファイルを修正します。
3. CSVファイルのデータ型を確認してください。
4. インポートタスクを再試行してください。

マッピング設定

ソース ファイルが命名規則を満たしていない場合は、各ターゲット テーブルとそれに対応する CSV ファイルに対してカスタム マッピング ルールを定義できます。その後、提供されたカスタム マッピング ルールを使用してデータ ソース ファイルが再スキャンされます。マッピングを変更するには、 「詳細設定」に移動し、 「マッピング設定」をクリックします。 [マッピング設定] は、 [事前作成されたテーブルにインポート] を選択した場合にのみ使用できることに注意してください。

[ソース ファイルの URI と名前] にソース ファイルの URI と名前を入力する場合は、 s3://[bucket_name]/[data_source_folder]/[file_name].csvの形式であることを確認してください。たとえば、 s3://sampledate/ingest/TableName.01.csv 。

ワイルドカードを使用してソース ファイルと一致させることもできます。例えば：

• s3://[bucket_name]/[data_source_folder]/my-data?.csv : そのフォルダー内のmy-dataで始まり、その後に 1 文字が続くすべての CSV ファイル ( my-data1.csvやmy-data2.csvなど) が同じターゲット テーブルにインポートされます。

• s3://[bucket_name]/[data_source_folder]/my-data*.csv : my-dataで始まるフォルダー内のすべての CSV ファイルが同じターゲット テーブルにインポートされます。

?と*のみがサポートされることに注意してください。

注記：

URI にはデータ ソース フォルダーが含まれている必要があります。

トラブルシューティング

データインポート中の警告を解決する

[インポートの開始]をクリックした後、 can't find the corresponding source filesなどの警告メッセージが表示された場合は、正しいソース ファイルを提供するか、 データインポートの命名規則に従って既存のファイルの名前を変更するか、詳細設定を使用して変更することで問題を解決します。

これらの問題を解決した後、データを再度インポートする必要があります。

インポートされたテーブルの行がゼロ

インポートの進行状況にCompletedと表示されたら、インポートされたテーブルを確認します。行数がゼロの場合は、入力したバケット URI に一致するデータ ファイルがなかったことを意味します。この場合、正しいソース ファイルを提供するか、 データインポートの命名規則に従って既存のファイルの名前を変更するか、または詳細設定を使用して変更を加えることで、この問題を解決します。その後、それらのテーブルを再度インポートします。