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

非圧縮および Snappy 圧縮アパッチ寄木細工形式のデータファイルの両方をTiDB Cloudにインポートできます。このドキュメントでは、Amazon Simple Storage Service (Amazon S3) または Google Cloud Storage (GCS) からTiDB Cloudに Parquet ファイルをインポートする方法について説明します。

注記：
TiDB Cloud は、空のテーブルへの Parquet ファイルのインポートのみをサポートします。すでにデータが含まれている既存のテーブルにデータをインポートするには、このドキュメントに従ってTiDB Cloudを使用して一時的な空のテーブルにデータをインポートし、その後INSERT SELECTステートメントを使用してデータをターゲットの既存のテーブルにコピーします。
TiDB 専用クラスターにチェンジフィードがある場合、現在のデータインポート機能は物理インポートモードを使用するため、データをクラスターにインポートできません ([**データのインポート]**ボタンが無効になります)。このモードでは、インポートされたデータは変更ログを生成しないため、変更フィードはインポートされたデータを検出できません。
TiDB 専用クラスターのみが GCS からの Parquet ファイルのインポートをサポートしています。
Snappy 圧縮ファイルは公式の Snappy フォーマットに存在する必要があります。 Snappy 圧縮の他のバリアントはサポートされていません。

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

注記：
現在、 TiDB Cloud は、次のデータタイプのいずれかを含む Parquet ファイルのインポートをサポートしていません。インポートする Parquet ファイルにそのようなデータ型が含まれている場合は、最初にサポートされているデータ型 (たとえば、 STRING ) を使用して Parquet ファイルを再生成する必要があります。あるいは、AWS Glue などのサービスを使用して、データ型を簡単に変換することもできます。
LIST
NEST STRUCT
BOOL
ARRAY
MAP

Parquet ファイルが 256 MB より大きい場合は、ファイルを 256 MB 程度の小さなファイルに分割することを検討してください。
TiDB Cloudは非常に大きな Parquet ファイルのインポートをサポートしていますが、サイズが約 256 MB の複数の入力ファイルで最適なパフォーマンスを発揮します。これは、 TiDB Cloud が複数のファイルを並行して処理できるため、インポート速度が大幅に向上する可能性があります。
Parquet ファイルに次のように名前を付けます。
- Parquet ファイルにテーブル全体のすべてのデータが含まれている場合は、ファイルに${db_name}.${table_name}.parquet形式で名前を付けます。これは、データをインポートするときに${db_name}.${table_name}テーブルにマップされます。
- 1 つのテーブルのデータが複数の Parquet ファイルに分割されている場合は、これらの Parquet ファイルに数値の接尾辞を追加します。たとえば、 ${db_name}.${table_name}.000001.parquetと${db_name}.${table_name}.000002.parquetです。数値接尾辞は連続していなくてもかまいませんが、昇順である必要があります。また、すべての接尾辞が同じ長さになるように、数値の前にゼロを追加する必要があります。
注記：
場合によっては、前述のルールに従って Parquet ファイル名を更新できない場合 (たとえば、Parquet ファイルリンクが他のプログラムでも使用されている場合)、ファイル名を変更しないで、ステップ4のマッピング設定を使用してソースデータをインポートできます。単一のターゲットテーブルに。

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

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

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

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

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

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

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

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

CREATE DATABASE mydb;

ソースデータのテーブルスキーマファイルを作成します。
Parquet ファイルが配置されている 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 バケット内の Parquet ファイルにアクセスできるようにするには、次のいずれかを実行します。

Parquet ファイルが Amazon S3 にある場合、 Amazon S3 アクセスを設定する .
AWS アクセスキーまたはロール ARN を使用してバケットにアクセスできます。完了したら、アクセスキー (アクセスキー ID とシークレットアクセスキーを含む) またはロール ARN 値をメモします ( ステップ4で必要になります)。
Parquet ファイルが GCS にある場合は、 GCS アクセスを構成する。

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

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

ターゲットクラスターのインポートページを開きます。
1. TiDB Cloudコンソールにログインし、プロジェクトのクラスターページに移動します。
  ヒント：
  複数のプロジェクトがある場合は、左下隅のをクリックして、別のプロジェクトに切り替えます。
2. ターゲットクラスターの名前をクリックして概要ページに移動し、左側のナビゲーションペインで[インポート]をクリックします。
インポートページで:
- TiDB 専用クラスターの場合は、右上隅にある「データのインポート」をクリックします。
- TiDB サーバーレスクラスターの場合は、アップロード領域の上にある[S3 からデータをインポート]リンクをクリックします。
ソース Parquet ファイルについて次の情報を指定します。
クラスターが配置されている場所に応じて、Amazon S3 または GCS からデータをインポートすることを選択できます。
- Amazon S3
- GCS
- 場所: Amazon S3を選択します。
- データ形式: 「Parquet」を選択します。
- バケット URI : Parquet ファイルが配置されているバケット URI を選択します。 URI の末尾に/含める必要があることに注意してください (例: s3://sampledate/ingest/ )。
- バケットアクセス(このフィールドは AWS S3 でのみ表示されます): AWS アクセスキーまたはロール ARN を使用してバケットにアクセスできます。詳細については、 Amazon S3 アクセスを構成するを参照してください。
  - AWS アクセスキー: AWS アクセスキー ID と AWS シークレットアクセスキーを入力します。
  - AWS ロール ARN : ロール ARN 値を入力します。
- 場所: Google Cloudを使用します。
- データ形式: 「Parquet」を選択します。
- バケット gsutil URI : Parquet ファイルが配置されているバケット URI を選択します。 URI の末尾に/含める必要があることに注意してください (例: gs://sampledate/ingest/ )。
- バケットアクセス: GCS IAMロールを使用してバケットにアクセスできます。詳細については、 GCS アクセスを構成するを参照してください。
事前に作成したテーブルにインポートするか、ソースからスキーマとデータをインポートするかを選択できます。
- 事前に作成されたテーブルにインポートすると、事前に TiDB にテーブルを作成し、データをインポートするテーブルを選択できます。この場合、インポートするテーブルを最大 1000 個選択できます。左側のナビゲーションペインでChat2Query をクリックしてテーブルを作成できます。 Chat2Query の使用方法の詳細については、 AI を活用した Chat2Query でデータを探索するを参照してください。
- S3 からスキーマとデータをインポート(このフィールドは AWS S3 でのみ表示されます) により、テーブルを作成するための SQL スクリプトをインポートし、S3 に保存されている対応するテーブルデータを TiDB にインポートできます。
- GCS からスキーマとデータをインポート(このフィールドは GCS でのみ表示されます) により、GCS に保存されている対応するデータとともにテーブルを作成する SQL スクリプトを TiDB に直接インポートできます。
ソースファイルが命名規則を満たしていない場合は、単一のターゲットテーブルと CSV ファイルの間にカスタムマッピングルールを指定できます。その後、提供されたカスタムマッピングルールを使用してデータソースファイルが再スキャンされます。マッピングを変更するには、 [詳細設定]をクリックし、 [マッピング設定]をクリックします。マッピング設定は、事前に作成されたテーブルへのインポートを選択した場合にのみ使用できることに注意してください**。
- ターゲットデータベース: 選択したターゲットデータベースの名前を入力します。
- ターゲットテーブル: 選択したターゲットテーブルの名前を入力します。このフィールドは 1 つの特定のテーブル名のみを受け入れるため、ワイルドカードはサポートされていないことに注意してください。
- ソースファイルの URI と名前: ソースファイルの URI と名前を次の形式で入力します。 s3://[bucket_name]/[data_source_folder]/[file_name].parquet .たとえば、 s3://sampledate/ingest/TableName.01.parquet 。ワイルドカードを使用してソースファイルと一致させることもできます。例えば：
  - s3://[bucket_name]/[data_source_folder]/my-data?.parquet : そのフォルダー内のmy-dataと 1 文字 ( my-data1.parquetやmy-data2.parquetなど) で始まるすべての Parquet ファイルが同じターゲットテーブルにインポートされます。
  - s3://[bucket_name]/[data_source_folder]/my-data*.parquet : my-dataで始まるフォルダー内のすべての Parquet ファイルが同じターゲットテーブルにインポートされます。
  ?と*のみがサポートされることに注意してください。
  注記：
  URI にはデータソースフォルダーが含まれている必要があります。
[インポートの開始]をクリックします。
インポートの進行状況にCompletedと表示されたら、インポートされたテーブルを確認します。

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

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

部分的にインポートされたテーブルを削除します。
テーブルスキーマファイルを確認してください。エラーがある場合は、テーブルスキーマファイルを修正します。
Parquet ファイルのデータ型を確認してください。
Parquet ファイルにサポートされていないデータ型 (たとえば、 NEST STRUCT 、 ARRAY 、またはMAP ) が含まれている場合は、サポートされているデータ型 (たとえば、 STRING ) を使用して Parquet ファイルを再生成する必要があります。
インポートタスクを再試行してください。

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

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

寄木細工のプリミティブタイプ	寄木細工の論理タイプ	TiDB または MySQL の型
ダブル	ダブル	ダブル浮く
FIXED_LEN_BYTE_ARRAY(9)	DECIMAL(20,0)	BIGINT 署名なし
FIXED_LEN_BYTE_ARRAY(N)	DECIMAL(p,s)	10進数数値
INT32	DECIMAL(p,s)	10進数数値
INT32	該当なし	INT ミディアムミント年
INT64	DECIMAL(p,s)	10進数数値
INT64	該当なし	BIGINT INT 符号なしミディアムミント未署名
INT64	TIMESTAMP_MICROS	日付時刻タイムスタンプ
バイト配列	該当なし	バイナリ少し BLOB チャーラインストリングロングブロブミディアムブロブ複数行の文字列タイニーブロブヴァービナリー
バイト配列	弦	ENUM 日付 10進数幾何学模様ジオメトリコレクション JSON 長文メディアテキストマルチポイントマルチポリゴン数値ポイントポリゴンセット TEXT 時間小さなテキスト VARCHAR
スモールント	該当なし	INT32
小さな署名なし	該当なし	INT32
タイイント	該当なし	INT32
TINYINT 署名なし	該当なし	INT32

トラブルシューティング

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

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

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

インポートされたテーブルの行がゼロ

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