クラウドストレージからTiDB Cloud DedicatedにApache Parquetファイルをインポートする

このドキュメントでは、Amazon Simple Storage Service (Amazon S3)、Google Cloud Storage (GCS)、またはAzure Blob StorageからTiDB Cloud DedicatedにApache Parquetファイルをインポートする方法について説明します。Parquetファイルは、非圧縮またはGoogle スナッピーで圧縮された状態でインポートできます。その他のParquet圧縮コーデックはサポートされていません。

制限事項

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

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

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

注記：

現在、 TiDB Cloud は、以下のいずれかのデータ型を含む Parquet ファイルのインポートをサポートしていません。インポートする Parquet ファイルにこれらのデータ型が含まれている場合は、まずサポートされているデータ型 （例： STRING ）を使用して Parquet ファイルを再生成する必要があります。あるいは、AWS Glue などのサービスを使用してデータ型を簡単に変換することもできます。

• LIST
• NEST STRUCT
• BOOL
• ARRAY
• MAP

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

   TiDB Cloudは非常に大きなParquetファイルのインポートをサポートしていますが、256MB程度の複数の入力ファイルで最適なパフォーマンスを発揮します。これは、 TiDB Cloudが複数のファイルを並列処理できるため、インポート速度が大幅に向上するからです。

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

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

   • 1つのテーブルのデータが複数のParquetファイルに分割されている場合は、これらのParquetファイルに数値サフィックスを追加します。例： ${db_name}.${table_name}.000001.parquetと${db_name}.${table_name}.000002.parquet 。数値サフィックスは連続していなくても構いませんが、昇順である必要があります。また、すべてのサフィックスの長さを揃えるため、数値の前にゼロを追加する必要があります。

   注記：

   • 場合によっては、前述のルールに従って Parquet ファイル名を更新できない場合 (たとえば、Parquet ファイル リンクが他のプログラムでも使用されている場合) は、ファイル名を変更せずに、 ステップ4のマッピング設定を使用してソース データを単一のターゲット テーブルにインポートできます。
   • Snappy 圧縮ファイルは公式Snappyフォーマットである必要があります。その他の Snappy 圧縮形式はサポートされていません。

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

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

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

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

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

     Parquetファイルがステップ1の命名規則に従っている場合、データベーススキーマファイルはデータのインポートに必須ではありません。そうでない場合は、データベーススキーマファイルは必須です。

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

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

     CREATE DATABASE mydb;
     

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

     Parquet ファイルが配置されている Amazon S3、GCS、または Azure Blob Storage ディレクトリにテーブル スキーマ ファイルを含めない場合、 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ファイルには1つのDDL文のみを含めることができます。ファイルに複数のDDL文が含まれている場合、最初の文のみが有効になります。

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

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

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

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

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

• Parquet ファイルが Azure Blob Storage にある場合は、 Azure Blob Storage アクセスを構成する 。

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

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

インポートタスクの実行中に、サポートされていない変換や無効な変換が検出された場合、 TiDB Cloud はインポートジョブを自動的に終了し、インポートエラーを報告します。詳細は「ステータス」フィールドで確認できます。

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

1. 部分的にインポートされたテーブルを削除します。

2. テーブルスキーマファイルを確認してください。エラーがある場合は、テーブルスキーマファイルを修正してください。

3. Parquet ファイル内のデータ型を確認します。

   Parquet ファイルにサポートされていないデータ型 (たとえば、 NEST STRUCT 、 ARRAY 、 MAP ) が含まれている場合は、 サポートされているデータ型 (たとえば、 STRING ) を使用して Parquet ファイルを再生成する必要があります。

4. インポートタスクをもう一度試してください。

サポートされているデータ型

次の表は、TiDB Cloudにインポートできるサポートされている Parquet データ型を示しています。

トラブルシューティング

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

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

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

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

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