クラウドストレージからCSVファイルをTiDB Cloud PremiumまたはTiDB Cloud BYOCにインポートする

このドキュメントでは、Amazon Simple Storage Service（Amazon S3）からTiDB Cloud PremiumおよびTiDB Cloud BYOCインスタンスにCSVファイルをインポートする方法と、Alibaba Cloud Object Storage Service（OSS）からTiDB Cloud PremiumインスタンスにCSVファイルをインポートする方法について説明します。

制限事項

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

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

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

   TiDB Cloud Premium および TiDB Cloud BYOC は非常に大きなCSVファイルのインポートをサポートしていますが、サイズが約256 MiBの複数の入力ファイルを扱う場合に最高のパフォーマンスを発揮します。これは、TiDB Cloud Premium および TiDB Cloud BYOC が複数のファイルを並列処理できるため、インポート速度を大幅に向上できるからです。

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 Premium および TiDB Cloud BYOC は、.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のMapping Settingsを使用してソースデータを単一のターゲットテーブルにインポートできます。

ステップ2．対象テーブルのスキーマを作成する

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

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

• 方法2：CSVファイルが保存されているクラウドストレージのディレクトリに、ソースデータ用のターゲットテーブルスキーマファイルを次のように作成します。

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

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

     各データベーススキーマファイルは${db_name}-schema-create.sql形式である必要があり、CREATE DATABASE DDL文を含んでいる必要があります。このファイルを使用すると、TiDB Cloud Premium または TiDB Cloud BYOC は、データのインポート時にデータを格納するための${db_name}データベースを作成します。

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

     CREATE DATABASE mydb;
     

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

     CSVファイルが保存されているクラウドストレージのディレクトリにテーブルスキーマファイルを含めない場合、TiDB Cloud Premium または TiDB Cloud BYOC はデータのインポート時に対応するテーブルを作成しません。

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

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

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

     ノート

     ${db_name}.${table_name}-schema.sqlファイルには、単一の DDL文のみを含める必要があります。ファイルに複数の DDL文が含まれている場合、最初の文のみが有効になります。

ステップ3．アカウント間アクセスの設定

TiDB Cloud Premium または TiDB Cloud BYOC がクラウドストレージ内のCSVファイルにアクセスできるようにするには、該当するストレージプロバイダーに対してアカウント間アクセスを設定します。

• CSVファイルがAmazon S3にある場合は、TiDB Cloud Premium または TiDB Cloud BYOC インスタンスに対してAmazon S3へのアクセスを設定する。

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

• CSV ファイルが Alibaba Cloud Object Storage Service (OSS) にある場合は、 TiDB Cloud Premium インスタンスのAlibaba Cloud Object Storage Service (OSS) へのアクセスを設定する。

ステップ4．CSVファイルをインポートする

CSVファイルをTiDB Cloud Premium または TiDB Cloud BYOC にインポートするには、以下の手順に従ってください。

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

インポートエラーが発生した場合は、以下を実行してください。

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

トラブルシューティング

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

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

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

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

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