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

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

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

Cloud Storage からオブジェクト情報を読み取るための接続を作成します。
接続に関連付けられているサービスアカウントに Cloud Storage 情報を読み取る権限を付与します。
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.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the BigQuery and BigQuery Connection API APIs.

Enable the APIs

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

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the BigQuery and BigQuery Connection API APIs.

Enable the APIs

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

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

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

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

SQL

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

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

[BigQuery] に移動
クエリエディタで次のステートメントを入力します。
```
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 を設定する必要があります。
[実行] をクリックします。

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

例

次の例では、メタデータキャッシュのステイルネス間隔が 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 です。各リソースの詳細については、BigQuery の Terraform のドキュメントをご覧ください。


# 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;

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

次のステップ

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

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

始める前に

必要なロール

必要な権限

必要な権限

必要な権限

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

SQL

bq

API

Terraform

Cloud Shell を準備する

ディレクトリを準備する

変更を適用する

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

次のステップ

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

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

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