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 ファイルを準備する

CSV ファイルが 256 MB より大きい場合は、それぞれのサイズが 256 MB 程度の小さなファイルに分割することを検討してください。
TiDB Cloudは非常に大きな CSV ファイルのインポートをサポートしていますが、サイズが約 256 MB の複数の入力ファイルで最高のパフォーマンスを発揮します。これは、 TiDB Cloud が複数のファイルを並行して処理できるため、インポート速度が大幅に向上する可能性があります。
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 に制限することをお勧めします。
- 非圧縮ファイルの場合、場合によっては前述のルールに従って CSV ファイル名を更新できない場合 (たとえば、CSV ファイルのリンクが他のプログラムでも使用されている場合)、ファイル名を変更せずに、ステップ4のマッピング設定を使用して、ソースデータを単一のターゲットテーブルにインポートします。

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

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

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

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

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

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

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

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

CREATE DATABASE mydb;

ソースデータのテーブルスキーマファイルを作成します。
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. TiDB Cloudコンソールにログインし、プロジェクトのクラスターページに移動します。
  ヒント：
  複数のプロジェクトがある場合は、左下隅のをクリックして、別のプロジェクトに切り替えます。
2. ターゲットクラスターの名前をクリックして概要ページに移動し、左側のナビゲーションペインで[インポート]をクリックします。
インポートページで:
- TiDB 専用クラスターの場合は、右上隅にある「データのインポート」をクリックします。
- TiDB サーバーレスクラスターの場合は、アップロード領域の上にある[S3 からデータをインポート]リンクをクリックします。
ソース CSV ファイルに次の情報を指定します。
- 場所: 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 値を入力します。
事前に作成されたテーブルにインポートするか、 S3 からスキーマとデータをインポートするかを選択できます。
- 事前に作成されたテーブルにインポートを使用すると、事前に TiDB にテーブルを作成し、データをインポートするテーブルを選択できます。この場合、インポートするテーブルを最大 1000 個選択できます。テーブルを作成するには、左側のナビゲーションペインで[Chat2Qury]をクリックします。 Chat2Qury の使用方法の詳細については、 AI を活用した Chat2Query でデータを探索するを参照してください。
- S3 からスキーマとデータをインポートすると、テーブルを作成する SQL スクリプトと、S3 に保存されている対応するデータを TiDB に直接インポートできます。
ソースファイルが命名規則を満たしていない場合は、各ターゲットテーブルとそれに対応する CSV ファイルに対してカスタムマッピングルールを定義できます。その後、提供されたカスタムマッピングルールを使用してデータソースファイルが再スキャンされます。マッピングを変更するには、 「詳細設定」に移動し、 「マッピング設定」をクリックします。 [マッピング設定] は、 [事前作成されたテーブルにインポート] を選択した場合にのみ使用できることに注意してください。
- ターゲットデータベース: 選択したターゲットデータベースの名前を入力します。
- ターゲットテーブル: 選択したターゲットテーブルの名前を入力します。このフィールドは 1 つの特定のテーブル名のみを受け入れるため、ワイルドカードはサポートされていないことに注意してください。
- ソースファイルの URI と名前: ソースファイルの URI と名前を次の形式で入力します。 s3://[bucket_name]/[data_source_folder]/[file_name].csv .たとえば、 s3://sampledate/ingest/TableName.01.csv 。ワイルドカードを使用してソースファイルと一致させることもできます。詳細については、マッピング設定を参照してください。
[インポートの開始]をクリックします。
インポートの進行状況にCompletedと表示されたら、インポートされたテーブルを確認します。

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

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

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

マッピング設定

ソースファイルが命名規則を満たしていない場合は、各ターゲットテーブルとそれに対応する 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 に一致するデータファイルがなかったことを意味します。この場合、正しいソースファイルを提供するか、データインポートの命名規則に従って既存のファイルの名前を変更するか、または詳細設定を使用して変更を加えることで、この問題を解決します。その後、それらのテーブルを再度インポートします。