Amazon S3 BigLake 外部テーブルを作成する

このドキュメントでは、Amazon Simple Storage Service（Amazon S3）BigLake テーブルを作成する方法について説明します。BigLake テーブルを使用すると、アクセス権の委任を使用して Amazon S3 のデータをクエリできます。アクセス委任は、BigLake テーブルへのアクセスを、基盤となるデータストアへのアクセスから切り離します。

BigQuery と Amazon S3 の間のデータフローについては、データに対してクエリを実行する際のデータフローをご覧ください。

始める前に

Amazon S3 データにアクセスするための接続があることを確認します。

必要なロール

外部テーブルを作成するために必要な権限を取得するには、データセットの BigQuery 管理者（roles/bigquery.admin）の IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

この事前定義ロールには、外部テーブルを作成するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

外部テーブルを作成するには、次の権限が必要です。

• bigquery.tables.create
• bigquery.connections.delegate

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

データセットを作成する

外部テーブルを作成する前に、サポートされているリージョンにデータセットを作成する必要があります。次のオプションのいずれかを選択します。

コンソール

1. [BigQuery] ページに移動します。

   [BigQuery] に移動

2. [エクスプローラ] ペインで、データセットを作成するプロジェクトを選択します。
3. （アクションを表示）オプションを開き、[データセットを作成] をクリックします。
4. [データセットを作成] ページで、次の詳細を指定します。
1. [データセット ID] に、データセットの一意の名前を入力します。
2. [データのロケーション] で、サポートされているリージョンを選択します。
3. 省略可: テーブルを自動的に削除するには、[テーブルの有効期限を有効にする] チェックボックスをオンにして、[デフォルトのテーブル最長存続期間] を日数で設定します。テーブルが期限切れになると、Amazon S3 のデータは削除されません。
4. デフォルトの照合を使用する場合は、[詳細オプション] セクションを開いて、[デフォルトの照合を有効にする] オプションを選択します。
5. [データセットを作成] をクリックします。

SQL

CREATE SCHEMA DDL ステートメントを使用します。次の例では、aws-us-east-1 リージョンにデータセットが作成されます。

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

   [BigQuery] に移動

2. クエリエディタで次のステートメントを入力します。

   CREATE SCHEMA mydataset
   OPTIONS (
     location = 'aws-us-east-1');

3. [実行] をクリックします。

クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。

bq

コマンドライン環境で bq mk コマンドを使用してデータセットを作成します。

bq --location=LOCATION mk \
    --dataset \
PROJECT_ID:DATASET_NAME

--project_id パラメータは、デフォルト プロジェクトをオーバーライドします。

次のように置き換えます。

• LOCATION: データセットのロケーション

  サポートされているリージョンの詳細については、ロケーションをご覧ください。 データセットを作成した後に、そのロケーションを変更することはできません。ロケーションのデフォルト値は、.bigqueryrc ファイルを使用して設定できます。

• PROJECT_ID: プロジェクト ID

• DATASET_NAME: 作成するデータセットの名前

  デフォルト プロジェクト以外のプロジェクト内にデータセットを作成するには、PROJECT_ID:DATASET_NAME の形式でそのプロジェクト ID をデータセット名に追加します。

Java

このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import com.google.cloud.bigquery.DatasetInfo;

// Sample to create a aws dataset
public class CreateDatasetAws {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    // Note: As of now location only supports aws-us-east-1
    String location = "aws-us-east-1";
    createDatasetAws(projectId, datasetName, location);
  }

  public static void createDatasetAws(String projectId, String datasetName, String location) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      DatasetInfo datasetInfo =
          DatasetInfo.newBuilder(projectId, datasetName).setLocation(location).build();

      Dataset dataset = bigquery.create(datasetInfo);
      System.out.println(
          "Aws dataset created successfully :" + dataset.getDatasetId().getDataset());
    } catch (BigQueryException e) {
      System.out.println("Aws dataset was not created. \n" + e.toString());
    }
  }
}

パーティション分割されていないデータに対して BigLake テーブルを作成する

次のオプションのいずれかを選択します。

コンソール

1. [BigQuery] ページに移動します。

   [BigQuery] に移動

2. [エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。

3. [データセット情報] セクションで、[ テーブルを作成] をクリックします。

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

   1. [テーブルの作成元] で [Amazon S3] を選択します。
   2. [S3 パスを選択] に、Amazon S3 データを指す URI を s3://BUCKET_NAME/PATH の形式で入力します。BUCKET_NAME は Amazon S3 バケットの名前に置き換えます。バケットのリージョンは、データセットのリージョンと同じにする必要があります。PATH は、エクスポート ファイルを書き込むパスで置き換えます。ワイルドカード * を使用できます。
   3. [ファイル形式] で、Amazon S3 のデータ形式を選択します。サポートされている形式は、AVRO、CSV、DELTA_LAKE、ICEBERG、JSONL、ORC、PARQUET です。

5. [送信先] セクションで、次の詳細を指定します。

   1. [データセット] で、該当するデータセットを選択します。
   2. [テーブル] フィールドにテーブルの名前を入力します。
   3. [テーブルタイプ] が [外部テーブル] に設定されていることを確認します。
   4. [接続 ID] で、プルダウンから該当する接続 ID を選択します。接続については、Amazon S3 への接続をご覧ください。

6. [スキーマ] セクションで、スキーマの自動検出を有効にするか、ソースファイルがある場合はスキーマを手動で指定できます。ソースファイルがない場合は、スキーマを手動で指定する必要があります。

   • スキーマの自動検出を有効にするには、[自動検出] オプションをオンにします。

   • 手動でスキーマを指定するには、[自動検出] オプションをオフにしておきます。[テキストとして編集] を有効にし、テーブル スキーマを JSON 配列として入力します。

7. [テーブルを作成] をクリックします。

SQL

BigLake テーブルを作成するには、WITH CONNECTION 句を指定した CREATE EXTERNAL TABLE ステートメントを使用します。

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

   [BigQuery] に移動

2. クエリエディタで次のステートメントを入力します。

   CREATE EXTERNAL TABLE DATASET_NAME.TABLE_NAME
     WITH CONNECTION `AWS_LOCATION.CONNECTION_NAME`
     OPTIONS (
       format = "DATA_FORMAT",
       uris = ["S3_URI"],
       max_staleness = STALENESS_INTERVAL,
       metadata_cache_mode = 'CACHE_MODE');

   次のように置き換えます。

   • DATASET_NAME: 作成したデータセットの名前。
   • TABLE_NAME: このテーブルに設定する名前。
   • AWS_LOCATION: Google Cloud の AWS ロケーション（例: aws-us-east-1）
   • CONNECTION_NAME: 作成した接続の名前。
   • DATA_FORMAT: サポートされている任意の BigQuery 連携形式（AVRO、CSV、DELTA_LAKE、ICEBERG、PARQUET など（プレビュー））。
   • S3_URI: Amazon S3 データを指す URI（例: s3://bucket/path）。
   • STALENESS_INTERVAL: キャッシュ内のメタデータを BigLake テーブルに対するオペレーションで使用するかどうかを指定します。また、オペレーションがキャッシュ内のメタデータを使用するためにその鮮度を指定します。メタデータ キャッシュに関する考慮事項の詳細については、メタデータ キャッシュによるパフォーマンスの向上をご覧ください。

     メタデータのキャッシュ保存を無効にするには、0 を指定します。これがデフォルトです。

     メタデータ キャッシュを有効にするには、30 分から 7 日の間で間隔リテラルの値を指定します。たとえば、4 時間の未更新間隔の場合、INTERVAL 4 HOUR を指定します。この値を指定すると、キャッシュに保存されたメタデータが過去 4 時間以内に更新されていれば、テーブルに対するオペレーションはそのメタデータを使用します。キャッシュに保存されているメタデータがそれより古い場合、オペレーションは代わりに Amazon S3 からメタデータを取得します。

   • CACHE_MODE: メタデータ キャッシュを自動的に更新するか手動で更新するかを指定します。メタデータ キャッシュに関する考慮事項の詳細については、メタデータ キャッシュによるパフォーマンスの向上をご覧ください。

     AUTOMATIC に設定すると、メタデータ キャッシュがシステムで定義された間隔（通常は 30～60 分）で更新されます。

     自身で決めたスケジュールでメタデータ キャッシュを更新する場合は、MANUAL に設定します。この場合は、BQ.REFRESH_EXTERNAL_METADATA_CACHE システム プロシージャを呼び出してキャッシュを更新できます。

     STALENESS_INTERVAL が 0 より大きい値に設定されている場合は、CACHE_MODE を設定する必要があります。

3. [実行] をクリックします。

クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。

例:

CREATE EXTERNAL TABLE awsdataset.awstable
  WITH CONNECTION `aws-us-east-1.s3-read-connection`
  OPTIONS (
    format="CSV",
    uris=["s3://s3-bucket/path/file.csv"],
    max_staleness = INTERVAL 1 DAY,
    metadata_cache_mode = 'AUTOMATIC'
);

bq

テーブル定義ファイルを作成します。

bq mkdef  \
--source_format=DATA_FORMAT \
--connection_id=AWS_LOCATION.CONNECTION_NAME \
--metadata_cache_mode=CACHE_MODE \
S3_URI > table_def

次のように置き換えます。

• DATA_FORMAT: サポートされている任意の BigQuery 連携形式（AVRO、CSV、DELTA_LAKE、ICEBERG、PARQUET など）。
• S3_URI: Amazon S3 データを指す URI（例: s3://bucket/path）。
• AWS_LOCATION: Google Cloud の AWS ロケーション（たとえば、aws-us-east-1）。

• CONNECTION_NAME: 作成した接続の名前。

• CACHE_MODE: メタデータ キャッシュを自動的に更新するか手動で更新するかを指定します。このフラグは、後続の bq mk コマンドで --max_staleness フラグを使用してメタデータ キャッシュを有効にする場合にのみ指定する必要があります。メタデータ キャッシュに関する考慮事項の詳細については、メタデータ キャッシュによるパフォーマンスの向上をご覧ください。

  AUTOMATIC に設定すると、メタデータ キャッシュがシステムで定義された間隔（通常は 30～60 分）で更新されます。

  自身で決めたスケジュールでメタデータ キャッシュを更新する場合は、MANUAL に設定します。この場合は、BQ.REFRESH_EXTERNAL_METADATA_CACHE システム プロシージャを呼び出してキャッシュを更新できます。 STALENESS_INTERVAL が 0 より大きい値に設定されている場合は、CACHE_MODE を設定する必要があります。

注: デフォルト プロジェクトをオーバーライドするには、--project_id=PROJECT_ID パラメータを使用します。PROJECT_ID は、Google Cloud プロジェクトの ID に置き換えます。

次に、BigLake テーブルを作成します。

bq mk --max_staleness=STALENESS_INTERVAL --external_table_definition=table_def DATASET_NAME.TABLE_NAME

次のように置き換えます。

• STALENESS_INTERVAL: キャッシュ内のメタデータを BigLake テーブルに対するオペレーションで使用するかどうかを指定します。また、オペレーションがキャッシュ内のメタデータを使用するためにその鮮度を指定します。メタデータ キャッシュに関する考慮事項の詳細については、メタデータ キャッシュによるパフォーマンスの向上をご覧ください。

  メタデータのキャッシュ保存を無効にするには、0 を指定します。これがデフォルトです。

  メタデータ キャッシュを有効にするには、30 分から 7 日の間で間隔リテラルの値を指定します。たとえば、4 時間の未更新間隔の場合、INTERVAL 4 HOUR を指定します。この値を指定すると、キャッシュに保存されたメタデータが過去 4 時間以内に更新されていれば、テーブルに対するオペレーションはそのメタデータを使用します。キャッシュに保存されているメタデータがそれより古い場合、オペレーションは代わりに Amazon S3 からメタデータを取得します。

• DATASET_NAME: 作成したデータセットの名前。

• TABLE_NAME: このテーブルに設定する名前。

たとえば、次のコマンドでは、新しい BigLake テーブル awsdataset.awstable を作成します。これにより、パス s3://s3-bucket/path/file.csv に保存されている Amazon S3 データをクエリでき、ロケーション aws-us-east-1 に読み取り接続があります。

bq mkdef  \
--autodetect \
--source_format=CSV \
--connection_id=aws-us-east-1.s3-read-connection \
--metadata_cache_mode=AUTOMATIC \
s3://s3-bucket/path/file.csv > table_def

bq mk --max_staleness=INTERVAL "1" HOUR \
--external_table_definition=table_def awsdataset.awstable

API

tables.insert API メソッドを呼び出して、Table リソースに ExternalDataConfiguration を作成します。

schema プロパティを指定するか autodetect プロパティを true に設定して、サポートされているデータソースのスキーマの自動検出を有効にします。

connectionId プロパティを指定して、Amazon S3 への接続に使用する接続を特定します。

Java

このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CsvOptions;
import com.google.cloud.bigquery.ExternalTableDefinition;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

// Sample to create an external aws table
public class CreateExternalTableAws {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String connectionId = "MY_CONNECTION_ID";
    String sourceUri = "s3://your-bucket-name/";
    CsvOptions options = CsvOptions.newBuilder().setSkipLeadingRows(1).build();
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    ExternalTableDefinition externalTableDefinition =
        ExternalTableDefinition.newBuilder(sourceUri, options)
            .setConnectionId(connectionId)
            .setSchema(schema)
            .build();
    createExternalTableAws(projectId, datasetName, tableName, externalTableDefinition);
  }

  public static void createExternalTableAws(
      String projectId,
      String datasetName,
      String tableName,
      ExternalTableDefinition externalTableDefinition) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(projectId, datasetName, tableName);
      TableInfo tableInfo = TableInfo.newBuilder(tableId, externalTableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Aws external table created successfully");

      // Clean up
      bigquery.delete(TableId.of(projectId, datasetName, tableName));
    } catch (BigQueryException e) {
      System.out.println("Aws external was not created." + e.toString());
    }
  }
}

パーティション分割データに対して BigLake テーブルを作成する

Amazon S3 の Hive パーティション分割データ用の BigLake テーブルを作成できます。外部パーティション分割テーブルを作成した後に、パーティション キーを変更することはできません。パーティション キーを変更するには、テーブルを再作成する必要があります。

Hive パーティション分割データに基づいて BigLake テーブルを作成するには、次のいずれかのオプションを選択します。

コンソール

1. [BigQuery] ページに移動します。

   [BigQuery] に移動

2. [エクスプローラ] ペインでプロジェクトを開いて、データセットを選択します。

3. [アクションを表示] をクリックしてから、[テーブルを作成] をクリックします。これで、[テーブルを作成] ペインが開きます。

4. [送信元] セクションで、次の詳細を指定します。

   1. [テーブルの作成元] で [Amazon S3] を選択します。

   2. ワイルドカードを使用してフォルダへのパスを指定します。例: s3://mybucket/*

      このフォルダは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在する必要があります。

   3. [ファイル形式] リストでファイル形式を選択します。

   4. [ソースデータ パーティショニング] チェックボックスをオンにして、次の詳細を指定します。

      1. [ソース URI の接頭辞を選択] で、URI 接頭辞を入力します。例: s3://mybucket/my_files
      2. 省略可: このテーブルのすべてのクエリでパーティション フィルタを要求するには、[パーティション フィルタを要求] チェックボックスをオンにします。パーティション フィルタを要求すると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、クエリ内のパーティション キーに対する必須の述語フィルタをご覧ください。

      3. [パーティション推論モード] セクションで、次のいずれかのオプションを選択します。

         • 種類を自動的に推測します: パーティション スキーマ検出モードを AUTO に設定します。
         • すべての列は文字列です: パーティション スキーマ検出モードを STRINGS に設定します。
         • 独自に指定します: パーティション スキーマ検出モードを CUSTOM に設定し、パーティション キーのスキーマ情報を手動で入力します。詳細については、カスタム パーティション キー スキーマの指定をご覧ください。

5. [送信先] セクションで、次の詳細を指定します。

   1. [プロジェクト] で、テーブルを作成するプロジェクトを選択します。
   2. [データセット] で、テーブルを作成するデータセットを選択します。
   3. [テーブル] に、作成するテーブルの名前を入力します。
   4. [テーブルタイプ] で [外部テーブル] が選択されていることを確認します。
   5. [接続 ID] で、先ほど作成した接続を選択します。

6. [スキーマ] セクションで、スキーマの自動検出を有効にするか、ソースファイルがある場合はスキーマを手動で指定できます。ソースファイルがない場合は、スキーマを手動で指定する必要があります。

   • スキーマの自動検出を有効にするには、[自動検出] オプションをオンにします。

   • 手動でスキーマを指定するには、[自動検出] オプションをオフにしておきます。[テキストとして編集] を有効にし、テーブル スキーマを JSON 配列として入力します。

7. スキーマと一致しない追加の列値を持つ行を無視するには、[詳細オプション] セクションを開いて [不明な値] を選択します。

8. [テーブルを作成] をクリックします。

SQL

CREATE EXTERNAL TABLE DDL ステートメントを使用します。

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

   [BigQuery] に移動

2. クエリエディタで次のステートメントを入力します。

   CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
   WITH PARTITION COLUMNS
   (
     PARTITION_COLUMN PARTITION_COLUMN_TYPE,
   )
   WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
   OPTIONS (
     hive_partition_uri_prefix = "HIVE_PARTITION_URI_PREFIX",
     uris=['FILE_PATH'],
     format ="TABLE_FORMAT"
     max_staleness = STALENESS_INTERVAL,
     metadata_cache_mode = 'CACHE_MODE'
   );

   次のように置き換えます。

   • PROJECT_ID: テーブルを作成するプロジェクトの名前（例: myproject）
   • DATASET: テーブルを作成する BigQuery データセットの名前（例: mydataset）
   • EXTERNAL_TABLE_NAME: 作成するテーブルの名前（例: mytable）
   • PARTITION_COLUMN: パーティショニング列の名前。
   • PARTITION_COLUMN_TYPE: パーティショニング列の型
   • REGION: 接続を含むリージョン（例: us）
   • CONNECTION_ID: 接続の名前（例: myconnection）
   • HIVE_PARTITION_URI_PREFIX: Hive パーティショニング URI 接頭辞（例: s3://mybucket/）
   • FILE_PATH: 作成する外部テーブルのデータソースへのパス。例: s3://mybucket/*.parquet
   • TABLE_FORMAT: 作成するテーブルの形式（例: PARQUET）
   • STALENESS_INTERVAL: キャッシュ内のメタデータを BigLake テーブルに対するオペレーションで使用するかどうかを指定します。また、オペレーションがキャッシュ内のメタデータを使用するためにその鮮度を指定します。メタデータ キャッシュに関する考慮事項の詳細については、メタデータ キャッシュによるパフォーマンスの向上をご覧ください。

     メタデータのキャッシュ保存を無効にするには、0 を指定します。これがデフォルトです。

     メタデータ キャッシュを有効にするには、30 分から 7 日の間で間隔リテラルの値を指定します。たとえば、4 時間の未更新間隔の場合、INTERVAL 4 HOUR を指定します。この値を指定すると、キャッシュに保存されたメタデータが過去 4 時間以内に更新されていれば、テーブルに対するオペレーションはそのメタデータを使用します。キャッシュに保存されているメタデータがそれより古い場合、オペレーションは代わりに Amazon S3 からメタデータを取得します。

   • CACHE_MODE: メタデータ キャッシュを自動的に更新するか手動で更新するかを指定します。メタデータ キャッシュに関する考慮事項の詳細については、メタデータ キャッシュによるパフォーマンスの向上をご覧ください。

     AUTOMATIC に設定すると、メタデータ キャッシュがシステムで定義された間隔（通常は 30～60 分）で更新されます。

     自身で決めたスケジュールでメタデータ キャッシュを更新する場合は、MANUAL に設定します。この場合は、BQ.REFRESH_EXTERNAL_METADATA_CACHE システム プロシージャを呼び出してキャッシュを更新できます。

     STALENESS_INTERVAL が 0 より大きい値に設定されている場合は、CACHE_MODE を設定する必要があります。

3. [実行] をクリックします。

クエリの実行方法について詳しくは、インタラクティブ クエリを実行するをご覧ください。

例

次の例では、Amazon S3 のパーティション分割データに対する BigLake テーブルを作成します。スキーマは自動検出されます。

CREATE EXTERNAL TABLE `my_dataset.my_table`
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "s3://mybucket/products",
  uris = ['s3://mybucket/products/*']
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

bq

まず、bq mkdef コマンドを使用してテーブル定義ファイルを作成します。

bq mkdef \
--source_format=SOURCE_FORMAT \
--connection_id=REGION.CONNECTION_ID \
--hive_partitioning_mode=PARTITIONING_MODE \
--hive_partitioning_source_uri_prefix=URI_SHARED_PREFIX \
--require_hive_partition_filter=BOOLEAN \
--metadata_cache_mode=CACHE_MODE \
 URIS > DEFINITION_FILE

次のように置き換えます。

• SOURCE_FORMAT: 外部データソースの形式。例: CSV
• REGION: 接続を含むリージョン（例: us）。
• CONNECTION_ID: 接続の名前（例: myconnection）。
• PARTITIONING_MODE: Hive パーティショニング モード。次の値のいずれかを使用できます。
  • AUTO: キー名と型を自動的に検出します。
  • STRINGS: キー名を自動的に文字列に変換します。
  • CUSTOM: ソース URI 接頭辞でキースキーマをエンコードします。
• URI_SHARED_PREFIX: ソース URI 接頭辞。

• BOOLEAN: クエリ時に述語フィルタを要求するかどうかを指定します。このフラグは省略可能です。デフォルト値は false です。

• CACHE_MODE: メタデータ キャッシュを自動的に更新するか手動で更新するかを指定します。このフラグは、後続の bq mk コマンドで --max_staleness フラグを使用してメタデータ キャッシュを有効にする場合にのみ指定する必要があります。メタデータ キャッシュに関する考慮事項の詳細については、メタデータ キャッシュによるパフォーマンスの向上をご覧ください。

  AUTOMATIC に設定すると、メタデータ キャッシュがシステムで定義された間隔（通常は 30～60 分）で更新されます。

  自身で決めたスケジュールでメタデータ キャッシュを更新する場合は、MANUAL に設定します。この場合は、BQ.REFRESH_EXTERNAL_METADATA_CACHE システム プロシージャを呼び出してキャッシュを更新できます。 STALENESS_INTERVAL が 0 より大きい値に設定されている場合は、CACHE_MODE を設定する必要があります。

• URIS: ワイルドカードを使用した Amazon S3 フォルダのパス。

• DEFINITION_FILE: ローカルマシン上のテーブル定義ファイルへのパス。

PARTITIONING_MODE が CUSTOM の場合、次の形式を使用して、ソース URI プレフィックスにパーティション キー スキーマを含めます。

--hive_partitioning_source_uri_prefix=URI_SHARED_PREFIX/{KEY1:TYPE1}/{KEY2:TYPE2}/...

テーブル定義ファイルを作成したら、bq mk コマンドを使用して BigLake テーブルを作成します。

bq mk --max_staleness=STALENESS_INTERVAL \
--external_table_definition=DEFINITION_FILE \
DATASET_NAME.TABLE_NAME \
SCHEMA

次のように置き換えます。

• STALENESS_INTERVAL: キャッシュ内のメタデータを BigLake テーブルに対するオペレーションで使用するかどうかを指定します。また、オペレーションがキャッシュ内のメタデータを使用するためにその鮮度を指定します。メタデータ キャッシュに関する考慮事項の詳細については、メタデータ キャッシュによるパフォーマンスの向上をご覧ください。

  メタデータのキャッシュ保存を無効にするには、0 を指定します。これがデフォルトです。

  メタデータ キャッシュを有効にするには、30 分から 7 日の間で間隔リテラルの値を指定します。たとえば、4 時間の未更新間隔の場合、INTERVAL 4 HOUR を指定します。この値を指定すると、キャッシュに保存されたメタデータが過去 4 時間以内に更新されていれば、テーブルに対するオペレーションはそのメタデータを使用します。キャッシュに保存されているメタデータがそれより古い場合、オペレーションは代わりに Amazon S3 からメタデータを取得します。

• DEFINITION_FILE: テーブル定義ファイルへのパス。

• DATASET_NAME: テーブルを含むデータセットの名前。

• TABLE_NAME: 作成するテーブルの名前。

• SCHEMA: JSON スキーマ ファイルへのパスを指定するか、field:data_type,field:data_type,... 形式のスキーマを指定します。スキーマの自動検出を使用するには、この引数を省略します。

例

次の例では、Amazon S3 データに対して AUTO Hive パーティショニング モードを使用します。

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=AUTO \
  --hive_partitioning_source_uri_prefix=s3://mybucket/myTable \
  --metadata_cache_mode=AUTOMATIC \
  s3://mybucket/* > mytable_def

bq mk --max_staleness=INTERVAL "1" HOUR \
  --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

次の例では、Amazon S3 データに対して STRING Hive パーティショニング モードを使用します。

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=STRING \
  --hive_partitioning_source_uri_prefix=s3://mybucket/myTable \
  --metadata_cache_mode=AUTOMATIC \
  s3://mybucket/myTable/* > mytable_def

bq mk --max_staleness=INTERVAL "1" HOUR \
  --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

API

BigQuery API を使用して Hive パーティショニングを設定するには、テーブル定義ファイルを作成する際に、ExternalDataConfiguration オブジェクトに hivePartitioningOptions オブジェクトを含めます。BigLake テーブルを作成するには、connectionId フィールドの値も指定する必要があります。

hivePartitioningOptions.mode フィールドを CUSTOM に設定した場合、hivePartitioningOptions.sourceUriPrefix フィールドのパーティション キースキーマを次のように入力します。s3://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...

クエリの実行時に述語フィルタの使用を強制するには、hivePartitioningOptions.requirePartitionFilter フィールドを true に設定します。

Delta Lake テーブル

Delta Lake は、ペタバイト規模のデータテーブルをサポートするオープンソースのテーブル形式です。Delta Lake のテーブルは一時テーブルと永続テーブルの両方としてクエリでき、BigLake テーブルとしてサポートされています。

スキーマの同期

Delta Lake は、正規スキーマをメタデータの一部として維持します。JSON メタデータ ファイルを使用してスキーマを更新することはできません。スキーマを更新するには:

1. --autodetect_schema フラグを指定して bq update コマンドを使用します。

   bq update --autodetect_schema
   PROJECT_ID:DATASET.TABLE
   

   次のように置き換えます。

   • PROJECT_ID: 更新するテーブルを含むプロジェクト ID

   • DATASET: 更新するテーブルを含むデータセット

   • TABLE: 更新するテーブル。

型変換

BigQuery は Delta Lake のデータ型を次の BigQuery データ型に変換します。

Delta Lake の型	BigQuery の型
boolean	BOOL
byte	INT64
int	INT64
long	INT64
float	FLOAT64
double	FLOAT64
Decimal(P/S)	精度に応じて NUMERIC または BIG_NUMERIC
date	DATE
time	TIME
timestamp (not partition column)	TIMESTAMP
timestamp (partition column)	DATETIME
string	STRING
binary	BYTES
array<Type>	ARRAY<Type>
struct	STRUCT
map<KeyType, ValueType>	ARRAY<Struct<key KeyType, value ValueType>>

制限事項

Delta Lake テーブルには以下の制限が適用されます。

• Delta Lake テーブルには、外部テーブルの制限が適用されます。

• Delta Lake テーブルは BigQuery Omni でのみサポートされており、関連する制限事項があります。

• 新しい JSON メタデータ ファイルでテーブルを更新することはできません。自動検出スキーマ テーブル更新オペレーションを使用する必要があります。詳細については、スキーマの同期をご覧ください。

• BigLake のセキュリティ機能は、BigQuery サービスからアクセスされた場合にのみ、Delta Lake テーブルを保護します。

Delta Lake テーブルを作成する

次の例では、CREATE EXTERNAL TABLE ステートメントを使用して、Delta Lake 形式で外部テーブルを作成します。

CREATE [OR REPLACE] EXTERNAL TABLE table_name
WITH CONNECTION connection_name
OPTIONS (
         format = 'DELTA_LAKE',
         uris = ["parent_directory"]
       );

次のように置き換えます。

• table_name: テーブル名。

• connection_name: 接続の名前。接続では、Amazon S3 または Blob Storage のソースを指定する必要があります。

• parent_directory: 親ディレクトリの URI。

Delta Lake を使用したクロスクラウド転送

次の例では、LOAD DATA ステートメントを使用して、適切なテーブルにデータを読み込みます。

LOAD DATA [INTO | OVERWRITE] table_name
FROM FILES (
        format = 'DELTA_LAKE',
        uris = ["parent_directory"]
)
WITH CONNECTION connection_name;

クロスクラウド データ転送の詳細な例については、クロスクラウド オペレーションでデータを読み込むをご覧ください。

BigLake テーブルにクエリを実行する

詳細については、Amazon S3 データに対してクエリを行うをご覧ください。

リソース メタデータを表示する

プレビュー

この機能には、サービス固有の利用規約の「一般的なサービス規約」の「pre-GA サービス規約」が適用されます。 pre-GA の機能は「現状有姿」で利用できますが、サポートが制限される場合があります。 詳しくは、リリース ステージの説明をご覧ください。

リソース メタデータは INFORMATION_SCHEMA ビューで確認できます。JOBS_BY_*、JOBS_TIMELINE_BY_*、RESERVATION* のビューに対してクエリを行う場合は、テーブルのリージョンと同じ場所に配置されているクエリの処理ロケーションを指定する必要があります。BigQuery Omni のロケーションの詳細については、ロケーションをご覧ください。他のすべてのシステム テーブルでは、クエリジョブのロケーションの指定は任意です。

BigQuery Omni がサポートするシステム テーブルについては、制限事項をご覧ください。

JOBS_* システム テーブルと RESERVATION* システム テーブルに対してクエリを実行するには、次のいずれかの方法で処理を行うロケーションを指定します。

コンソール

1. [BigQuery] ページに移動します。

   [BigQuery] に移動

2. [エディタ] タブが表示されていない場合は、[クエリを新規作成] をクリックします。

3. [その他] > [クエリ設定] をクリックします。[クエリの設定] ダイアログが開きます。

4. [クエリの設定] ダイアログの [追加の設定] > [データのロケーション] で、BigQuery Omni リージョンと同じ場所に配置されている BigQuery リージョンを選択します。たとえば、BigQuery Omni リージョンが aws-us-east-1 の場合は、us-east4 を指定します。

5. 残りのフィールドを選択して、[保存] をクリックします。

bq

ジョブの処理を行うロケーションを、BigQuery Omni リージョンと同じ場所に配置される BigQuery リージョンに設定するには、--location フラグを使用します。たとえば、BigQuery Omni リージョンが aws-us-east-1 の場合は、us-east4 を指定します。

例

bq query --use_legacy_sql=false --location=us-east4 \
"SELECT * FROM region-aws-us-east-1.INFORMATION_SCHEMA.JOBS limit 10;"

bq query --use_legacy_sql=false --location=asia-northeast3 \
"SELECT * FROM region-aws-ap-northeast-2.INFORMATION_SCHEMA.JOBS limit 10;"

API

プログラムでジョブを実行する場合は、ロケーション引数を BigQuery Omni リージョンと同じ場所に配置される BigQuery リージョンに設定します。たとえば、BigQuery Omni リージョンが aws-us-east-1 の場合は、us-east4 を指定します。

次の例では、メタデータ更新ジョブを一覧表示します。

SELECT
 *
FROM
 `region-aws-us-east-1.INFORMATION_SCHEMA.JOBS_BY_PROJECT`
WHERE
 job_id LIKE '%metadata_cache_refresh%'
 AND creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 6 HOUR)
ORDER BY start_time desc
LIMIT 10;

VPC Service Controls

防御強化のため、VPC Service Controls の境界を使用して、BigQuery Omni から外部クラウド サービスへのアクセスを制限できます。たとえば、VPC Service Controls の境界により、BigQuery Omni テーブルから特定の Amazon S3 バケットまたは Blob Storage コンテナへのエクスポートを制限できます。

VPC Service Controls の詳細については、VPC Service Controls の概要をご覧ください。

必要な権限

サービス境界を構成するために必要な権限があることを確認します。VPC Service Controls を構成するために必要な IAM ロールの一覧を表示するには、VPC Service Controls のドキュメントの IAM を使用したアクセス制御をご覧ください。

Google Cloud コンソールを使用して VPC Service Controls を設定する

1. Google Cloud コンソールのナビゲーション メニューで [セキュリティ] をクリックし、続いて [VPC Service Controls] をクリックします。

   [VPC Service Controls] に移動

2. BigQuery Omni の VPC Service Controls を設定するには、サービス境界を作成するガイドの手順に沿って作業します。[下り（外向き）ルール] ペインが表示されたら、次の手順を行います。

   1. [下り（外向き）ルール] ペインで [ルールの追加] をクリックします。

   2. [API クライアントの FROM 属性] セクションで、[ID] リストからオプションを選択します。

   3. [外部リソースの TO 属性] を選択します。

   4. 外部リソースを追加するには、[Add external resources] をクリックします。

   5. [Add external resource] ダイアログで、[External resource name] に有効なリソース名を入力します。次に例を示します。

      • Amazon Simple Storage Service（Amazon S3）の場合: s3://BUCKET_NAME

        BUCKET_NAME は、Amazon S3 バケットの名前に置き換えます。

      • Azure Blob Storage の場合: azure://myaccount.blob.core.windows.net/CONTAINER_NAME

        CONTAINER NAME は、Blob Storage コンテナの名前に置き換えます。

      下り（外向き）ルールの属性の一覧については、下り（外向き）ルールのリファレンスをご覧ください。

   6. 外部リソースで許可するメソッドを選択します。

      1. すべてのメソッドを許可する場合は、[メソッド] リストで [All methods] を選択します。
      2. 特定のメソッドを許可する場合は、[Selected method] を選択し、[メソッドを選択] をクリックしてから、外部リソースに対して許可するメソッドを選択します。

   7. [境界を作成] をクリックします。

gcloud CLI を使用して VPC Service Controls を設定する

gcloud CLI を使用して VPC Service Controls を設定する手順は、次のとおりです。

1. デフォルトのアクセス ポリシーを設定する。
2. 下り（外向き）ポリシー入力ファイルを作成する。
3. 下り（外向き）ポリシーを追加する。

デフォルトのアクセス ポリシーを設定する

アクセス ポリシーは、アクセスレベルとサービス境界用の組織全体のコンテナです。デフォルトのアクセス ポリシーの設定、またはアクセス ポリシー名の取得については、アクセス ポリシーの管理をご覧ください。

下り（外向き）ポリシー入力ファイルを作成する

下り（外向き）ルールのブロックは、境界からその境界外のリソースへ許可されるアクセスを定義します。外部リソースの場合、externalResources プロパティは、VPC Service Controls の境界内からアクセスできる外部リソースパスを定義します。

下り（外向き）ルールは、JSON ファイルまたは YAML ファイルを使用して構成できます。次のサンプルでは、.yaml 形式を使用します。

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
      *OR*
      - permission: "externalResource.read"
    externalResources:
      - EXTERNAL_RESOURCE_PATH
  egressFrom:
    identityType: IDENTITY_TYPE
    *OR*
    identities:
    - serviceAccount:SERVICE_ACCOUNT

• egressTo - 境界外の指定されたプロジェクトの Google Cloud リソースに対して許可されているサービス オペレーションを一覧表示します。

• operations: from ブロック条件を満たすクライアントがアクセスを許可され、アクセスが可能なサービスとアクション、またはメソッドを一覧表示します。

• serviceName: BigQuery Omni に bigquery.googleapis.com を設定します。

• methodSelectors: from 条件を満たすクライアントがアクセスできるメソッドを一覧表示します。制限付きのメソッドとサービスの権限については、サポートされているサービス メソッドの制限をご覧ください。

• method : 有効なサービス メソッド、またはすべての serviceName メソッドを許可する \"*\"。

• permission: 有効なサービス権限（\"*\"、externalResource.read、externalResource.write など）。この権限を必要とするオペレーションでは、境界外のリソースにアクセスできます。

• externalResources: 境界内のクライアントがアクセスできる外部リソースを一覧表示します。EXTERNAL_RESOURCE_PATH は、有効な Amazon S3 バケット（s3://bucket_name など）または Blob Storage コンテナパス（azure://myaccount.blob.core.windows.net/container_name など）に置き換えます。

• egressFrom - 境界内の指定されたプロジェクトの Google Cloud リソースに対して許可されているサービス オペレーションを一覧表示します。

• identityType または identities: 境界外の指定されたリソースにアクセスできる ID タイプを定義します。IDENTITY_TYPE は、次のいずれかの有効な値に置き換えます。

  • ANY_IDENTITY: すべての ID を許可します。
  • ANY_USER_ACCOUNT: すべてのユーザーを許可します。
  • ANY_SERVICE_ACCOUNT: すべてのサービス アカウントを許可します。

• identities: 境界外の指定リソースにアクセスできるサービス アカウントを一覧表示します。

• serviceAccount（省略可）: SERVICE_ACCOUNT を、境界外の指定されたリソースにアクセスできるサービス アカウントに置き換えます。

例

次の例は、境界内からの AWS 内の s3://mybucket Amazon S3 ロケーションへの下り（外向き）オペレーションを許可するポリシーです。

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
    externalResources:
      - s3://mybucket
      - s3://mybucket2
  egressFrom:
    identityType: ANY_IDENTITY

次の例では、Blob Storage コンテナへの下り（外向き）オペレーションを許可します。

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
    externalResources:
      - azure://myaccount.blob.core.windows.net/mycontainer
  egressFrom:
    identityType: ANY_IDENTITY

下り（外向き）ポリシーの詳細については、下り（外向き）ルールのリファレンスをご覧ください。

下り（外向き）ポリシーを追加する

新しいサービス境界を作成するときに下り（外向き）ポリシーを追加するには、gcloud access-context-manager perimeters create コマンドを使用します。たとえば、次のコマンドは、プロジェクト番号 12345 を持つプロジェクトを含む omniPerimeter という名前の新しい境界を作成し、BigQuery API を制限して、egress.yaml ファイルで定義されている下り（外向き）ポリシーを追加します。

gcloud access-context-manager perimeters create omniPerimeter \
    --title="Omni Perimeter" \
    --resources=projects/12345 \
    --restricted-services=bigquery.googleapis.com \
    --egress-policies=egress.yaml

既存のサービス境界に下り（外向き）ポリシーを追加するには、gcloud access-context-manager perimeters update コマンドを使用します。たとえば、次のコマンドは、egress.yaml ファイルで定義されている下り（外向き）ポリシーを omniPerimeter という名前の既存のサービス境界に追加します。

gcloud access-context-manager perimeters update omniPerimeter
    --set-egress-policies=egress.yaml

境界を確認する

境界を確認するには、gcloud access-context-manager perimeters describe コマンドを使用します。

gcloud access-context-manager perimeters describe PERIMETER_NAME

PERIMETER_NAME は、境界の名前に置き換えます。

たとえば、次のコマンドは境界 omniPerimeter を記述します。

gcloud access-context-manager perimeters describe omniPerimeter

詳細については、サービス境界を管理するをご覧ください。

BigQuery Omni VPC から Amazon S3 へのアクセスを許可する

プレビュー

この機能には、サービス固有の利用規約の「一般的なサービス規約」の「pre-GA サービス規約」が適用されます。 pre-GA の機能は「現状有姿」で利用できますが、サポートが制限される場合があります。 詳しくは、リリース ステージの説明をご覧ください。

この機能に関するフィードバックやサポートをご希望の場合は、[e-mail] 宛てにメールを送信してください。

BigQuery 管理者は、S3 バケット ポリシーを作成して、BigQuery Omni に Amazon S3 リソースへのアクセス権を付与できます。これにより、承認された BigQuery Omni VPC のみが Amazon S3 とやり取りできる状態が確保されるため、データのセキュリティが強化されます。

BigQuery Omni VPC に S3 バケット ポリシーを適用する

S3 バケット ポリシーを適用するには、AWS CLI または Terraform を使用します。

AWS CLI

次のコマンドを実行して、aws:SourceVpc 属性を使用する条件を含む S3 バケット ポリシーを適用します。

  aws s3api put-bucket-policy \
    --bucket=BUCKET_NAME \
    --policy "{
      \"Version\": \"2012-10-17\",
      \"Id\": \"RestrictBucketReads\",
      \"Statement\": [
          {
              \"Sid\": \"AccessOnlyToOmniVPC\",
              \"Principal\": \"*\",
              \"Action\": [\"s3:ListBucket\", \"s3:GetObject\"],
              \"Effect\": \"Allow\",
              \"Resource\": [\"arn:aws:s3:::BUCKET_NAME\",
                             \"arn:aws:s3:::BUCKET_NAME/*\"],
              \"Condition\": {
                  \"StringEquals\": {
                    \"aws:SourceVpc\": \"VPC_ID\"
                  }
              }
          }
      ]
    }"

次のように置き換えます。

• BUCKET_NAME: BigQuery がアクセスする Amazon S3 バケット。
• VPC_ID: Amazon S3 バケットと同じ場所にある BigQuery Omni リージョンの BigQuery Omni VPC ID。この情報は、このページの表で確認できます。

Terraform

Terraform 構成ファイルに以下を追加します。

  resource "aws_s3_bucket" "example" {
    bucket = "BUCKET_NAME"
  }

  resource "aws_s3_bucket_policy" "example" {
    bucket = aws_s3_bucket.example.id
    policy = jsonencode({
      Version = "2012-10-17"
      Id      = "RestrictBucketReads"
      Statement = [
          {
              Sid       = "AccessOnlyToOmniVPC"
              Effect    = "Allow"
              Principal = "*"
              Action    = ["s3:GetObject", "s3:ListBucket"]
              Resource  = [
                  aws_s3_bucket.example.arn,
                  "${aws_s3_bucket.example.arn}/*"
                  ]
              Condition = {
                  StringEquals = {
                      "aws:SourceVpc": "VPC_ID"
                  }
              }
          },
      ]
    })
  }

次のように置き換えます。

• BUCKET_NAME: BigQuery がアクセスする Amazon S3 バケット。
• VPC_ID: Amazon S3 バケットと同じ場所にある BigQuery Omni リージョンの BigQuery Omni VPC ID。

BigQuery Omni VPC リソース ID

リージョン	VPC ID
aws-ap-northeast-2	vpc-0b488548024288af2
aws-ap-southeast-2	vpc-0726e08afef3667ca
aws-eu-central-1	vpc-05c7bba12ad45558f
aws-eu-west-1	vpc-0e5c646979bbe73a0
aws-us-east-1	vpc-0bf63a2e71287dace
aws-us-west-2	vpc-0cc24e567b9d2c1cb

制限事項

Amazon S3 と Blob Storage に基づく BigLake テーブルに適用される制限事項の全リストについては、制限事項をご覧ください。

次のステップ

• BigQuery Omni について確認する。
• AWS ラボで BigQuery Omni を使用する。
• BigLake テーブルについて確認する。
• クエリ結果を Amazon S3 にエクスポートする方法を確認する。
• Amazon Simple Storage Service（Amazon S3）メタデータ キャッシュが有効になっているテーブルのマテリアライズド ビューを作成する方法を学習する。
• マテリアライズド ビューのレプリカを作成して、マテリアライズド ビューの Amazon S3 データをローカルでの結合に使用できるようにする方法を学習する。