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

コンソール

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

   BigQuery に移動

2. [エクスプローラ] ペインで、データセットを作成するプロジェクトを選択します。
3. [more_vertアクションを表示] オプションを開き、[データセットを作成] をクリックします。
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. [play_circle実行] をクリックします。

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

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

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());
    }
  }
}

コンソール

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

   BigQuery に移動

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

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

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. [play_circle実行] をクリックします。

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

例:

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 を設定する必要があります。

次に、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

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());
    }
  }
}

コンソール

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

   BigQuery に移動

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

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

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. [play_circle実行] をクリックします。

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

例

次の例では、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 に設定します。

コンソール

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

   BigQuery に移動

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

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 を指定します。

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。