デフォルトの接続の概要

ワークフローを簡素化するために、BigQuery でデフォルトのクラウドリソース接続を構成して、外部テーブルと BigQuery ML リモートモデルを作成できます。管理者がデフォルトの接続を構成すると、ユーザーはリソースの作成時に接続の詳細を指定しなくても、その接続を参照できます。

BigQuery は、次のリソースでデフォルトの接続をサポートしています。

デフォルトの接続を使用するには、次の SQL 句で DEFAULT キーワードを指定します。

CREATE EXTERNAL TABLE ステートメントの WITH CONNECTION 句
リモートモデルの CREATE MODEL ステートメントの REMOTE WITH CONNECTION 句

始める前に

Enable the BigQuery Connection API.

Enable the API

必要なロールと権限

デフォルトの接続を使用するには、次の Identity and Access Management（IAM）ロールを使用します。

デフォルトの接続を使用する: プロジェクトに対する BigQuery Connection ユーザー（roles/bigquery.connectionUser）
デフォルトの接続を設定する: プロジェクトに対する BigQuery 管理者（roles/bigquery.admin）
デフォルト接続のサービスアカウントに権限を付与する必要がある場合:
- デフォルトの接続を使用して外部テーブルを作成する場合: 外部テーブルで使用される Cloud Storage バケットに対するストレージ管理者（roles/storage.admin）。
- デフォルトの接続を使用してリモートモデルを作成する場合: Vertex AI エンドポイントを含むプロジェクトに対するプロジェクト IAM 管理者（roles/resourcemanager.projectIamAdmin）。次のタイプのリモートモデルの場合、これは現在のプロジェクトです。
  - Cloud AI サービスを介したリモートモデル。
  - モデル名をエンドポイントとして指定して作成した、Google モデルまたはパートナーモデルを介したリモートモデル。
  他のすべてのリモートモデルの場合、これはターゲットモデルがデプロイされる Vertex AI エンドポイントを含むプロジェクトです。
  
  リモートモデルを使用してオブジェクトテーブルの非構造化データを分析し、オブジェクトテーブルで使用する Cloud Storage バケットが Vertex AI エンドポイントとは異なるプロジェクトにある場合は、オブジェクトテーブルで使用される Cloud Storage バケットに対するストレージ管理者（roles/storage.admin）も必要です。
これらのロールが必要になるのは、デフォルトの接続として使用する接続を構成する管理者、またはサービスアカウントに適切なロールがまだ付与されていないデフォルトの接続を使用しているユーザーの場合のみです。詳細については、デフォルト接続を構成するをご覧ください。

これらの事前定義ロールには、このドキュメントのタスクを実行するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

デフォルトの接続を使用する: bigquery.connections.use
接続を作成する: bigquery.connections.*
デフォルトの接続を設定する: bigquery.config.*
外部テーブルの作成に使用されるデフォルトの接続に対するサービスアカウント権限を設定する: storage.buckets.getIamPolicy と storage.buckets.setIamPolicy
リモートモデルの作成に使用されるデフォルトの接続に対するサービスアカウント権限を設定する:
- resourcemanager.projects.getIamPolicy と resourcemanager.projects.setIamPolicy
- オブジェクトテーブルの非構造化データを処理するリモートモデルでデフォルトの接続が使用されている場合: storage.buckets.getIamPolicy と storage.buckets.setIamPolicy

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

デフォルトの接続を構成する

デフォルトの接続を初めて構成するには、次のいずれかの方法を使用します。

接続を作成し、接続のサービスアカウントに適切なロールを付与してから、接続をデフォルトの接続として設定します。

デフォルトの接続を作成して構成するユーザーには、必要に応じて BigQuery 管理者ロールとストレージ管理者ロールまたはプロジェクト IAM 管理者ロールが必要です。デフォルトの接続ユーザーには BigQuery Connection ユーザーロールが必要です。
接続を作成し、デフォルトの接続として設定します。デフォルトの接続が使用されると、サービスはデフォルトの接続のサービスアカウントに適切なロールを付与します。

デフォルトの接続を作成して設定するユーザーには、BigQuery 管理者のロールが必要です。デフォルトの接続ユーザーには、必要に応じて BigQuery Connection ユーザーロールと、ストレージ管理者またはプロジェクト IAM 管理者のロールが必要です。
サポートされているステートメントで DEFAULT キーワードを指定します。サービスは接続を作成し、接続のサービスアカウントに適切なロールを付与してから、接続をデフォルトの接続として設定します。

デフォルトの接続ユーザーには、必要に応じて BigQuery 管理者ロールとストレージ管理者ロールまたはプロジェクト IAM 管理者ロールが必要です。

プロジェクトのデフォルトの接続を設定する

ALTER PROJECT SET OPTIONS DDL ステートメントを使用して、プロジェクトのデフォルトの Cloud リソース接続を設定します。

次の例では、プロジェクトのデフォルトの接続を設定しています。

  ALTER PROJECT PROJECT_ID
  SET OPTIONS (
    `region-REGION.default_cloud_resource_connection_id` = CONNECTION_ID);

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

PROJECT_ID: デフォルトの接続を設定するプロジェクトの ID。
REGION: 接続のリージョン。
CONNECTION_ID: テーブルとモデルのデフォルトとして使用する接続の ID または名前。接続の ID または名前のみを指定し、名前または ID に付加されているプロジェクト ID とリージョン接頭辞を除外します。

プロジェクトのデフォルト接続の構成について詳しくは、デフォルト構成を管理するをご覧ください。

デフォルトの接続に対する権限のプロビジョニング

デフォルトの接続を使用して外部テーブルまたはリモートモデルを作成すると、デフォルトの接続のサービスアカウントに適切なロールがまだ付与されていない場合、Google Cloud はそのロールを付与します。外部テーブルまたはリモートモデルで使用される Cloud Storage または Vertex AI リソースに対する管理者権限がない場合、このアクションは失敗します。

デフォルトの接続のサービスアカウントには、次のロールが付与されます。

テーブルまたはモデルのタイプ	リモートリソース	接続のサービスアカウントに割り当てられたロール
Cloud Storage BigLake テーブル	Cloud Storage	`roles/storage.legacyBucketReader` `roles/storage.legacyObjectReader`
オブジェクトテーブル	Cloud Storage	`roles/storage.legacyBucketReader` `roles/storage.legacyObjectReader`
BigQuery の BigLake Iceberg テーブル	Cloud Storage	`roles/storage.legacyBucketWriter` `roles/storage.legacyObjectOwner`
Vertex AI モデルを介した BigQuery ML リモートモデル	Google 所有のモデル	`roles/aiplatform.user`
	Model Garden からエンドポイントにデプロイ可能
	ユーザーモデル
	ファインチューニングされたモデル	`roles/aiplatform.serviceAgent`
Cloud AI サービスを介した BigQuery ML リモートモデル	ドキュメントプロセッサ	`roles/documentai.apiUser`
	音声認識ツール	`roles/speech.serviceAgent`
	Cloud NLP	`roles/serviceusage.serviceUsageConsumer`
	Cloud Vision	`roles/serviceusage.serviceUsageConsumer`
	Cloud Translation	`roles/cloudtranslate.user`

`CONNECTION DEFAULT` を使用して外部テーブルを作成する

次の例は、BigQuery で WITH CONNECTION DEFAULT を指定して外部テーブルを作成する方法を示しています。

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

次の SQL 式は、デフォルトの接続を使用して Cloud Storage BigLake テーブルを作成します。

CREATE EXTERNAL TABLE PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME
WITH CONNECTION DEFAULT
OPTIONS (
  format = 'TABLE_FORMAT',
  uris = ['BUCKET_PATH']);

例: デフォルトの接続を使用してオブジェクトテーブルを作成する

次の SQL 式は、デフォルトの接続を使用してオブジェクトテーブルを作成します。

CREATE EXTERNAL TABLE PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME
WITH CONNECTION DEFAULT
OPTIONS (
  object_metadata = 'SIMPLE'
  uris = ['BUCKET_PATH']);

例: デフォルトの接続を使用して BigQuery に BigLake Iceberg テーブルを作成する

次の SQL 式は、デフォルトの接続を使用して BigQuery の BigLake Iceberg テーブルを作成します。

CREATE TABLE `myproject.tpch_clustered.nation` (
  n_nationkey integer,
  n_name string,
  n_regionkey integer,
  n_comment string)
CLUSTER BY n_nationkey
WITH CONNECTION DEFAULT
OPTIONS (
  file_format = 'PARQUET',
  table_format = 'ICEBERG',
  storage_uri = 'gs://mybucket/warehouse/nation');

`REMOTE WITH CONNECTION DEFAULT` を使用してリモートモデルを作成する

次の例は、BigQuery で REMOTE WITH CONNECTION DEFAULT を指定してリモートモデルを作成する方法を示しています。

例: Vertex AI モデルを介してリモートモデルを作成する

次の SQL 式は、デフォルトの接続を使用してリモートモデルを作成します。

CREATE OR REPLACE MODEL `mydataset.flash_model`
  REMOTE WITH CONNECTION DEFAULT
  OPTIONS(ENDPOINT = 'gemini-2.0-flash');

例: Cloud AI サービスを介してリモートモデルを作成する

次の SQL 式は、デフォルトの接続を使用して Cloud AI サービスを介してリモートモデルを作成します。

CREATE MODEL `project_id.mydataset.mymodel`
REMOTE WITH CONNECTION DEFAULT
 OPTIONS(REMOTE_SERVICE_TYPE = 'CLOUD_AI_VISION_V1')

例: HTTPS エンドポイントを使用してリモートモデルを作成する

次の SQL 式は、デフォルトの接続と HTTPS エンドポイントを使用してリモートモデルを作成します。

CREATE MODEL `project_id.mydataset.mymodel`
 INPUT(f1 INT64, f2 FLOAT64, f3 STRING, f4 ARRAY)
 OUTPUT(out1 INT64, out2 INT64)
 REMOTE WITH CONNECTION DEFAULT
 OPTIONS(ENDPOINT = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/endpoints/1234')

次のステップ

BigQuery のデフォルトの構成について学習する。