デフォルト構成を管理する

このドキュメントでは、組織レベルまたはプロジェクト レベルでデフォルトの構成設定を作成および取得する方法について説明します。

ジョブを管理しやすくするために、BigQuery 内でデフォルト設定を構成できます。このサービスを使用する設定は、組織レベルまはプロジェクト レベルで構成されますが、セッション レベルまたはジョブレベルでオーバーライドできます。関連する組織のポリシーと組み合わせてデフォルト設定を構成すると、デフォルトの動作を適用できます。

料金

BigQuery 構成サービスの使用には追加料金は発生しません。詳細は、料金をご覧ください。

デフォルト構成

次の設定のデフォルト構成を指定できます。

• default_time_zone: タイムゾーンが引数として指定されていない場合に、タイムゾーンに依存する SQL 関数で使用するデフォルトのタイムゾーン。この構成は、時間単位の列パーティション分割テーブル（タイムゾーンとして UTC を使用）、Storage Transfer Service による転送スケジュール、bq コマンドライン ツールでのデータの読み込みには適用されません。詳細については、タイムゾーンをご覧ください。
• default_kms_key_name: 一時テーブルまたは匿名テーブルなどのテーブルデータを暗号化するためのデフォルトの Cloud Key Management Service 鍵。詳細については、顧客管理の Cloud KMS 鍵をご覧ください。
• default_query_job_timeout_ms: クエリジョブがタイムアウトするまでのデフォルトの時間（ジョブがキューに追加された時間や実行に費やされた時間など）。タイムアウト時間は 5 分～6 時間にする必要があります。
• default_interactive_query_queue_timeout_ms: インタラクティブ クエリがキューに格納されるデフォルトの時間（ミリ秒単位）。設定しなかった場合、デフォルトは 6 時間です。最小値は 1 ミリ秒です。最大値は 48 時間です。インタラクティブ クエリのキューイングをオフにするには、この値を -1 に設定します。
• default_batch_query_queue_timeout_ms: バッチクエリがキューに入れられるデフォルトの時間（ミリ秒単位）。設定しなかった場合、デフォルトは 24 時間です。最小値は 1 ミリ秒です。最大値は 48 時間です。バッチクエリのキューイングをオフにするには、この値を -1 に設定します。

デフォルト構成を作成する

このセクションでは、構成の作成方法について説明します。

必要な権限

構成を作成するには、bigquery.config.update Identity and Access Management（IAM）権限が必要です。事前定義された IAM ロールの roles/bigquery.admin には、ビューの作成に必要な権限が含まれています。

警告: デフォルトの Cloud Key Management Service 鍵を設定する場合は、プロジェクトまたは組織内で使用されているすべての BigQuery サービス アカウントに暗号化 / 復号のロールを付与する必要があります。プロジェクトまたは組織内のサービス アカウントに適切な権限がない場合、サービス アカウント内のすべてのクエリが失敗します。暗号化 / 復号のロールを割り当てるには、暗号化 / 復号のロールを割り当てるをご覧ください。最初に適切なロールを割り当てずに、デフォルトの Cloud Key Management Service 鍵を誤って設定した場合は、値を NULL に設定することでデフォルトの鍵をクリアできます。例については、このドキュメントの組織の設定を構成するとプロジェクトの構成をご覧ください。同様に、デフォルトのタイムゾーンを設定する場合は、DATETIME リテラルを使用する既存のクエリに影響が及ばないようにしてください。これには、明示的な DATETIME キーワードを使用したクエリ、パラメータとして時間関数（DATETIME_DIFF('2022-10-01', ...)、PARSE_DATETIME() 関数など）に渡される、暗黙的に変換された文字列リテラルが含まれます。このため、新しいプロジェクトでは default_time_zone パラメータのみを設定する方が安全です。

BigQuery での IAM のロールと権限については、事前定義ロールと権限をご覧ください。

デフォルトの設定を構成する

次の SQL ステートメントを使用して、組織レベルまたはプロジェクト レベルでデフォルトの設定を構成できます。構成を作成するときに、構成を適用するリージョンを指定する必要があります。ステートメントごとに使用できるリージョンは 1 つのみです。

組織の設定を構成する

組織設定を構成するには、ALTER ORGANIZATION SET OPTIONS DDL ステートメントを使用します。次の例では、デフォルトのタイムゾーンを America/Chicago、デフォルトの Cloud KMS 鍵をユーザー定義、デフォルトのクエリ タイムアウトを 30 分、デフォルトのインタラクティブ クエリキューのタイムアウトを 10 分、デフォルトのバッチクエリ キューのタイムアウトを 20 分に設定しています。

ALTER ORGANIZATION
SET OPTIONS (
  `region-REGION.default_time_zone`= 'America/Chicago',
  -- Ensure all service accounts under the organization have permission to KMS_KEY
  `region-REGION.default_kms_key_name` = KMS_KEY,
  `region-REGION.default_query_job_timeout_ms` = 1800000,
  `region-REGION.default_interactive_query_queue_timeout_ms` = 600000,
  `region-REGION.default_batch_query_queue_timeout_ms` = 1200000);

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

• REGION: プロジェクトまたは組織に関連付けられたリージョン。たとえば、us や europe-west6 です。
• KMS_KEY: ユーザー定義の Cloud KMS 鍵。Cloud KMS 鍵の詳細については、顧客管理の Cloud KMS 鍵をご覧ください。

次の例では、組織レベルのデフォルト設定をすべてクリアしています。

ALTER ORGANIZATION
SET OPTIONS (
  `region-REGION.default_time_zone` = NULL,
  `region-REGION.default_kms_key_name` = NULL,
  `region-REGION.default_query_job_timeout_ms` = NULL,
  `region-REGION.default_interactive_query_queue_timeout_ms` = NULL,
  `region-REGION.default_batch_query_queue_timeout_ms` = NULL);

プロジェクトを構成する

プロジェクトを構成するには、ALTER PROJECT SET OPTIONS DDL ステートメントを使用します。ALTER PROJECT SET OPTIONS DDL ステートメントは、必要に応じて project_id 変数を受け入れます。project_id が指定されていない場合、デフォルトはクエリが実行される現在のプロジェクトです。次の例では、デフォルトのタイムゾーンを America/Los_Angeles、デフォルトの Cloud KMS 鍵をサンプル鍵、デフォルトのクエリ タイムアウトを 1 時間、デフォルトのインタラクティブ クエリキューのタイムアウトを 10 分、デフォルトのバッチクエリ キューのタイムアウトを 20 分に設定しています。

ALTER PROJECT project_id
SET OPTIONS (
  `region-REGION.default_time_zone` = 'America/Los_Angeles',
  -- Ensure all service accounts under the project have permission to KMS_KEY
  `region-REGION.default_kms_key_name` = KMS_KEY,
  `region-REGION.default_query_job_timeout_ms` = 3600000,
  `region-REGION.default_interactive_query_queue_timeout_ms` = 600000,
  `region-REGION.default_batch_query_queue_timeout_ms` = 1200000);

次の例では、プロジェクト レベルのデフォルト設定をすべてクリアしています。デフォルト設定では、組織レベルのデフォルト設定が存在する場合は、それを使用します。それ以外の場合、すべてのデフォルト設定はすべてグローバルのデフォルトに設定されます。

ALTER PROJECT project_id
SET OPTIONS (
  `region-REGION.default_time_zone` = NULL,
  `region-REGION.default_kms_key_name` = NULL,
  `region-REGION.default_query_job_timeout_ms` = NULL,
  `region-REGION.default_interactive_query_queue_timeout_ms` = NULL,
  `region-REGION.default_batch_query_queue_timeout_ms` = NULL);

プロジェクト レベルの構成は、組織レベルの構成をオーバーライドします。また、プロジェクト レベルの構成よりもセッション レベルの構成が優先され、さらにジョブレベルの構成の方が優先されます。

構成値を取得する

組織またはプロジェクトのデフォルトの構成設定を確認するには、情報スキーマを確認します。クエリには 3 種類のビューがあります。

• INFORMATION_SCHEMA.PROJECT_OPTIONS: プロジェクトに適用される構成
• INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS: プロジェクトに適用される有効な構成。有効な構成には、プロジェクト レベルで設定されたすべての構成と、プロジェクトが組織から継承されたすべての設定が含まれます。
• INFORMATION_SCHEMA.ORGANIZATION_OPTIONS: 組織に適用される構成

新しい構成が有効になり、INFORMATION_SCHEMA ビューに反映されるまでには、数分かかることがあります。

必要な権限

構成値を取得するには、bigquery.config.get IAM 権限が必要です。

以下の各事前定義 IAM ロールには、INFORMATION_SCHEMA ビューから構成を取得するために必要な権限が含まれています。

• roles/bigquery.jobUser
• roles/bigquery.dataEditor
• roles/bigquery.dataUser

BigQuery での IAM のロールと権限については、事前定義ロールと権限をご覧ください。

例

us リージョンの組織の構成を表示するには、次のクエリを実行します。

SELECT * FROM region-us.INFORMATION_SCHEMA.ORGANIZATION_OPTIONS;

us リージョンのデフォルト プロジェクトで有効になっている構成を表示するには、次のクエリを実行します。

SELECT * FROM region-us.INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS;

us リージョンのデフォルト プロジェクトの構成を表示するには、次のクエリを実行します。

SELECT * FROM region-us.INFORMATION_SCHEMA.PROJECT_OPTIONS;