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
カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。
データセットを作成する
外部テーブルを作成する前に、サポートされているリージョンにデータセットを作成する必要があります。次のオプションのいずれかを選択します。コンソール
[BigQuery] ページに移動します。
- [エクスプローラ] ペインで、データセットを作成するプロジェクトを選択します。
- (アクションを表示)オプションを開き、[データセットを作成] をクリックします。
- [データセットを作成] ページで、次の詳細を指定します。
- [データセット ID] に、データセットの一意の名前を入力します。
- [データのロケーション] で、サポートされているリージョンを選択します。
- 省略可: テーブルを自動的に削除するには、[テーブルの有効期限を有効にする] チェックボックスをオンにして、[デフォルトのテーブル最長存続期間] を日数で設定します。テーブルが期限切れになると、Amazon S3 のデータは削除されません。
- デフォルトの照合を使用する場合は、[詳細オプション] セクションを開いて、[デフォルトの照合を有効にする] オプションを選択します。
- [データセットを作成] をクリックします。
SQL
CREATE SCHEMA
DDL ステートメントを使用します。次の例では、aws-us-east-1
リージョンにデータセットが作成されます。
Google Cloud コンソールで [BigQuery] ページに移動します。
クエリエディタで次のステートメントを入力します。
CREATE SCHEMA mydataset OPTIONS ( location = 'aws-us-east-1');
[
実行] をクリックします。
クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。
bq
コマンドライン環境で bq mk
コマンドを使用してデータセットを作成します。
bq --location=LOCATION mk \ --dataset \ PROJECT_ID:DATASET_NAME
--project_id
パラメータは、デフォルト プロジェクトをオーバーライドします。
次のように置き換えます。
LOCATION
: データセットのロケーションサポートされているリージョンの詳細については、ロケーションをご覧ください。 データセットを作成した後に、そのロケーションを変更することはできません。ロケーションのデフォルト値は、
.bigqueryrc
ファイルを使用して設定できます。PROJECT_ID
: プロジェクト IDDATASET_NAME
: 作成するデータセットの名前デフォルト プロジェクト以外のプロジェクト内にデータセットを作成するには、
PROJECT_ID:DATASET_NAME
の形式でそのプロジェクト ID をデータセット名に追加します。
Java
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
パーティション分割されていないデータに対して BigLake テーブルを作成する
次のオプションのいずれかを選択します。
コンソール
[BigQuery] ページに移動します。
[エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。
[データセット情報] セクションで、[
テーブルを作成] をクリックします。[テーブルの作成] ページの [ソース] セクションで、次の操作を行います。
- [テーブルの作成元] で [Amazon S3] を選択します。
- [S3 パスを選択] に、Amazon S3 データを指す URI を
s3://BUCKET_NAME/PATH
の形式で入力します。BUCKET_NAME
は Amazon S3 バケットの名前に置き換えます。バケットのリージョンは、データセットのリージョンと同じにする必要があります。PATH
は、エクスポート ファイルを書き込むパスで置き換えます。ワイルドカード*
を使用できます。 - [ファイル形式] で、Amazon S3 のデータ形式を選択します。サポートされている形式は、AVRO、CSV、DELTA_LAKE、ICEBERG、JSONL、ORC、PARQUET です。
[送信先] セクションで、次の詳細を指定します。
- [データセット] で、該当するデータセットを選択します。
- [テーブル] フィールドにテーブルの名前を入力します。
- [テーブルタイプ] が [外部テーブル] に設定されていることを確認します。
- [接続 ID] で、プルダウンから該当する接続 ID を選択します。接続については、Amazon S3 への接続をご覧ください。
[スキーマ] セクションで、スキーマの自動検出を有効にするか、ソースファイルがある場合はスキーマを手動で指定できます。ソースファイルがない場合は、スキーマを手動で指定する必要があります。
スキーマの自動検出を有効にするには、[自動検出] オプションをオンにします。
手動でスキーマを指定するには、[自動検出] オプションをオフにしておきます。[テキストとして編集] を有効にし、テーブル スキーマを JSON 配列として入力します。
[テーブルを作成] をクリックします。
SQL
BigLake テーブルを作成するには、WITH CONNECTION
句を指定した CREATE EXTERNAL TABLE
ステートメントを使用します。
Google Cloud コンソールで [BigQuery] ページに移動します。
クエリエディタで次のステートメントを入力します。
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
を設定する必要があります。
[
実行] をクリックします。
クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。
例:
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
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
パーティション分割データに対して BigLake テーブルを作成する
Amazon S3 の Hive パーティション分割データ用の BigLake テーブルを作成できます。外部パーティション分割テーブルを作成した後に、パーティション キーを変更することはできません。パーティション キーを変更するには、テーブルを再作成する必要があります。
Hive パーティション分割データに基づいて BigLake テーブルを作成するには、次のいずれかのオプションを選択します。
コンソール
[BigQuery] ページに移動します。
[エクスプローラ] ペインでプロジェクトを開いて、データセットを選択します。
[アクションを表示] をクリックしてから、[テーブルを作成] をクリックします。これで、[テーブルを作成] ペインが開きます。
[送信元] セクションで、次の詳細を指定します。
[テーブルの作成元] で [Amazon S3] を選択します。
ワイルドカードを使用してフォルダへのパスを指定します。例:
s3://mybucket/*
このフォルダは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在する必要があります。
[ファイル形式] リストでファイル形式を選択します。
[ソースデータ パーティショニング] チェックボックスをオンにして、次の詳細を指定します。
- [ソース URI の接頭辞を選択] で、URI 接頭辞を入力します。例:
s3://mybucket/my_files
- 省略可: このテーブルのすべてのクエリでパーティション フィルタを要求するには、[パーティション フィルタを要求] チェックボックスをオンにします。パーティション フィルタを要求すると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、クエリ内のパーティション キーに対する必須の述語フィルタをご覧ください。
[パーティション推論モード] セクションで、次のいずれかのオプションを選択します。
- 種類を自動的に推測します: パーティション スキーマ検出モードを
AUTO
に設定します。 - すべての列は文字列です: パーティション スキーマ検出モードを
STRINGS
に設定します。 - 独自に指定します: パーティション スキーマ検出モードを
CUSTOM
に設定し、パーティション キーのスキーマ情報を手動で入力します。詳細については、カスタム パーティション キー スキーマの指定をご覧ください。
- 種類を自動的に推測します: パーティション スキーマ検出モードを
- [ソース URI の接頭辞を選択] で、URI 接頭辞を入力します。例:
[送信先] セクションで、次の詳細を指定します。
- [プロジェクト] で、テーブルを作成するプロジェクトを選択します。
- [データセット] で、テーブルを作成するデータセットを選択します。
- [テーブル] に、作成するテーブルの名前を入力します。
- [テーブルタイプ] で [外部テーブル] が選択されていることを確認します。
- [接続 ID] で、先ほど作成した接続を選択します。
[スキーマ] セクションで、スキーマの自動検出を有効にするか、ソースファイルがある場合はスキーマを手動で指定できます。ソースファイルがない場合は、スキーマを手動で指定する必要があります。
スキーマの自動検出を有効にするには、[自動検出] オプションをオンにします。
手動でスキーマを指定するには、[自動検出] オプションをオフにしておきます。[テキストとして編集] を有効にし、テーブル スキーマを JSON 配列として入力します。
スキーマと一致しない追加の列値を持つ行を無視するには、[詳細オプション] セクションを開いて [不明な値] を選択します。
[テーブルを作成] をクリックします。
SQL
CREATE EXTERNAL TABLE
DDL ステートメントを使用します。
Google Cloud コンソールで [BigQuery] ページに移動します。
クエリエディタで次のステートメントを入力します。
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
を設定する必要があります。
[
実行] をクリックします。
クエリの実行方法について詳しくは、インタラクティブ クエリを実行するをご覧ください。
例
次の例では、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 メタデータ ファイルを使用してスキーマを更新することはできません。スキーマを更新するには:
--autodetect_schema
フラグを指定してbq update
コマンドを使用します。bq update --autodetect_schema PROJECT_ID:DATASET.TABLE
次のように置き換えます。
PROJECT_ID
: 更新するテーブルを含むプロジェクト IDDATASET
: 更新するテーブルを含むデータセット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 データに対してクエリを行うをご覧ください。
リソース メタデータを表示する
リソース メタデータはINFORMATION_SCHEMA
ビューで確認できます。JOBS_BY_*
、JOBS_TIMELINE_BY_*
、RESERVATION*
のビューに対してクエリを行う場合は、テーブルのリージョンと同じ場所に配置されているクエリの処理ロケーションを指定する必要があります。BigQuery Omni のロケーションの詳細については、ロケーションをご覧ください。他のすべてのシステム テーブルでは、クエリジョブのロケーションの指定は任意です。
BigQuery Omni がサポートするシステム テーブルについては、制限事項をご覧ください。
JOBS_*
システム テーブルと RESERVATION*
システム テーブルに対してクエリを実行するには、次のいずれかの方法で処理を行うロケーションを指定します。
コンソール
[BigQuery] ページに移動します。
[エディタ] タブが表示されていない場合は、[
クエリを新規作成] をクリックします。[その他] > [クエリ設定] をクリックします。[クエリの設定] ダイアログが開きます。
[クエリの設定] ダイアログの [追加の設定] > [データのロケーション] で、BigQuery Omni リージョンと同じ場所に配置されている BigQuery リージョンを選択します。たとえば、BigQuery Omni リージョンが
aws-us-east-1
の場合は、us-east4
を指定します。残りのフィールドを選択して、[保存] をクリックします。
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 を設定する
Google Cloud コンソールのナビゲーション メニューで [セキュリティ] をクリックし、続いて [VPC Service Controls] をクリックします。
BigQuery Omni の VPC Service Controls を設定するには、サービス境界を作成するガイドの手順に沿って作業します。[下り(外向き)ルール] ペインが表示されたら、次の手順を行います。
[下り(外向き)ルール] ペインで [ルールの追加] をクリックします。
[API クライアントの FROM 属性] セクションで、[ID] リストからオプションを選択します。
[外部リソースの TO 属性] を選択します。
外部リソースを追加するには、[Add external resources] をクリックします。
[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 コンテナの名前に置き換えます。
下り(外向き)ルールの属性の一覧については、下り(外向き)ルールのリファレンスをご覧ください。
外部リソースで許可するメソッドを選択します。
- すべてのメソッドを許可する場合は、[メソッド] リストで [All methods] を選択します。
- 特定のメソッドを許可する場合は、[Selected method] を選択し、[メソッドを選択] をクリックしてから、外部リソースに対して許可するメソッドを選択します。
[境界を作成] をクリックします。
gcloud CLI を使用して VPC Service Controls を設定する
gcloud CLI を使用して VPC Service Controls を設定する手順は、次のとおりです。
デフォルトのアクセス ポリシーを設定する
アクセス ポリシーは、アクセスレベルとサービス境界用の組織全体のコンテナです。デフォルトのアクセス ポリシーの設定、またはアクセス ポリシー名の取得については、アクセス ポリシーの管理をご覧ください。
下り(外向き)ポリシー入力ファイルを作成する
下り(外向き)ルールのブロックは、境界からその境界外のリソースへ許可されるアクセスを定義します。外部リソースの場合、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 へのアクセスを許可する
この機能に関するフィードバックやサポートをご希望の場合は、bq-omni-customer-support@google.com 宛てにメールを送信してください。
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 データをローカルでの結合に使用できるようにする方法を学習する。