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

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

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

オブジェクトテーブルを含むデータセットを作成します。
Cloud Storage からオブジェクト情報を読み取るための接続を作成します。
接続に関連付けられたサービスアカウントに Storage オブジェクト閲覧者（roles/storage.objectViewer）ロールを付与します。
CREATE EXTERNAL TABLE ステートメントを使用してオブジェクトテーブルを作成し、接続に関連付けます。

始める前に

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.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and BigQuery Connection API APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and BigQuery Connection API APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

必要なロール

オブジェクトテーブルを作成するには、プロジェクトに対する次のロールが必要です。

データセットとテーブルを作成するには、BigQuery データ編集者（roles/bigquery.dataEditor）のロールが必要です。
接続を作成するには、BigQuery 接続管理者（roles/bigquery.connectionAdmin）のロールが必要です。
接続のサービスアカウントにロールを付与するには、プロジェクト IAM 管理者（roles/resourcemanager.projectIamAdmin）が必要です。

オブジェクトテーブルに対してクエリを実行するには、プロジェクトに対する次のロールが必要です。

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

必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

bigquery.datasets.create
bigquery.tables.create
bigquery.tables.update
bigquery.connections.create
bigquery.connections.get
bigquery.connections.list
bigquery.connections.update
bigquery.connections.use
bigquery.connections.delete
bigquery.connections.delegate
storage.bucket.*
storage.object.*
bigquery.jobs.create
bigquery.tables.get
bigquery.tables.getData
bigquery.readsessions.create

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

データセットを作成する

オブジェクトテーブルを格納する BigQuery データセットを作成します。

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

[BigQuery] に移動
左側のペインで、 [エクスプローラ] をクリックします。

左側のペインが表示されていない場合は、 [左ペインを開く] をクリックしてペインを開きます。
[エクスプローラ] ペインで、プロジェクト名をクリックします。
[アクションを表示] > [データセットを作成] をクリックします。
[データセットを作成する] ページで、次の操作を行います。
1. [データセット ID] にデータセットの名前を入力します。
2. [ロケーションタイプ] で、[リージョン] または [マルチリージョン] を選択します。
  - [リージョン] を選択した場合は、[リージョン] リストからロケーションを選択します。
  - [マルチリージョン] を選択した場合は、[マルチリージョン] リストから [US] または [ヨーロッパ] を選択します。
3. [データセットを作成] をクリックします。

接続を作成する

デフォルトの接続が構成されているか、BigQuery 管理者ロールが付与されている場合は、この手順をスキップできます。

オブジェクトテーブル��使用する Cloud リソース接続を作成し、接続のサービスアカウントを取得します。

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

[BigQuery] に移動
左側のペインで、 [エクスプローラ] をクリックします。
[エクスプローラ] ペインで、 [データを追加] をクリックします。

[データを追加] ダイアログが開きます。
[フィルタ条件] ペインの [データソースのタイプ] セクションで、[ビジネスアプリケーション] を選択します。

または、[データソースを検索] フィールドに「Vertex AI」と入力します。
[特徴量データソース] セクションで、[Vertex AI] をクリックします。
[Vertex AI モデル: BigQuery フェデレーション] ソリューションカードをクリックします。
[接続タイプ] リストで、[Vertex AI リモートモデル、リモート関数、BigLake、Spanner（Cloud リソース）] を選択します。
[接続 ID] フィールドに、接続の名前を入力します。
[ロケーションタイプ] で、[リージョン] または [マルチリージョン] を選択します。
- [リージョン] を選択した場合は、[リージョン] リストからロケーションを選択します。
- [マルチリージョン] を選択した場合は、[マルチリージョン] リストから [US] または [ヨーロッパ] を選択します。
[接続を作成] をクリックします。
[接続へ移動] をクリックします。
[接続情報] ペインで、次の手順で使用するサービスアカウント ID をコピーします。

サービスアカウントにアクセス権を付与する

接続のサービスアカウントに Storage オブジェクト閲覧者のロールを付与します。

コンソール

[IAM と管理] ページに移動します。

[IAM と管理] に移動
[追加] をクリックします。

[プリンシパルを追加] ダイアログが開きます。
[新しいプリンシパル] フィールドに、前の手順でコピーしたサービスアカウント ID を入力します。
[ロールを選択] フィールドで、[Cloud Storage] を選択し、続いて [Storage オブジェクト閲覧者] を選択します。
[保存] をクリックします。

gcloud

gcloud projects add-iam-policy-binding コマンドを使用します。

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None

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

PROJECT_NUMBER: ロールを付与するプロジェクトのプロジェクト番号。
MEMBER: 先ほどコピーしたサービスアカウント ID。

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

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

SQL

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

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

[BigQuery] に移動
クエリエディタで次のステートメントを入力します。
```
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME`
WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID`| DEFAULT}
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）。
  
  デフォルトの接続を使用するには、PROJECT_ID.REGION.CONNECTION_ID を含む接続文字列ではなく、DEFAULT を指定します。
- 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 を設定する必要があります。
[実行] をクリックします。

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

例

次の例では、メタデータキャッシュのステイルネス間隔が 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=BUCKET_PATH@REGION.CONNECTION_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/*.pdf@us.my-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

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアントライブラリの認証を設定するをご覧ください。

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


# 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 を準備する

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

このコマンドは、プロジェクトごとに 1 回だけ実行する必要があります。これは任意のディレクトリで実行できます。
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
Terraform 構成ファイルに明示的な値を設定すると、環境変数がオーバーライドされます。

ディレクトリを準備する

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

Cloud Shell で、ディレクトリを作成し、そのディレクトリ内に新しいファイルを作成します。ファイルの拡張子は .tf にする必要があります（例: main.tf）。このチュートリアルでは、このファイルを main.tf とします。
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
チュートリアルを使用している場合は、各セクションまたはステップのサンプルコードをコピーできます。

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

必要に応じて、GitHub からコードをコピーします。Terraform スニペットがエンドツーエンドのソリューションの一部である場合は、この方法をおすすめします。
環境に適用するサンプルパラメータを確認し、変更します。
変更を保存します。
Terraform を初期化します。これは、ディレクトリごとに 1 回だけ行います。
```
terraform init
```
最新バージョンの Google プロバイダを使用する場合は、-upgrade オプションを使用します。
```
terraform init -upgrade
```

変更を適用する

構成を確認して、Terraform が作成または更新するリソースが想定どおりであることを確認します。
```
terraform plan
```
必要に応じて構成を修正します。
次のコマンドを実行します。プロンプトで「yes」と入力して、Terraform 構成を適用します。
```
terraform apply
```
Terraform に「Apply complete!」というメッセージが表示されるまで待ちます。
Google Cloud プロジェクトを開いて結果を表示します。 Google Cloud コンソールの UI でリソースに移動して、Terraform によって作成または更新されたことを確認します。

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

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

SELECT *
FROM mydataset.myobjecttable;

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

次のステップ

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

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

始める前に

必要なロール

必要な権限

データセットを作成する

接続を作成する

サービス アカウントにアクセス権を付与する

コンソール

gcloud

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

SQL

bq

API

Terraform

Cloud Shell を準備する

ディレクトリを準備する

変更を適用する

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

次のステップ

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

サービスアカウントにアクセス権を付与する

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

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