Cloud Storage 用の BigLake 外部テーブルを作成する

コンソール

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

   BigQuery に移動

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

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

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

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

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 Console で接続の詳細を表示する場合、[接続 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 Console で接続の詳細を表示する場合、[接続 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 に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

# 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 によって作成または更新されたことを確認します。

コンソール

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

   BigQuery に移動

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

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

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. [スキーマ] セクションで、[自動検出] オプションを選択してスキーマの自動検出を有効にします。

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

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

例

次の例では、パーティション分割データに対して 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 Console で接続の詳細を表示する場合、[接続 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 に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

# 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 によって作成または更新されたことを確認します。

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

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

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" } です。