オブジェクト テーブルを作成する

このドキュメントでは、オブジェクト テーブルを作成して BigQuery の非構造化データにアクセスする方法について説明します。

オブジェクト テーブルを作成するには、次のタスクを完了する必要があります。

1. Cloud Storage からオブジェクト情報を読み取るための接続を作成します。
2. 接続に関連付けられているサービス アカウントに Cloud Storage 情報を読み取る権限を付与します。
3. CREATE EXTERNAL TABLE ステートメントを使用してオブジェクト テーブルを作成し、接続に関連付けます。

始める前に

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

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

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

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

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

   API を有効にする

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

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

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

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

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

   API を有効にする

8. BigQuery 管理者が接続を作成済みで、Cloud Storage へのアクセスを設定していることを確認します。

必要なロール

オブジェクト テーブルを操作するには、ユーザーは組織内でのロールに応じて次の IAM 権限が必要です。ユーザーロールの詳細については、セキュリティ モデルをご覧ください。権限付与の詳細については、リソースに対して付与可能なロールの表示をご覧ください。

• データレイク管理者

  Cloud Storage への接続に必要な権限を取得するには、プロジェクトの BigQuery 接続管理者（roles/bigquery.connectionAdmin）ロールの付与を管理者に依頼してください。

  Cloud Storage バケットの作成と管理に必要な権限を取得するには、プロジェクトのストレージ管理者（roles/storage.admin）ロールの付与を管理者に依頼してください。

  この事前定義ロールには、Cloud Storage への接続、および Cloud Storage バケットの作成と管理に必要な権限が含まれています。必要とされる正確な権限については、必要な権限セクションを開いてご確認ください。

  必要な権限

  • bigquery.connections.create
  • bigquery.connections.get
  • bigquery.connections.list
  • bigquery.connections.update
  • bigquery.connections.use
  • bigquery.connections.delete
  • storage.bucket.*
  • storage.object.*

• データ ウェアハウス管理者

  オブジェクト テーブルを作成するために必要な権限を取得するには、プロジェクトに対して次のロールを付与するよう管理者に依頼してください。

  • BigQuery データ編集者（roles/bigquery.dataEditor）のロール。
  • BigQuery 接続管理者（roles/bigquery.connectionAdmin）のロール。

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

  必要な権限

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

• データ アナリスト

  オブジェクト テーブルに対してクエリを実行するために必要な権限を取得するには、プロジェクトに対して次のロールを付与するよう管理者に依頼してください。

  • BigQuery データ閲覧者（roles/bigquery.dataViewer）のロール
  • BigQuery 接続ユーザー（roles/bigquery.connectionUser）のロール

  この事前定義ロールには、オブジェクト テーブルに対するクエリに必要な権限が含まれています。必要とされる正確な権限については、必要な権限セクションを開いてご確認ください。

  必要な権限

  • bigquery.jobs.create
  • bigquery.tables.get
  • bigquery.tables.getData
  • bigquery.readsessions.create

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

注意: データ アナリストへの次の権限の付与は、回避する必要があります。

• Cloud Storage から直接オブジェクトを読み取ることができる権限（Storage オブジェクト閲覧者 IAM ロールを参照）。この権限により、データ アナリストは、データ ウェアハウス管理者が設定したアクセス制御を回避できます。

• テーブルを接続にバインドできる権限（BigQuery 接続管理者など）。

  この権限により、データ アナリストは、アクセス制御が存在しない新しいオブジェクト テーブルを作成して、データ ウェアハウス管理者が設定した制御を回避できます。

オブジェクト テーブルを作成する

オブジェクト テーブルを作成する前に、そのテーブルを格納するデータセットが存在していることが必要です。詳細については、データセットの作成をご覧ください。

オブジェクト テーブルを作成するには:

SQL

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

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

   [BigQuery] に移動

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

   CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME`
   WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
   OPTIONS(
     object_metadata = 'SIMPLE',
     uris = ['BUCKET_PATH'[,...]],
     max_staleness = STALENESS_INTERVAL,
     metadata_cache_mode = 'CACHE_MODE');
   

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

   • PROJECT_ID: プロジェクト ID。
   • DATASET_ID: オブジェクト テーブルを格納するデータセットの ID。
   • TABLE_NAME: オブジェクト テーブルの名前。
   • REGION: 接続を含むリージョンまたはマルチリージョン。
   • CONNECTION_ID: このオブジェクト テーブルで使用するクラウド リソース接続の ID。この接続によって、Cloud Storage からデータを読み込むために使用されるサービス アカウントが決まります。

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

   • BUCKET_PATH: オブジェクト テーブルで表されるオブジェクトを含む Cloud Storage バケットへのパス。形式は ['gs://bucket_name/[folder_name/]*'] です。

     各パスでアスタリスク 1 つ（*）のワイルドカード文字を使用すると、オブジェクト テーブルに含まれるオブジェクトを制限できます。たとえば、バケットに複数のタイプの非構造化データが含まれている場合は、['gs://bucket_name/*.pdf'] を指定することで、PDF オブジェクトのみを含むオブジェクト テーブルを作成できます。詳細については、Cloud Storage の URI でのワイルドカードのサポートをご覧ください。

     ['gs://mybucket1/*', 'gs://mybucket2/folder5/*'] などの複数のパスを指定することで、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. [実行] をクリックします。

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

例

次の例では、メタデータ キャッシュのステイルネス間隔が 1 日のオブジェクト テーブルを作成します。

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://mybucket/*'],
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

次の例では、3 つの Cloud Storage バケット内のオブジェクトに対するオブジェクト テーブルを作成します。

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket1/*','gs://bucket2/folder1/*','gs://bucket3/*']
);

次の例では、Cloud Storage バケット内の PDF オブジェクトのみを含むオブジェクト テーブルを作成します。

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket1/*.pdf']
);

bq

bq mk コマンドを使用します。

bq mk --table \
--external_table_definition=[e-mail]_ID \
--object_metadata=SIMPLE \
--max_staleness=STALENESS_INTERVAL \
--metadata_cache_mode=CACHE_MODE \
PROJECT_ID:DATASET_ID.TABLE_NAME

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

• PROJECT_ID: プロジェクト ID。
• DATASET_ID: オブジェクト テーブルを格納するデータセットの ID。
• TABLE_NAME: オブジェクト テーブルの名前。
• REGION: 接続を含むリージョンまたはマルチリージョン。
• CONNECTION_ID: この外部テーブルで使用するクラウド リソース接続の ID。この接続によって、Cloud Storage からデータを読み込むために使用されるサービス アカウントが決まります。

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

• BUCKET_PATH: オブジェクト テーブルで表されるオブジェクトを含む Cloud Storage バケットへのパス。形式は gs://bucket_name/[folder_name/]* です。

  各パスでアスタリスク 1 つ（*）のワイルドカード文字を使用すると、オブジェクト テーブルに含まれるオブジェクトを制限できます。たとえば、バケットに複数のタイプの非構造化データが含まれている場合は、gs://bucket_name/*.pdf を指定することで、PDF オブジェクトのみを含むオブジェクト テーブルを作成できます。詳細については、Cloud Storage の URI でのワイルドカードのサポートをご覧ください。

  gs://mybucket1/*,gs://mybucket2/folder5/* などの複数のパスを指定することで、uris オプションに複数のバケットを指定できます。

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

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

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

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

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

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

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

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

例

次の例では、メタデータ キャッシュのステイルネス間隔が 1 日のオブジェクト テーブルを作成します。

bq mk --table \
--external_table_definition=gs://mybucket/*@us.my-connection \
--object_metadata=SIMPLE \
--max_staleness=0-0 1 0:0:0 \
--metadata_cache_mode=AUTOMATIC \
my_dataset.object_table

次の例では、3 つの Cloud Storage バケット内のオブジェクトに対するオブジェクト テーブルを作成します。

bq mk --table \
--external_table_definition=gs://bucket1/*,gs://bucket2/folder1/*,gs://bucket3/*@us.my-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

次の例では、Cloud Storage バケット内の PDF オブジェクトのみを含むオブジェクト テーブルを作成します。

bq mk --table \
--external_table_definition=gs://bucket1/*[e-mail]-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

API

tables.insert メソッドを呼び出します。渡す Table リソースに、objectMetadata フィールドが SIMPLE に設定された ExternalDataConfiguration オブジェクトを含めます。

次の例は、curl を使用してこのメソッドを呼び出す方法を示しています。

ACCESS_TOKEN=$(gcloud auth print-access-token) curl \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST \
-d '{"tableReference": {"projectId": "my_project", "datasetId": "my_dataset", "tableId": "object_table_name"}, "externalDataConfiguration": {"objectMetadata": "SIMPLE", "sourceUris": ["gs://mybucket/*"]}}' \
https://www.googleapis.com/bigquery/v2/projects/my_project/datasets/my_dataset/tables

Terraform

この例では、メタデータのキャッシュを有効にして、手動更新を使用したオブジェクト テーブルを作成します。

オブジェクト テーブルで指定する主なフィールドは google_bigquery_table.external_data_configuration.object_metadata、google_bigquery_table.external_data_configuration.metadata_cache_mode、google_bigquery_table.max_staleness です。各リソースの詳細については、BigQuery の Terraform のドキュメントをご覧ください。

bigquery/biglake/bigquery_create_object_table/main.tf

GitHub で表示 フィードバック

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

# This creates a connection in the US region named "my-connection-id".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection-id"
  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.project_id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This defines a Google BigQuery dataset.
resource "google_bigquery_dataset" "default" {
  dataset_id = "my_dataset_id"
}

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

# This defines a BigQuery object table with manual metadata caching.
resource "google_bigquery_table" "default" {
  deletion_protection = false
  table_id            = "my-table-id"
  dataset_id          = google_bigquery_dataset.default.dataset_id
  external_data_configuration {
    connection_id = google_bigquery_connection.default.name
    autodetect    = false
    # `object_metadata is` required for object tables. For more information, see
    # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/bigquery_table#object_metadata
    object_metadata = "SIMPLE"
    # This defines the source for the prior object table.
    source_uris = [
      "gs://${google_storage_bucket.default.name}/*",
    ]

    metadata_cache_mode = "MANUAL"
  }

  # This ensures that the connection can access the bucket
  # before Terraform creates a table.
  depends_on = [
    google_project_iam_member.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 プロジェクトで有効になっていることを前提としています。

クエリ オブジェクト テーブル

オブジェクト テーブルは、他の BigQuery と同様にクエリできます。次に例を示します。

SELECT *
FROM mydataset.myobjecttable;

オブジェクト テーブルに対してクエリを実行すると、基盤となるオブジェクトのメタデータが返されます。詳細については、オブジェクト テーブル スキーマをご覧ください。

次のステップ

• 画像オブジェクト テーブルで推論を実行する方法を確認する。
• リモート関数を使用してオブジェクト テーブルを分析する方法を学習する。