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

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

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

料金

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

デフォルト構成

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

  • default_batch_query_queue_timeout_ms: バッチクエリがキューに入れられるデフォルトの時間（ミリ秒単位）。設定しなかった場合、デフォルトは 24 時間です。最小値は 1 ミリ秒です。最大値は 48 時間です。バッチクエリのキューイングをオフにするには、この値を -1 に設定します。
  • default_column_name_character_map: 列名の文字のデフォルトのスコープと処理。設定されていない場合、列名にサポートされていない文字を含む読み込みジョブは失敗し、エラー メッセージが返されます。古いテーブルの中には、列名でサポートされていない文字を置き換えるように設定されているものがあります。詳細については、load_option_list をご覧ください。
  • default_interactive_query_queue_timeout_ms: インタラクティブ クエリがキューに格納されるデフォルトの時間（ミリ秒単位）。設定しなかった場合、デフォルトは 6 時間です。最小値は 1 ミリ秒です。最大値は 48 時間です。インタラクティブ クエリのキューイングをオフにするには、この値を -1 に設定します。
  • default_kms_key_name: 一時テーブルまたは匿名テーブルなどのテーブルデータを暗号化するためのデフォルトの Cloud Key Management Service 鍵。詳細については、顧客管理の Cloud KMS 鍵をご覧ください。
  • default_query_job_timeout_ms: クエリジョブがタイムアウトするまでのデフォルトの時間（ジョブがキューに追加された時間や実行に費やされた時間など）。タイムアウト時間は 5 分～6 時間にする必要があります。

  • default_query_optimizer_options: 履歴ベースのクエリの最適化。このオプションは次のいずれかになります。

    • 'adaptive=on': 履歴ベースのクエリ最適化を使用します。
    • 'adaptive=off': 履歴ベースのクエリ最適化を使用しません。
    • NULL（デフォルト）: デフォルトの履歴ベースのクエリ最適化の設定を使用します（'adaptive=off' と同等）。

  • default_time_zone: タイムゾーンが引数として指定されていない場合に、タイムゾーンに依存する SQL 関数で使用するデフォルトのタイムゾーン。この構成は、時間単位の列パーティション分割テーブル（タイムゾーンとして UTC を使用）、Storage Transfer Service による転送スケジュール、bq コマンドライン ツールでのデータの読み込みには適用されません。詳細については、タイムゾーンをご覧ください。

  • default_storage_billing_model: 新しいデータセットのデフォルトのストレージ課金モデル。ストレージ料金の計算時に物理バイトを使用する場合は、値を PHYSICAL に設定します。論理バイトを使用する場合は LOGICAL に設定します。デフォルトのストレージ課金モデルを変更しても、既存のデータセットに影響はありません。詳細については、ストレージの課金モデルをご覧ください。

  • default_max_time_travel_hours: 新しいデータセットのデフォルトのタイムトラベル期間（時間）。この期間には 48～168 の範囲で、24 で割り切れる値を指定する必要があります。デフォルトの最大タイムトラベル時間を変更しても、既存のデータセットには影響しません。詳しくは、タイムトラベルをご覧ください。

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

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

必要な権限

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

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-REGION.default_storage_billing_model`= PHYSICAL,
  `region-REGION.default_max_time_travel_hours` = 72);

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

  • 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,
  `region-REGION.default_storage_billing_model`= NULL,
  `region-REGION.default_max_time_travel_hours` = 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,
  `region-REGION.default_storage_billing_model`= PHYSICAL,
  `region-REGION.default_max_time_travel_hours` = 72);

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

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,
  `region-REGION.default_storage_billing_model`= NULL,
  `region-REGION.default_max_time_travel_hours` = NULL);

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

構成値を取得する

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

新しい構成が有効になり、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;