Cloud Storage BigLake テーブルを作成する

このドキュメントでは、Cloud Storage BigLake テーブルの作成方法について説明します。BigLake テーブルを使用すると、アクセス委任を使用して Cloud Storage 内の構造化データに対するクエリを実行できます。アクセス権の委任により、BigLake テーブルへのアクセス権と基盤となるデータストアへのアクセス権が分離されます。

始める前に

1. Google Cloud Console の [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

   注: この手順で作成するリソースをそのまま保持する予定でない場合、既存のプロジェクトを選択するのではなく、新しいプロジェクトを作成してください。チュートリアルの終了後にそのプロジェクトを削除すれば、プロジェクトに関連するすべてのリソースを削除できます。

   プロジェクト セレクタに移動

2. Google Cloud プロジェクトで課金が有効になっていることを確認します。

3. BigQuery Connection API を有効にします。

   API を有効にする

   Apache Spark などのオープンソース エンジンから BigLake テーブルを読み取る場合は、BigQuery Storage Read API を有効にする必要があります。

4. Google Cloud コンソールで、「Cloud Shell をアクティブにする」をクリックします。

   Cloud Shell をアクティブにする

5. BigQuery データセットがあることを確認します。

6. Google Cloud SDK のバージョンが 366.0.0 以降であることを確認します。

   gcloud version
   

   必要に応じて、Google Cloud SDK を更新します。

   1. 省略可: Terraform の場合は、terraform-provider-google バージョン 4.25.0 以降が必要です。terraform-provider-google リリースは GitHub に掲載されています。Terraform の最新バージョンは、HashiCorp Terraform のダウンロードからダウンロードできます。

7. 外部データソースに基づいてクラウド リソース接続を作成し、その接続に Cloud Storage へのアクセス権を付与します。接続を作成するための適切な権限が付与されていない場合は、接続を作成して共有するよう BigQuery 管理者に依頼してください。

必要なロール

BigLake テーブルを作成するには、次の BigQuery Identity and Access Management（IAM）権限が必要です。

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

BigQuery 管理者（roles/bigquery.admin）の事前定義 Identity and Access Management ロールには、これらの権限が含まれています。

このロールでのプリンシパルでない場合は、アクセス権の付与、または BigLake テーブルの作成を管理者に依頼してください。

BigQuery での Identity and Access Management のロールと権限の詳細については、事前定義ロールと権限をご覧ください。

ロケーションに関する考慮事項

Cloud Storage を使用してデータファイルを保存する場合は、マルチリージョン バケットではなく、Cloud Storage のシングル リージョン バケットまたはデュアル リージョン バケットを使用することでパフォーマンスを改善できます。

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

BigQuery でのテーブルの作成に精通されている場合は、BigLake テーブルの作成プロセスも同様の手順で作成できます。テーブルでは、BigLake でサポートされている任意のファイル形式を使用できます。詳細については、制限事項をご覧ください。

BigLake テーブルを作成する前に、Cloud Storage にアクセスできるデータセットと Cloud リソース接続が必要です。

BigLake テーブルを作成するには、次のいずれかのオプションを選択します。

コンソール

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

   [BigQuery] に移動

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

3. アクション オプションを開き、[テーブルを作成] をクリックします。

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

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

   2. GCS バケットからファイルを選択するか、URI パターンを使用するには、使用するバケットとファイルを参照して選択するか、gs://bucket_name/[folder_name/]file_name の形式でパスを入力します。

      Google Cloud コンソールで複数の URI を指定することはできませんが、ワイルドカードとしてアスタリスク（*）を 1 つ指定することで複数のファイルを選択できます。たとえば、gs://mybucket/file_name* のようにします。詳細については、Cloud Storage の URI でのワイルドカードのサポートをご覧ください。

      Cloud Storage バケットは、作成するテーブルを含むデータセットと同じロケーションに存在する必要があります。

   3. [ファイル形式] で、ファイルと一致する形式を選択します。

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

   1. [プロジェクト] で、テーブルを作成するプロジェクトを選択します。

   2. [データセット] で、テーブルを作成するデータセットを選択します。

   3. [テーブル] に、作成するテーブルの名前を入力します。

   4. [テーブルタイプ] で [外部テーブル] を選択します。

   5. [Cloud リソース接続を使用して BigLake テーブルを作成する] を選択します。

   6. [接続 ID] で、先ほど作成した接続を選択します。

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

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

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

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

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

永続テーブルが作成されると、ネイティブの BigQuery テーブルの場合と同じようにクエリを実行できます。クエリの完了後は、CSV ファイルまたは JSON ファイルとして結果をエクスポートする、結果をテーブルとして保存する、または Google スプレッドシートに結果を保存することが可能です。

SQL

CREATE EXTERNAL TABLE DDL ステートメントを使用します。スキーマを明示的に指定できます。または、スキーマ自動検出を使用して外部データからスキーマを推論することもできます。

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

   [BigQuery] に移動

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

   CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
     WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
     OPTIONS (
       format ="TABLE_FORMAT",
       uris = ['BUCKET_PATH'[,...]],
       max_staleness = STALENESS_INTERVAL,
       metadata_cache_mode = 'CACHE_MODE'
       );
   

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

   • PROJECT_ID: テーブルを作成するプロジェクトの名前（例: myproject）
   • DATASET: テーブルを作成する BigQuery データセットの名前（例: mydataset）
   • EXTERNAL_TABLE_NAME: 作成するテーブルの名前（例: mytable）
   • REGION: 接続を含むリージョン（例: us）
   • CONNECTION_ID: 接続 ID（例: myconnection）。

     Google Cloud コンソールで接続の詳細を表示する場合、接続 ID は接続 ID に表示される完全修飾接続 ID の最後のセクションの値です（例: projects/myproject/locations/connection_location/connections/myconnection）。

   • TABLE_FORMAT: 作成するテーブルの形式（例: PARQUET）

     サポートされている形式の詳細については、制限事項をご覧ください。

   • BUCKET_PATH: 外部テーブルのデータを含む Cloud Storage バケットへのパス（['gs://bucket_name/[folder_name/]file_name'] 形式）。

     パスにワイルドカードとしてアスタリスク（*）を 1 つ使用して、バケットから複数のファイルを選択することもできます。たとえば、['gs://mybucket/file_name*'] のようにします。詳細については、Cloud Storage の URI でのワイルドカードのサポートをご覧ください。

     複数のパスを指定して、uris オプションに複数のバケットを指定できます。

     次の例に、有効な uris 値を示します。

     • ['gs://bucket/path1/myfile.csv']
     • ['gs://bucket/path1/*.csv']
     • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

     複数のファイルをターゲットとする uris 値を指定する場合、それらのファイルはすべて互換性のあるスキーマを共有する必要があります。

     BigQuery での Cloud Storage URI の使用について詳しくは、Cloud Storage リソースパスをご覧ください。

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

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

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

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

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

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

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

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

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

bq

オプション 1: テーブル定義ファイル

bq mkdef コマンドを使用してテーブル定義ファイルを作成し、次のようにファイルパスを bq mk コマンドに渡します。

bq mkdef \
    --connection_id=CONNECTION_ID \
    --source_format=SOURCE_FORMAT \
  BUCKET_PATH > DEFINITION_FILE

bq mk --table \
    --external_table_definition=DEFINITION_FILE \
    --max_staleness=STALENESS_INTERVAL \
    PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME \
    SCHEMA

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

• CONNECTION_ID: 接続 ID（例: myconnection）。

  Google Cloud コンソールで接続の詳細を表示する場合、接続 ID は接続 ID に表示される完全修飾接続 ID の最後のセクションの値です（例: projects/myproject/locations/connection_location/connections/myconnection）。

• SOURCE_FORMAT: 外部データソースの形式。たとえば、PARQUET のようにします。

• BUCKET_PATH: テーブルのデータを含む Cloud Storage バケットへのパス（gs://bucket_name/[folder_name/]file_pattern 形式）。

  file_pattern にワイルドカードとしてアスタリスク（*）を 1 つ指定して、バケットから複数のファイルを選択することもできます。たとえば、gs://mybucket/file00*.parquet のようにします。詳細については、Cloud Storage の URI でのワイルドカードのサポートをご覧ください。

  複数のパスを指定して、uris オプションに複数のバケットを指定できます。

  次の例に、有効な uris 値を示します。

  • gs://bucket/path1/myfile.csv
  • gs://bucket/path1/*.parquet
  • gs://bucket/path1/file1*、gs://bucket1/path1/*

  複数のファイルをターゲットとする uris 値を指定する場合、それらのファイルはすべて互換性のあるスキーマを共有する必要があります。

  BigQuery での Cloud Storage URI の使用方法については、Cloud Storage リソースパスをご覧ください。

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

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

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

  メタデータ キャッシュを有効にするには、INTERVAL データ型ドキュメントで説明されている Y-M D H:M:S 形式を使用して、30 分から 7 日の間隔値を指定します。たとえば、4 時間のステイルネス間隔の場合、0-0 0 4:0:0 を指定します。この値を指定すると、キャッシュに保存されたメタデータが過去 4 時間以内に更新されていれば、テーブルに対するオペレーションはそのメタデータを使用します。キャッシュに保存されたメタデータがそれより古い場合、オペレーションは代わりに Cloud Storage からメタデータを取得します。

• DATASET: テーブルを作成する BigQuery データセットの名前（例: mydataset）

• EXTERNAL_TABLE_NAME: 作成するテーブルの名前（例: mytable）

• SCHEMA: BigLake テーブルのスキーマ

例:

bq mkdef
    --connection_id=myconnection
    --metadata_cache_mode=CACHE_MODE
    --source_format=CSV 'gs://mybucket/*.csv' > mytable_def

bq mk
    --table
    --external_table_definition=mytable_def='gs://mybucket/*.csv'
    --max_staleness=0-0 0 4:0:0
    myproject:mydataset.mybiglaketable
    Region:STRING,Quarter:STRING,Total_sales:INTEGER

スキーマの自動検出を使用するには、--autodetect=true フラグを mkdef コマンドに設定し、スキーマを省略します。

bq mkdef \
    --connection_id=myconnection \
    --metadata_cache_mode=CACHE_MODE \
    --source_format=CSV --autodetect=true \
    gs://mybucket/*.csv > mytable_def

bq mk \
    --table \
    --external_table_definition=mytable_def=gs://mybucket/*.csv \
    --max_staleness=0-0 0 4:0:0 \
    myproject:mydataset.myexternaltable

オプション 2: インライン テーブル定義

テーブル定義ファイルを作成する代わりに、テーブル定義を bq mk コマンド に直接渡せます。@connection デコレータを使用して、--external_table_definition フラグの最後に使用する接続を指定します。

bq mk --table \
  --external_table_definition=@SOURCE_FORMAT=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \
  DATASET_NAME.TABLE_NAME \
  SCHEMA

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

• SOURCE_FORMAT: 外部データソースの形式。

  たとえば、CSV のようにします。

• BUCKET_PATH: テーブルのデータを含む Cloud Storage バケットへのパス（gs://bucket_name/[folder_name/]file_pattern 形式）。

  file_pattern にワイルドカードとしてアスタリスク（*）を 1 つ指定して、バケットから複数のファイルを選択することもできます。たとえば、gs://mybucket/file00*.parquet のようにします。詳細については、Cloud Storage の URI でのワイルドカードのサポートをご覧ください。

  複数のパスを指定して、uris オプションに複数のバケットを指定できます。

  次の例に、有効な uris 値を示します。

  • gs://bucket/path1/myfile.csv
  • gs://bucket/path1/*.parquet
  • gs://bucket/path1/file1*、gs://bucket1/path1/*

  複数のファイルをターゲットとする uris 値を指定する場合、それらのファイルはすべて互換性のあるスキーマを共有する必要があります。

  BigQuery での Cloud Storage URI の使用について詳しくは、Cloud Storage リソースパスをご覧ください。

• PROJECT_ID: テーブルを作成するプロジェクトの名前（例: myproject）

• REGION: 接続を含むリージョン（us）

• CONNECTION_ID: 接続 ID（例: myconnection）。

  Google Cloud コンソールで接続の詳細を表示する場合、接続 ID は接続 ID に表示される完全修飾接続 ID の最後のセクションの値です（例: projects/myproject/locations/connection_location/connections/myconnection）。

• DATASET_NAME: BigLake テーブルを作成するデータセットの名前

• TABLE_NAME: BigLake テーブルの名前

• SCHEMA: BigLake テーブルのスキーマ

例:

bq mk --table \
    --external_table_definition=@CSV=gs://mybucket/*.parquet@projects/myproject/locations/us/connections/myconnection \
    --max_staleness=0-0 0 4:0:0 \
    myproject:mydataset.myexternaltable \
    Region:STRING,Quarter:STRING,Total_sales:INTEGER

API

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

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

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

Terraform

この例では、パーティション分割されていないデータに BigLake テーブルを作成します。

bigquery/biglake/bigquery_create_unpartitioned_biglake_table/main.tf

GitHub で表示 フィードバック

# This creates a bucket in the US region named "my-bucket" with a pseudorandom suffix.
resource "random_id" "default" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.default.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

# This queries the provider for project information.
data "google_project" "project" {}

# This creates a connection in the US region named "my-connection".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.project.id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This makes the script wait for seven minutes before proceeding.
# This lets IAM permissions propagate.
resource "time_sleep" "default" {
  create_duration = "7m"

  depends_on = [google_project_iam_member.default]
}

# This defines a Google BigQuery dataset with
# default expiration times for partitions and tables, a
# description, a location, and a maximum time travel.
resource "google_bigquery_dataset" "default" {
  dataset_id                      = "my_dataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "My dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  # This defines a map of labels for the bucket resource,
  # including the labels "billing_group" and "pii".
  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

# This creates a BigQuery Table with automatic metadata caching.
resource "google_bigquery_table" "default" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  table_id   = "my_table"
  schema = jsonencode([
    { "name" : "country", "type" : "STRING" },
    { "name" : "product", "type" : "STRING" },
    { "name" : "price", "type" : "INT64" }
  ])
  external_data_configuration {
    # This defines an external data configuration for the BigQuery table
    # that reads Parquet data from the publish directory of the default
    # Google Cloud Storage bucket.
    autodetect    = false
    source_format = "PARQUET"
    connection_id = google_bigquery_connection.default.name
    source_uris   = ["gs://${google_storage_bucket.default.name}/data/*"]
    # This enables automatic metadata refresh.
    metadata_cache_mode = "AUTOMATIC"
  }

  # This sets the maximum staleness of the metadata cache to 10 hours.
  max_staleness = "0-0 0 10:0:0"

  deletion_protection = false

  depends_on = [time_sleep.default]
}

Google Cloud プロジェクトで Terraform 構成を適用するには、次のセクションの手順を完了します。

Cloud Shell を準備する

1. Cloud Shell を起動します。

2. Terraform 構成を適用するデフォルトの Google Cloud プロジェクトを設定します。

   このコマンドは、プロジェクトごとに 1 回だけ実行する必要があります。これは任意のディレクトリで実行できます。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Terraform 構成ファイルに明示的な値を設定すると、環境変数がオーバーライドされます。

ディレクトリを準備する

Terraform 構成ファイルには独自のディレクトリ（ルート モジュールとも呼ばれます）が必要です。

1. Cloud Shell で、ディレクトリを作成し、そのディレクトリ内に新しいファイルを作成します。ファイルの拡張子は .tf にする必要があります（例: main.tf）。このチュートリアルでは、このファイルを main.tf とします。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. チュートリアルを使用している場合は、各セクションまたはステップのサンプルコードをコピーできます。

   新しく作成した main.tf にサンプルコードをコピーします。

   必要に応じて、GitHub からコードをコピーします。Terraform スニペットがエンドツーエンドのソリューションの一部である場合は、この方法をおすすめします。

3. 環境に適用するサンプル パラメータを確認し、変更します。
4. 変更を保存します。
5. Terraform を初期化します。これは、ディレクトリごとに 1 回だけ行います。

   terraform init

   最新バージョンの Google プロバイダを使用する場合は、-upgrade オプションを使用します。

   terraform init -upgrade

変更を適用する

1. 構成を確認して、Terraform が作成または更新するリソースが想定どおりであることを確認します。

   terraform plan

   必要に応じて構成を修正します。

2. 次のコマンドを実行します。プロンプトで「yes」と入力して、Terraform 構成を適用します。

   terraform apply

   Terraform に「Apply complete!」というメッセージが表示されるまで待ちます。

3. Google Cloud プロジェクトを開いて結果を表示します。Google Cloud コンソールの UI でリソースに移動して、Terraform によって作成または更新されたことを確認します。

注: Terraform のサンプルでは通常、必要な API が Google Cloud プロジェクトで有効になっていることを前提としています。

BigLake は、スキーマの自動検出をサポートしています。ただし、スキーマを指定せず、前の手順でサービス アカウントにアクセス権が付与されていない場合は、スキーマを自動検出しようとすると、アクセス拒否メッセージで手順が失敗します。

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

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

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

コンソール

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

   [BigQuery] に移動

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

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

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

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

   2. ワイルドカードを使用してフォルダへのパスを指定します。例: my_bucket/my_files* このフォルダは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在する必要があります。

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

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

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

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

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

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

   1. [プロジェクト] で、テーブルを作成するプロジェクトを選択します。
   2. [データセット] で、テーブルを作成するデータセットを選択します。
   3. [テーブル] に、作成するテーブルの名前を入力します。
   4. [テーブルタイプ] で [外部テーブル] を選択します。
   5. [Cloud リソース接続を使用して BigLake テーブルを作成する] チェックボックスをオンにします。
   6. [接続 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'],
     max_staleness = STALENESS_INTERVAL,
     metadata_cache_mode = 'CACHE_MODE',
     format ="TABLE_FORMAT"
   );
   

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

   • PROJECT_ID: テーブルを作成するプロジェクトの名前（例: myproject）
   • DATASET: テーブルを作成する BigQuery データセットの名前（例: mydataset）
   • EXTERNAL_TABLE_NAME: 作成するテーブルの名前（例: mytable）
   • PARTITION_COLUMN: パーティショニング列の名前。
   • PARTITION_COLUMN_TYPE: パーティショニング列の型
   • REGION: 接続を含むリージョン（例: us）
   • CONNECTION_ID: 接続 ID（例: myconnection）。

     Google Cloud コンソールで接続の詳細を表示する場合、接続 ID は接続 ID に表示される完全修飾接続 ID の最後のセクションの値です（例: projects/myproject/locations/connection_location/connections/myconnection）。

   • HIVE_PARTITION_URI_PREFIX: Hive パーティショニング URI 接頭辞（例: gs://mybucket/）
   • FILE_PATH: 作成する外部テーブルのデータソースへのパス（例: gs://mybucket/*.parquet）
   • STALENESS_INTERVAL: キャッシュ内のメタデータを BigLake テーブルに対するオペレーションで使用するかどうかを指定します。また、オペレーションがキャッシュ内のメタデータを使用するためにその鮮度を指定します。メタデータ キャッシュに関する考慮事項の詳細については、メタデータ キャッシュによるパフォーマンスの向上をご覧ください。

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

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

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

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

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

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

   • TABLE_FORMAT: 作成するテーブルの形式（例: PARQUET）

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

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

例

次の例では、パーティション分割データに対して BigLake テーブルを作成します。

• スキーマは自動検出されます。
• テーブルのメタデータ キャッシュの未更新間隔は 1 日です。
• メタデータ キャッシュは自動的に更新されます。

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

次の例では、パーティション分割データに対して BigLake テーブルを作成します。

• スキーマを指定します。
• テーブルのメタデータ キャッシュの未更新間隔は 8 時間です。
• メタデータ キャッシュは手動で更新する必要があります。

CREATE EXTERNAL TABLE `my_dataset.my_table`
(
  ProductId INTEGER,
  ProductName STRING,
  ProductType STRING
)
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "gs://mybucket/products",
  uris = ['gs://mybucket/products/*'],
  max_staleness = INTERVAL 8 HOUR,
  metadata_cache_mode = 'MANUAL'
);

bq

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

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

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

• SOURCE_FORMAT: 外部データソースの形式。例: CSV
• REGION: 接続を含むリージョン（例: us）。

• CONNECTION_ID: 接続 ID（例: myconnection）。

  Google Cloud コンソールで接続の詳細を表示する場合、接続 ID は接続 ID に表示される完全修飾接続 ID の最後のセクションの値です（例: projects/myproject/locations/connection_location/connections/myconnection）。

• PARTITIONING_MODE: Hive パーティショニング モード。次の値のいずれかを使用できます。

  • AUTO: キー名と型を自動的に検出します。
  • STRINGS: キー名を自動的に文字列に変換します。
  • CUSTOM: ソース URI 接頭辞でキースキーマをエンコードします。

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

• GCS_URIS: ワイルドカード形式を使用する Cloud Storage フォルダのパス。

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

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

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

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

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

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

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

• STALENESS_INTERVAL: キャッシュ内のメタデータを BigLake テーブルに対するオペレーションで使用するかどうかを指定します。また、オペレーションがキャッシュ内のメタデータを使用するためにその鮮度を指定します。このフラグを使用する場合は、前述の bq mkdef コマンドで --metadata_cache_mode フラグの値も指定している必要があります。メタデータ キャッシュに関する考慮事項の詳細については、メタデータ キャッシュによるパフォーマンスの向上をご覧ください。

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

  メタデータ キャッシュを有効にするには、INTERVAL データ型ドキュメントで説明されている Y-M D H:M:S 形式を使用して、30 分から 7 日の間隔値を指定します。たとえば、4 時間のステイルネス間隔に 0-0 0 4:0:0 を指定します。この値を指定すると、キャッシュに保存されたメタデータが過去 4 時間以内に更新されていれば、テーブルに対するオペレーションはそのメタデータを使用します。キャッシュに保存されているメタデータがそれより古い場合、オペレーションは代わりに Cloud Storage からメタデータを取得します。

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

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

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

例

次の例では、AUTO Hive パーティショニング モードを使用し、メタデータ キャッシュを 12 時間の未更新間隔に設定して自動的に更新するように設定しています。

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

bq mk --external_table_definition=mytable_def \
  --max_staleness=0-0 0 12:0:0 \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

次の例では、STRING Hive パーティショニング モードを使用します。

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=STRING \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
  gs://myBucket/myTable/* > mytable_def

bq mk --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

次の例では、CUSTOM Hive パーティショニング モードを使用します。

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=CUSTOM \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable/{dt:DATE}/{val:STRING} \
  gs://myBucket/myTable/* > mytable_def

bq mk --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 フィールドのパーティション キースキーマを次のように入力します。gs://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...

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

Terraform

この例では、パーティション分割データに BigLake テーブルを作成します。

bigquery/biglake/bigquery_create_partitioned_biglake_table/main.tf

GitHub で表示 フィードバック

# This creates a bucket in the US region named "my-bucket" with a pseudorandom
# suffix.
resource "random_id" "default" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.default.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

resource "google_storage_bucket_object" "default" {
  # This creates a fake message to create partition locations on the table.
  # Otherwise, the table deployment fails.
  name    = "publish/dt=2000-01-01/hr=00/min=00/fake_message.json"
  content = "{\"column1\": \"XXX\"}"
  bucket  = google_storage_bucket.default.name
}

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a connection in the US region named "my-connection".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.default.id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This makes the script wait for seven minutes before proceeding. This lets IAM
# permissions propagate.
resource "time_sleep" "default" {
  create_duration = "7m"

  depends_on = [google_project_iam_member.default]
}

# This defines a Google BigQuery dataset with default expiration times for
# partitions and tables, a description, a location, and a maximum time travel.
resource "google_bigquery_dataset" "default" {
  dataset_id                      = "my_dataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "My dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  # This defines a map of labels for the bucket resource,
  # including the labels "billing_group" and "pii".
  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

# This creates a BigQuery table with partitioning and automatic metadata
# caching.
resource "google_bigquery_table" "default" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  table_id   = "my_table"
  schema     = jsonencode([{ "name" : "column1", "type" : "STRING", "mode" : "NULLABLE" }])
  external_data_configuration {
    # This defines an external data configuration for the BigQuery table
    # that reads Parquet data from the publish directory of the default
    # Google Cloud Storage bucket.
    autodetect    = false
    source_format = "PARQUET"
    connection_id = google_bigquery_connection.default.name
    source_uris   = ["gs://${google_storage_bucket.default.name}/publish/*"]
    # This configures Hive partitioning for the BigQuery table,
    # partitioning the data by date and time.
    hive_partitioning_options {
      mode                     = "CUSTOM"
      source_uri_prefix        = "gs://${google_storage_bucket.default.name}/publish/{dt:STRING}/{hr:STRING}/{min:STRING}"
      require_partition_filter = false
    }
    # This enables automatic metadata refresh.
    metadata_cache_mode = "AUTOMATIC"
  }

  # This sets the maximum staleness of the metadata cache to 10 hours.
  max_staleness = "0-0 0 10:0:0"

  deletion_protection = false

  depends_on = [
    time_sleep.default,
    google_storage_bucket_object.default
  ]
}

Google Cloud プロジェクトで Terraform 構成を適用するには、次のセクションの手順を完了します。

Cloud Shell を準備する

1. Cloud Shell を起動します。

2. Terraform 構成を適用するデフォルトの Google Cloud プロジェクトを設定します。

   このコマンドは、プロジェクトごとに 1 回だけ実行する必要があります。これは任意のディレクトリで実行できます。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Terraform 構成ファイルに明示的な値を設定すると、環境変数がオーバーライドされます。

ディレクトリを準備する

Terraform 構成ファイルには独自のディレクトリ（ルート モジュールとも呼ばれます）が必要です。

1. Cloud Shell で、ディレクトリを作成し、そのディレクトリ内に新しいファイルを作成します。ファイルの拡張子は .tf にする必要があります（例: main.tf）。このチュートリアルでは、このファイルを main.tf とします。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. チュートリアルを使用している場合は、各セクションまたはステップのサンプルコードをコピーできます。

   新しく作成した main.tf にサンプルコードをコピーします。

   必要に応じて、GitHub からコードをコピーします。Terraform スニペットがエンドツーエンドのソリューションの一部である場合は、この方法をおすすめします。

3. 環境に適用するサンプル パラメータを確認し、変更します。
4. 変更を保存します。
5. Terraform を初期化します。これは、ディレクトリごとに 1 回だけ行います。

   terraform init

   最新バージョンの Google プロバイダを使用する場合は、-upgrade オプションを使用します。

   terraform init -upgrade

変更を適用する

1. 構成を確認して、Terraform が作成または更新するリソースが想定どおりであることを確認します。

   terraform plan

   必要に応じて構成を修正します。

2. 次のコマンドを実行します。プロンプトで「yes」と入力して、Terraform 構成を適用します。

   terraform apply

   Terraform に「Apply complete!」というメッセージが表示されるまで待ちます。

3. Google Cloud プロジェクトを開いて結果を表示します。Google Cloud コンソールの UI でリソースに移動して、Terraform によって作成または更新されたことを確認します。

注: Terraform のサンプルでは通常、必要な API が Google Cloud プロジェクトで有効になっていることを前提としています。

アクセス制御ポリシーを設定する

BigLake テーブルへのアクセスを制御する方法はいくつかあります。

• 列レベルのセキュリティの設定手順については、列レベルのセキュリティ ガイドをご覧ください。

• データ マスキングの設定手順については、データ マスキング ガイドをご覧ください。

• 行レベルのセキュリティの設定方法については、行レベルのセキュリティ ガイドをご覧ください。

たとえば、データセット mydataset 内のテーブル mytable に対する行アクセスを制限する必要があるとします。

+---------+---------+-------+
| country | product | price |
+---------+---------+-------+
| US      | phone   |   100 |
| JP      | tablet  |   300 |
| UK      | laptop  |   200 |
+---------+---------+-------+

Kim（[e-mail]）用に行レベルのフィルタを作成して、アクセス権を country が US の行だけに制限できます。

CREATE ROW ACCESS POLICY only_us_filter
ON mydataset.mytable
GRANT TO ('user:[e-mail]')
FILTER USING (country = 'US');

次に、Kim が次のクエリを実行すると:

SELECT * FROM projectid.mydataset.mytable;

出力には、country が US の行のみが表示されます。

+---------+---------+-------+
| country | product | price |
+---------+---------+-------+
| US      | phone   |   100 |
+---------+---------+-------+

BigLake テーブルに対してクエリを行う

詳細については、BigLake テーブルの Cloud Storage データに対してクエリを行うをご覧ください。

BigLake テーブルを更新する

必要に応じて、BigLake テーブルを更新できます。たとえば、メタデータ キャッシュを変更できます。ソース形式やソース URI など、テーブルの詳細情報を取得するには、テーブル情報の取得をご覧ください。

同じ手順で、外部テーブルを接続に関連付けることで、Cloud Storage ベースの外部テーブルを BigLake テーブルにアップグレードすることもできます。詳細については、外部テーブルを BigLake テーブルにアップグレードするをご覧ください。

BigLake テーブルを更新するには、次のいずれかのオプションを選択します。

SQL

CREATE OR REPLACE EXTERNAL TABLE DDL ステートメントを使用してテーブルを更新します。

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

   [BigQuery] に移動

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

   CREATE OR REPLACE EXTERNAL TABLE
     `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
     WITH CONNECTION `REGION.CONNECTION_ID`
     OPTIONS(
       format ="TABLE_FORMAT",
       uris = ['BUCKET_PATH'],
       max_staleness = STALENESS_INTERVAL,
       metadata_cache_mode = 'CACHE_MODE'
       );
   

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

   • PROJECT_ID: テーブルを含むプロジェクトの名前
   • DATASET: テーブルを含むデータセットの名前
   • EXTERNAL_TABLE_NAME: テーブルの名前
   • REGION: 接続を含むリージョン
   • CONNECTION_ID: 使用する接続の名前
   • TABLE_FORMAT: テーブルで使用される形式

     テーブルの更新時にこれを変更することはできません。

   • BUCKET_PATH: 外部テーブルのデータを含む Cloud Storage バケットへのパス（['gs://bucket_name/[folder_name/]file_name'] 形式）。

     パスにワイルドカードとしてアスタリスク（*）を 1 つ使用して、バケットから複数のファイルを選択することもできます。たとえば、['gs://mybucket/file_name*'] のようにします。詳細については、Cloud Storage の URI でのワイルドカードのサポートをご覧ください。

     複数のパスを指定して、uris オプションに複数のバケットを指定できます。

     次の例に、有効な uris 値を示します。

     • ['gs://bucket/path1/myfile.csv']
     • ['gs://bucket/path1/*.csv']
     • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

     複数のファイルをターゲットとする uris 値を指定する場合、それらのファイルはすべて互換性のあるスキーマを共有する必要があります。

     BigQuery での Cloud Storage URI の使用方法については、Cloud Storage リソースパスをご覧ください。

   • STALENESS_INTERVAL: キャッシュ内のメタデータをテーブルに対するオペレーションで使用するかどうかを指定します。また、オペレーションがキャッシュ内のメタデータを使用するためにその鮮度を指定します。

     メタデータ キャッシュに関する考慮事項の詳細については、メタデータ キャッシュによるパフォーマンスの向上をご覧ください。

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

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

   • CACHE_MODE: メタデータ キャッシュを自動的に更新するか手動で更新するかを指定します。

     メタデータ キャッシュに関する考慮事項の詳細については、メタデータ キャッシュのパフォーマンスをご覧ください。

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

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

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

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

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

bq

テーブルを更新するには、bq mkdef コマンドと bq update コマンドを使用します。

1. 変更するテーブルの要素を記述する外部テーブル定義を生成します。

   bq mkdef --connection_id=PROJECT_ID.REGION.CONNECTION_ID \
   --source_format=TABLE_FORMAT \
   --metadata_cache_mode=CACHE_MODE \
   "BUCKET_PATH" > /tmp/DEFINITION_FILE
   

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

   • PROJECT_ID: 接続を含むプロジェクトの名前。
   • REGION: 接続を含むリージョン。
   • CONNECTION_ID: 使用する接続の名前。
   • TABLE_FORMAT: テーブルで使用される形式。テーブルの更新時にこれを変更することはできません。

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

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

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

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

   • BUCKET_PATH: 外部テーブルのデータを含む Cloud Storage バケットへのパス（gs://bucket_name/[folder_name/]file_name 形式）。

     バケットから選択したファイルを制限するには、パスにワイルドカードとしてアスタリスク（*）を 1 つ指定します。たとえば、gs://mybucket/file_name* のようにします。詳細については、Cloud Storage の URI でのワイルドカードのサポートをご覧ください。

     複数のパスを指定して、uris オプションに複数のバケットを指定できます。

     次の例に、有効な uris 値を示します。

     • gs://bucket/path1/myfile.csv
     • gs://bucket/path1/*.csv
     • gs://bucket/path1/*,gs://bucket/path2/file00*

     複数のファイルをターゲットとする uris 値を指定する場合、それらのファイルはすべて互換性のあるスキーマを共有する必要があります。

     BigQuery での Cloud Storage URI の使用方法については、Cloud Storage リソースパスをご覧ください。

   • DEFINITION_FILE: 作成するテーブル定義ファイルの名前。

2. 新しい外部テーブルの定義を使用してテーブルを更新します。

   bq update --max_staleness=STALENESS_INTERVAL \
   --external_table_definition=/tmp/DEFINITION_FILE \
   PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME
   

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

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

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

     メタデータ キャッシュを有効にするには、INTERVAL データ型ドキュメントで説明されている Y-M D H:M:S 形式を使用して、30 分から 7 日の間隔値を指定します。たとえば、4 時間のステイルネス間隔の場合、0-0 0 4:0:0 を指定します。この値を指定すると、キャッシュに保存されたメタデータが過去 4 時間以内に更新されていれば、テーブルに対するオペレーションはそのメタデータを使用します。キャッシュに保存されたメタデータがそれより古い場合、オペレーションは代わりに Cloud Storage からメタデータを取得します。

   • DEFINITION_FILE: 作成または更新したテーブル定義ファイルの名前。

   • PROJECT_ID: テーブルを含むプロジェクトの名前。

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

   • EXTERNAL_TABLE_NAME: テーブルの名前。

例

次の例では、mytable を更新することで、キャッシュに保存されたメタデータが過去 4.5 時間以内に更新されていればそのメタデータを使用し、またキャッシュに保存されたメタデータの自動更新も行うようにします。

bq update --project_id=myproject --max_staleness='0-0 0 4:30:0' \
--external_table_definition=enable_metadata.json mydataset.mytable

ここで、enable_metadata.json の内容は { "metadataCacheMode": "AUTOMATIC" } です。

監査ロギング

BigQuery のロギングについては、BigQuery モニタリングの概要をご覧ください。Google Cloud のロギングの詳細については、Cloud Logging をご覧ください。

次のステップ

• BigLake の詳細を確認する。
• Cloud Storage について確認する。
• AWS データに対するクエリの実行について確認する。
• Azure データに対するクエリの実行について確認する。