Dataflow を使用して、ストレージ内の Parquet ファイルを Lakehouse ランタイム カタログにインポートする

Dataflow ジョブビルダー ブループリントを使用すると、クラウドベースのストレージ(Cloud Storage、Amazon S3、Azure Blob Storage)から既存の Apache Parquet ファイルをボーダーレス Lakehouse の Apache Iceberg テーブルに追加できます。

このプロセスでは、IcebergAddFiles 変換を使用します。Parquet ファイルが Cloud Storage にある場合、この変換では、基盤となるデータを移動または書き換えることなく、ファイルを Lakehouse に登録します。ファイルが Amazon S3 などの外部ストレージ システムにある場合は、Lakehouse を介してクエリを高速化するために Cloud Storage にコピーされ、登録されます。

次の接続の詳細を使用して、クラウドベースのストレージから Lakehouse の Apache Iceberg テーブルに Parquet ファイルを追加します。

始める前に

  1. Dataflow API、BigQuery API、Lakehouse API を有効にします。

  2. リソースの作成に必要な権限を取得するには、プロジェクトに対する必要な Identity and Access Management(IAM)ロールを付与するよう管理者に依頼してください。

  3. データをインポートする Lakehouse カタログ、名前空間、テーブルを作成します。

  4. クラウドベースのストレージ バケット(Cloud Storage、Amazon S3、Azure Blob Storage)を作成し、Parquet ファイルをバケットにアップロードします。

  5. 使用しているクラウドベースのストレージ バケットが Google の Cloud Storage ではない場合は、ジョブエラーログを保存する Cloud Storage バケットを作成します。

サポートと制限事項

Dataflow を使用してクラウドベースのストレージ内の Parquet ファイルを Lakehouse にインポートする場合、次の制限があります。

  • ソースデータは Apache Parquet 形式で、Cloud Storage、Amazon S3、または Azure Blob Storage に保存されている必要があります。
  • この機能はバッチ パイプラインのみをサポートしています。

Parquet ファイルを Lakehouse にインポートする

Dataflow ジョブビルダー UI を使用して、クラウドベースのストレージから Lakehouse の Iceberg テーブルに Parquet ファイルをインポートする手順は次のとおりです。

  1. Google Cloud コンソールで、[Lakehouse] ページに移動します。

    [レイクハウス] に移動

  2. データをインポートするカタログ、名前空間、テーブルを選択します。

  3. [テーブルの詳細] ページで、 [テーブルをインポート] をクリックし、[Apache Parquet ファイルから(バッチ)] を選択します。

    Dataflow の [ジョブビルダー] ページが開きます。

  4. [ソース] セクションで、次の操作を行います。

    1. すでに作成されている CreateGlobalInput ソースエントリを開きます。

    2. [YAML ソース構成] エディタ セクションで、elements シーケンスに Parquet ファイルへのパスを 1 つ以上入力します。

      インポートの効率を向上させるには、多数のファイルを登録するときに複数のファイルセット(glob)を指定します。次に例を示します。

      reshuffle: true
      elements:
        -   gs://BUCKET_NAME/restaurant-data/2023/*.parquet
        -   gs://BUCKET_NAME/restaurant-data/2024/*.parquet
      
    3. [完了] をクリックします。

  5. [変換] セクションで、次の操作を行います。

    1. [IcebergAddFiles] 変換セクションをクリックして開きます。

    2. [Iceberg テーブル] フィールドに、名前空間とテーブル名を入力します。例: NAMESPACE .TABLE_NAME 。

    3. 省略可: [マニフェスト ファイル サイズ] フィールドに、各マニフェスト ファイルに含めるデータファイルの数を入力します。デフォルト値は 10,000 です。

    4. の [カタログ プロパティ] で、次の項目を構成します。

      1. warehouse: カタログの Cloud Storage のロケーション。例: gs://CATALOG_PATH

      2. header.x-goog-user-project: Google Cloud プロジェクト ID: PROJECT_ID。

    5. 省略可: Parquet ファイルに合わせて宛先テーブル スキーマを更新できるようにするには、[スキーマの進化] リストで 1 つ以上のオプションを選択します。詳細については、スキーマの進化を構成するをご覧ください。

    6. [完了] をクリックします。

    7. Amazon S3 または Azure Blob Storage から移行する場合は、Parquet ファイルを Cloud Storage にコピーするための追加の構成を指定する必要があります。ファイルがすでに Cloud Storage にある場合は、この操作は必要ありません。

      1. [CopyFilesToGCS] 変換セクションをクリックして開きます。

      2. gcs_file_path 構成パラメータの値を設定して、一時ファイルのコピー先となる完全修飾 Cloud Storage バケットを指定します。Lakehouse ウェアハウスで使用されているものと同じ Cloud Storage バケットを使用することをおすすめします。

      3. [完了] をクリックします。

      4. [Dataflow オプション] セクションをクリックして開きます。

      5. Parquet ファイルが Amazon S3 にある場合は、[パイプライン オプションを追加] をクリックして、Apache Beam の S3 関連のパイプライン オプションを指定します。たとえば、s3_region_name、s3_access_key_id、s3_secret_access_key と、それらに対応する値です。

      6. Parquet ファイルが Azure Blob Storage にある場合は、[パイプライン オプションを追加] をクリックして、Azure に関連する Apache Beam パイプライン オプションを指定します。たとえば、azure_connection_string、blob_service_endpoint、azure_managed_identity_client_id と、それらに対応する値です。

  6. [シンク] セクションで、次の操作を行います。

    1. [Write results] シンクをクリックして開きます。

    2. [JSON の場所] フィールドに、エラー結果を書き込む Cloud Storage の場所とファイル名を指定します。次に例を示します。

      gs://BUCKET_NAME/errors/errors.json
      
    3. [完了] をクリックします。

  7. [Dataflow オプション] セクションで、[ジョブを実行] をクリックします。

Parquet ファイルの登録に使用される Dataflow パイプラインをさらにカスタマイズする必要がある場合は、ジョブビルダー フォームまたは YAML エディタを使用します。

スキーマの進化を構成する

デフォルトでは、IcebergAddFiles 変換は宛先テーブル スキーマを変更しません。バッチジョブを使用すると、スキーマの進化を有効にして、各 Parquet ファイルのフッターを検査し、ファイルを登録する前にテーブル スキーマを更新できます。宛先テーブルが存在しない場合、ジョブは Parquet ファイルの結合スキーマからテーブルを作成します。

[IcebergAddFiles] 変換セクションでスキーマの進化を有効にするには、[スキーマの進化] リストから 1 つ以上のオプションを選択します。

  • 列を追加する: テーブルにない Parquet ファイルの列をオプションの列として追加します。
  • 列を省略可能にする: ファイルで列が省略されている場合、または列に null 値が含まれている場合に、必須のテーブル列を省略可能に変更します。
  • 列の型を拡張する: 列のデータ型を拡張します(int から long など)。

データファイルに互換性のないスキーマがある場合、パイプラインはスキーマの変更を commit したり、ファイルを登録したりせずに失敗します。たとえば、選択していない変更が必要な場合や、テーブルまたは別のファイルと競合する場合、スキーマは互換性がありません。

少なくとも 1 つのスキーマの進化オプションを選択すると、[列を省略可能にする] が選択されている場合でも、常に存在し、null 以外の列を指定できます。[必須列] を開き、[項目を追加] をクリックして、[列名] フィールドに値を入力します。ネストされたフィールドの場合は、フィールド名をピリオドで区切ります(例: address.city)。必須の列が省略されているファイルや、必須の列に null 値が含まれているファイルは、エラー出力に送信されます。

ジョブの出力を調べる

ジョブが完了したら、BigQuery でクエリを実行して、データが Iceberg テーブルに登録されていることを確認できます。

  1. Dataflow ジョブリストで、ジョブのステータスが [成功] であることを確認します。

    [ジョブ] に移動

  2. ジョブが失敗した場合やエラーが発生した場合は、Cloud Storage の JSON エラーログ ファイルで詳細を確認します。

    [バケット] に移動

  3. Google Cloud コンソールで、BigQuery の [Studio] ページに移動します。

    BigQuery に移動

  4. クエリエディタで、テーブルを検査する SQL クエリを入力します。PROJECT_ID.CATALOG.NAMESPACE.TABLE_NAME 規則を使用してクエリを実行できます。

    SELECT * FROM `PROJECT_ID.CATALOG.NAMESPACE.TABLE_NAME` LIMIT 10
    
  5. (実行)をクリックします。

  6. [クエリ結果] を確認して、データが正しく処理されたことを確認します。

次のステップ