Amazon S3、GCS、または Azure Blob ストレージから CSV ファイルをTiDB Cloud Serverless にインポートする
このドキュメントでは、Amazon Simple Storage Service (Amazon S3)、Google Cloud Storage (GCS)、または Azure Blob Storage からTiDB Cloud Serverless に CSV ファイルをインポートする方法について説明します。
制限事項
- データの一貫性を確保するために、 TiDB Cloud Serverless では、CSV ファイルを空のテーブルにのみインポートできます。すでにデータが含まれている既存のテーブルにデータをインポートするには、このドキュメントに従ってTiDB Cloud Serverless を使用して一時的な空のテーブルにデータをインポートし、
INSERT SELECT
ステートメントを使用してデータを対象の既存のテーブルにコピーします。
ステップ1. CSVファイルを準備する
CSV ファイルが 256 MB より大きい場合は、サイズがそれぞれ約 256 MB の小さなファイルに分割することを検討してください。
TiDB Cloud Serverless は非常に大きな CSV ファイルのインポートをサポートしていますが、サイズが約 256 MB の複数の入力ファイルで最適なパフォーマンスを発揮します。これは、 TiDB Cloud Serverless が複数のファイルを並行して処理できるため、インポート速度が大幅に向上するためです。
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 Serverless は、
.gzip
、.gz
、.zstd
、.zst
、.snappy
形式の圧縮ファイルのインポートをサポートしています。圧縮された CSV ファイルをインポートする場合は、ファイルに${db_name}.${table_name}.${suffix}.csv.${compress}
形式で名前を付けます。13${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 Serverless にデータをインポートする前に、次のいずれかの方法でテーブル スキーマを作成する必要があります。
方法 1: TiDB Cloud Serverless で、ソース データのターゲット データベースとテーブルを作成します。
方法 2: CSV ファイルが保存されている Amazon S3、GCS、または Azure Blob Storage ディレクトリで、次のようにソース データのターゲット テーブル スキーマ ファイルを作成します。
ソース データのデータベース スキーマ ファイルを作成します。
CSV ファイルがステップ1の命名規則に従っている場合、データのインポートではデータベース スキーマ ファイルはオプションです。それ以外の場合は、データベース スキーマ ファイルは必須です。
各データベース スキーマ ファイルは
${db_name}-schema-create.sql
形式で、CREATE DATABASE
DDL ステートメントを含んでいる必要があります。このファイルを使用して、 TiDB Cloud Serverless は、データをインポートするときにデータを格納する${db_name}
データベースを作成します。たとえば、次のステートメントを含む
mydb-scehma-create.sql
ファイルを作成すると、 TiDB Cloud Serverless はデータをインポートするときにmydb
データベースを作成します。CREATE DATABASE mydb;ソース データのテーブル スキーマ ファイルを作成します。
CSV ファイルが配置されている Amazon S3、GCS、または Azure Blob Storage ディレクトリにテーブル スキーマ ファイルを含めない場合、 TiDB Cloud Serverless はデータをインポートするときに対応するテーブルを作成しません。
各テーブル スキーマ ファイルは
${db_name}.${table_name}-schema.sql
形式で、CREATE TABLE
DDL ステートメントが含まれている必要があります。このファイルを使用すると、 TiDB Cloud Serverless はデータをインポートするときに${db_name}
データベースに${db_table}
テーブルを作成します。たとえば、次のステートメントを含む
mydb.mytable-schema.sql
ファイルを作成すると、 TiDB Cloud Serverless はデータをインポートするときにmydb
データベースにmytable
テーブルを作成します。CREATE TABLE mytable ( ID INT, REGION VARCHAR(20), COUNT INT );注記:
${db_name}.${table_name}-schema.sql
ファイルには 1 つの DDL ステートメントのみを含める必要があります。ファイルに複数の DDL ステートメントが含まれている場合、最初のステートメントのみが有効になります。
ステップ3. クロスアカウントアクセスを構成する
TiDB Cloud Serverless が Amazon S3、GCS、または Azure Blob Storage バケット内の CSV ファイルにアクセスできるようにするには、次のいずれかを実行します。
CSV ファイルが Amazon S3 にある場合は、 TiDB Cloud Serverless の外部storageアクセスを構成する 。
バケットにアクセスするには、AWS アクセスキーまたはロール ARN のいずれかを使用できます。完了したら、アクセスキー (アクセスキー ID とシークレットアクセスキーを含む) またはロール ARN 値をメモしてください。これらはステップ4で必要になります。
CSV ファイルが GCS にある場合は、 TiDB Cloud Serverless の外部storageアクセスを構成する 。
CSV ファイルが Azure Blob Storage にある場合は、 TiDB Cloud Serverless の外部storageアクセスを構成する 。
ステップ4. CSVファイルをTiDB Cloud Serverlessにインポートする
CSV ファイルをTiDB Cloud Serverless にインポートするには、次の手順を実行します。
- Amazon S3
- Google Cloud
- Azure Blob Storage
ターゲット クラスターのインポートページを開きます。
TiDB Cloudコンソールにログインし、プロジェクトのクラスターページに移動します。
ヒント:
複数のプロジェクトがある場合は、
左下隅にある をクリックして、別のプロジェクトに切り替えます。 ターゲット クラスターの名前をクリックして概要ページに移動し、左側のナビゲーション ペインで[インポート]をクリックします。
「Cloud Storage からデータをインポート」を選択し、 「Amazon S3」をクリックします。
「Amazon S3 からのデータのインポート」ページで、ソース CSV ファイルについて次の情報を入力します。
- インポート ファイル数: 必要に応じて1 つのファイルまたは複数のファイルを選択します。
- 含まれるスキーマ ファイル: このフィールドは、複数のファイルをインポートする場合にのみ表示されます。ソース フォルダーにターゲット テーブル スキーマが含まれている場合は、 [はい] を選択します。それ以外の場合は、 [いいえ]を選択します。
- データ形式: CSVを選択します。
- ファイルURIまたはフォルダーURI :
- 1 つのファイルをインポートする場合は、ソース ファイルの URI と名前を次の形式で入力します
s3://[bucket_name]/[data_source_folder]/[file_name].csv
。たとえば、s3://sampledata/ingest/TableName.01.csv
。 - 複数のファイルをインポートする場合は、ソース ファイルの URI と名前を次の形式で入力します
s3://[bucket_name]/[data_source_folder]/
。たとえば、s3://sampledata/ingest/
。
- 1 つのファイルをインポートする場合は、ソース ファイルの URI と名前を次の形式で入力します
- バケットアクセス: バケットにアクセスするには、AWS ロール ARN または AWS アクセスキーのいずれかを使用できます。詳細については、 Amazon S3 アクセスを構成する参照してください。
- AWS ロール ARN : AWS ロール ARN 値を入力します。
- AWS アクセスキー: AWS アクセスキー ID と AWS シークレットアクセスキーを入力します。
[接続]をクリックします。
[宛先]セクションで、ターゲット データベースとテーブルを選択します。
複数のファイルをインポートする場合は、 [詳細設定] > [マッピング設定]を使用して、各ターゲット テーブルとそれに対応する CSV ファイルのカスタム マッピング ルールを定義できます。その後、提供されたカスタム マッピング ルールを使用してデータ ソース ファイルが再スキャンされます。
ソース ファイルの URI と名前を[ソース ファイルの URI と名前]に入力するときは、次の形式
s3://[bucket_name]/[data_source_folder]/[file_name].csv
になっていることを確認してください。たとえば、s3://sampledata/ingest/TableName.01.csv
。ソース ファイルを一致させるためにワイルドカードを使用することもできます。例:
s3://[bucket_name]/[data_source_folder]/my-data?.csv
: そのフォルダー内のmy-data
で始まり、その後に 1 文字 (my-data1.csv
やmy-data2.csv
など) が続くすべての CSV ファイルが同じターゲット テーブルにインポートされます。s3://[bucket_name]/[data_source_folder]/my-data*.csv
: フォルダー内のmy-data
で始まるすべての CSV ファイルが同じターゲット テーブルにインポートされます。
サポートされているのは
?
と*
のみであることに注意してください。注記:
URI にはデータ ソース フォルダーが含まれている必要があります。
[インポートの開始]をクリックします。
インポートの進行状況が「完了」と表示されたら、インポートされたテーブルを確認します。
ターゲット クラスターのインポートページを開きます。
TiDB Cloudコンソールにログインし、プロジェクトのクラスターページに移動します。
ヒント:
複数のプロジェクトがある場合は、
左下隅にある をクリックして、別のプロジェクトに切り替えます。 ターゲット クラスターの名前をクリックして概要ページに移動し、左側のナビゲーション ペインで[インポート]をクリックします。
[Cloud Storage からデータをインポート]を選択し、 [Google Cloud Storage]をクリックします。
「Google Cloud Storage からデータをインポート」ページで、ソース CSV ファイルに関する次の情報を入力します。
- インポート ファイル数: 必要に応じて1 つのファイルまたは複数のファイルを選択します。
- 含まれるスキーマ ファイル: このフィールドは、複数のファイルをインポートする場合にのみ表示されます。ソース フォルダーにターゲット テーブル スキーマが含まれている場合は、 [はい] を選択します。それ以外の場合は、 [いいえ]を選択します。
- データ形式: CSVを選択します。
- ファイルURIまたはフォルダーURI :
- 1 つのファイルをインポートする場合は、ソース ファイルの URI と名前を次の形式で入力します
[gcs|gs]://[bucket_name]/[data_source_folder]/[file_name].csv
。たとえば、[gcs|gs]://sampledata/ingest/TableName.01.csv
。 - 複数のファイルをインポートする場合は、ソース ファイルの URI と名前を次の形式で入力します
[gcs|gs]://[bucket_name]/[data_source_folder]/
。たとえば、[gcs|gs]://sampledata/ingest/
。
- 1 つのファイルをインポートする場合は、ソース ファイルの URI と名前を次の形式で入力します
- バケット アクセス: サービス アカウント キーを使用してバケットにアクセスできます。詳細については、 GCS アクセスを構成する参照してください。
[接続]をクリックします。
[宛先]セクションで、ターゲット データベースとテーブルを選択します。
複数のファイルをインポートする場合は、 [詳細設定] > [マッピング設定]を使用して、各ターゲット テーブルとそれに対応する CSV ファイルのカスタム マッピング ルールを定義できます。その後、提供されたカスタム マッピング ルールを使用してデータ ソース ファイルが再スキャンされます。
ソース ファイルの URI と名前を[ソース ファイルの URI と名前]に入力するときは、次の形式
[gcs|gs]://[bucket_name]/[data_source_folder]/[file_name].csv
になっていることを確認してください。たとえば、[gcs|gs]://sampledata/ingest/TableName.01.csv
。ソース ファイルを一致させるためにワイルドカードを使用することもできます。例:
[gcs|gs]://[bucket_name]/[data_source_folder]/my-data?.csv
: そのフォルダー内のmy-data
で始まり、その後に 1 文字 (my-data1.csv
やmy-data2.csv
など) が続くすべての CSV ファイルが同じターゲット テーブルにインポートされます。[gcs|gs]://[bucket_name]/[data_source_folder]/my-data*.csv
: フォルダー内のmy-data
で始まるすべての CSV ファイルが同じターゲット テーブルにインポートされます。
サポートされているのは
?
と*
のみであることに注意してください。注記:
URI にはデータ ソース フォルダーが含まれている必要があります。
[インポートの開始]をクリックします。
インポートの進行状況が「完了」と表示されたら、インポートされたテーブルを確認します。
ターゲット クラスターのインポートページを開きます。
TiDB Cloudコンソールにログインし、プロジェクトのクラスターページに移動します。
ヒント:
複数のプロジェクトがある場合は、
左下隅にある をクリックして、別のプロジェクトに切り替えます。 ターゲット クラスターの名前をクリックして概要ページに移動し、左側のナビゲーション ペインで[インポート]をクリックします。
[Cloud Storage からデータをインポート]を選択し、 [Azure Blob Storage]をクリックします。
[Azure Blob Storage からのデータのインポート]ページで、ソース CSV ファイルに関する次の情報を入力します。
- インポート ファイル数: 必要に応じて1 つのファイルまたは複数のファイルを選択します。
- 含まれるスキーマ ファイル: このフィールドは、複数のファイルをインポートする場合にのみ表示されます。ソース フォルダーにターゲット テーブル スキーマが含まれている場合は、 [はい] を選択します。それ以外の場合は、 [いいえ]を選択します。
- データ形式: CSVを選択します。
- ファイルURIまたはフォルダーURI :
- 1 つのファイルをインポートする場合は、ソース ファイルの URI と名前を次の形式で入力します
[azure|https]://[bucket_name]/[data_source_folder]/[file_name].csv
。たとえば、[azure|https]://sampledata/ingest/TableName.01.csv
。 - 複数のファイルをインポートする場合は、ソース ファイルの URI と名前を次の形式で入力します
[azure|https]://[bucket_name]/[data_source_folder]/
。たとえば、[azure|https]://sampledata/ingest/
。
- 1 つのファイルをインポートする場合は、ソース ファイルの URI と名前を次の形式で入力します
- バケット アクセス: 共有アクセス署名 (SAS) トークンを使用してバケットにアクセスできます。詳細については、 Azure Blob Storage アクセスを構成する参照してください。
[接続]をクリックします。
[宛先]セクションで、ターゲット データベースとテーブルを選択します。
複数のファイルをインポートする場合は、 [詳細設定] > [マッピング設定]を使用して、各ターゲット テーブルとそれに対応する CSV ファイルのカスタム マッピング ルールを定義できます。その後、提供されたカスタム マッピング ルールを使用してデータ ソース ファイルが再スキャンされます。
ソース ファイルの URI と名前を[ソース ファイルの URI と名前]に入力するときは、次の形式
[azure|https]://[bucket_name]/[data_source_folder]/[file_name].csv
になっていることを確認してください。たとえば、[azure|https]://sampledata/ingest/TableName.01.csv
。ソース ファイルを一致させるためにワイルドカードを使用することもできます。例:
[azure|https]://[bucket_name]/[data_source_folder]/my-data?.csv
: そのフォルダー内のmy-data
で始まり、その後に 1 文字 (my-data1.csv
やmy-data2.csv
など) が続くすべての CSV ファイルが同じターゲット テーブルにインポートされます。[azure|https]://[bucket_name]/[data_source_folder]/my-data*.csv
: フォルダー内のmy-data
で始まるすべての CSV ファイルが同じターゲット テーブルにインポートされます。
サポートされているのは
?
と*
のみであることに注意してください。注記:
URI にはデータ ソース フォルダーが含まれている必要があります。
[インポートの開始]をクリックします。
インポートの進行状況が「完了」と表示されたら、インポートされたテーブルを確認します。
インポート タスクを実行するときに、サポートされていない変換や無効な変換が検出されると、 TiDB Cloud Serverless はインポート ジョブを自動的に終了し、インポート エラーを報告します。
インポート エラーが発生した場合は、次の手順を実行します。
- 部分的にインポートされたテーブルを削除します。
- テーブル スキーマ ファイルを確認します。エラーがある場合は、テーブル スキーマ ファイルを修正します。
- CSV ファイル内のデータ型を確認します。
- インポートタスクをもう一度試してください。
トラブルシューティング
データのインポート中に警告を解決する
[インポートの開始]をクリックした後、 can't find the corresponding source files
などの警告メッセージが表示された場合は、正しいソース ファイルを指定するか、 データインポートの命名規則に従って既存のファイルの名前を変更するか、詳細設定を使用して変更を加えることで解決してください。
これらの問題を解決した後、データを再度インポートする必要があります。
インポートされたテーブルに行が 0 行あります
インポートの進行状況が「完了」と表示されたら、インポートされたテーブルを確認します。行数がゼロの場合は、入力したバケット URI に一致するデータ ファイルがなかったことを意味します。この場合、正しいソース ファイルを指定するか、 データインポートの命名規則に従って既存のファイルの名前を変更するか、詳細設定を使用して変更を加えることで、この問題を解決します。その後、それらのテーブルを再度インポートします。