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

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

制限事項

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

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

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

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

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

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

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

   • 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 ステートメントが含まれている場合、最初のステートメントのみが有効になります。

ステップ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にインポートするには、次の手順を実行します。

• Amazon S3
• Google Cloud

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

インポート エラーが発生した場合は、次の操作を行ってください。

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

トラブルシューティング

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

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

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

インポートされたテーブルに行が 0 行あります

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