クエリキューを使用する

BigQuery では、同時実行が可能なクエリの数（動的同時実行）が自動的に決定されます。追加のクエリは、処理リソースが使用可能になるまでキューに入れられます。このドキュメントでは、最大同時実行目標数を管理し、インタラクティブクエリとバッチクエリのキュータイムアウトを設定する方法について説明します。

概要

BigQuery では、同時に実行できるクエリの数が、使用可能なコンピューティングリソースに基づいて動的に決定されます。同時に実行できるクエリの数は、オンデマンドプロジェクトまたは予約ごとに計算されます。それ以上のクエリは、実行の開始に十分な容量が確保されるまで、キューに配置されます。プロジェクトがオンデマンドか予約を使用するかに関係なく、キューの長さは、プロジェクトごと、リージョンごとに 1,000 回のインタラクティブクエリと 20,000 回のバッチクエリに制限されています。次の例では、計算されたクエリの同時実行数が 202 である場合のオンデマンドプロジェクトの動作を示します。

202 件の同時クエリに、キューに登録されたクエリ、エラーを返すクエリが続きます。

予約の場合は、各クエリには最小数のスロットが割り当てられるように、1 つの予約で同時に実行できるクエリの数の上限である最大同時実行目標数を設定することもできます。オンデマンドプロジェクトでは最大同時実行目標数を指定できません。これは常に動的に計算されます。

キューイングの動作

BigQuery では、フェアスケジューリングを適用して、単一のプロジェクトで予約のすべてのスロットを消費できないようにします。

同時実行数の共有が最も少ないプロジェクトからのクエリは、最初にキューから外されます。実行中、スロットはプロジェクト間で均等に分配されてから、プロジェクト内のジョブ間で分配されます。

たとえば、A と B の 2 つのプロジェクトに割り当てられている予約があるとします。BigQuery は予約の同時実行数を 5 と計算します。プロジェクト A には 4 つの同時実行中のクエリがあり、プロジェクト B には 1 つの実行中のクエリがあり、他のクエリはキューに入っています。プロジェクト B のクエリは、それがプロジェクト A のクエリの後に送信された場合でも、最初にキューから外されます。クエリの実行を開始すると、そのクエリは共有予約の中で、スロットの公平な割り当てを受けます。

BigQuery では、同時実行クエリの合計数に加えて、オンデマンドプロジェクトまたは予約ごとに実行する同時実行バッチクエリの最大数を動的に決定します。同時に実行されるバッチクエリの数がこの上限に達すると、インタラクティブクエリが優先されます（後で送信された場合でも）。

予約を削除すると、キュー内のすべてのクエリがタイムアウトします。予約に割り当てられたプロジェクトが別の予約に再割り当てされると、キューに入っているリクエストや実行中のリクエストは、引き続き古い予約で継続し、新しいリクエストはすべて新しい予約で実行されます。予約に割り当てられているプロジェクトが予約から削除されると、実行中のクエリは予約内で続行され、新しいリクエストとキューに入れられたリクエストはオンデマンドモデルを使用して実行されます。実行中のクエリジョブやキューに入れられたクエリジョブは、必要に応じてキャンセルできます。

キューのタイムアウトを制御する

インタラクティブクエリまたはバッチクエリのキュータイムアウトを制御するには、ALTER PROJECT SET OPTIONS ステートメントまたは ALTER ORGANIZATION SET OPTIONS ステートメントを使用して、プロジェクトまたは組織のデフォルト構成で default_interactive_query_queue_timeout_ms フィールドまたは default_batch_query_queue_timeout_ms フィールドを設定します。

プロジェクト内のインタラクティブクエリやバッチクエリのキュータイムアウトを表示するには、INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS ビューをクエリします。

キューイングを無効にするには、キューのタイムアウトを -1 に設定します。クエリの同時実行の最大数に達すると、追加のクエリは ADMISSION_DENIED エラーで失敗します。

最大同時実行目標数を設定する

最大同時実行目標数は、予約の作成時に手動で設定できます。デフォルトの最大同時実行目標数は 0 であり、BigQuery は使用可能なリソースに基づいて同時実行数を動的に決定します。目標数を 0 以外に設定すると、同時実行目標数により、予約で同時に実行されるクエリ数の上限が指定され、実行する各クエリで使用可能な最小スロット容量が保証されます。

最大同時実行数を増やしても、より多くのクエリが同時に実行されるとは限りません。実際の同時実行数は、予約にスロットを追加することで増やすことができるコンピューティングリソースによって変わります。

必要なロール

新しい予約で同時実行数を設定するために必要な権限を取得するには、コミットメントの所有権を保持する管理プロジェクトに対する BigQuery リソース編集者（roles/bigquery.resourceEditor）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

この事前定義ロールには、新しい予約で同時実行を設定するために必要な bigquery.reservations.create 権限が含まれています。

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

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

予約の最大同時実行目標数を設定する

次のオプションのいずれかを選択します。

コンソール

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

[BigQuery] に移動
ナビゲーションメニューで [容量管理] セクションに移動します。
[予約を作成] をクリックします。
予約設定を選択します。
[詳細設定] セクションを開くには、展開矢印をクリックします。
ターゲットジョブの同時実行数を設定するには、[自動のターゲットジョブ同時実行をオーバーライドする] トグルをオンに切り替えて、ターゲットジョブ同時実行を入力します。
[保存] をクリックします。

SQL

新しい予約の最大同時実行目標数を設定するには、CREATE RESERVATION DDL ステートメントを使用して、target_job_concurrency フィールドを設定します。

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

[BigQuery] に移動
クエリエディタで次のステートメントを入力します。
```
CREATE RESERVATION `ADMIN_PROJECT_ID.LOCATION.RESERVATION_NAME`
  OPTIONS (
    target_job_concurrency = CONCURRENCY);
```
次のように置き換えます。
- ADMIN_PROJECT_ID: 予約を有するプロジェクト
- LOCATION: 予約のロケーション（region-us など）
- RESERVATION_NAME: 予約の名前
- CONCURRENCY: 最大同時実行目標数
[実行] をクリックします。

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

bq

新しい予約の最大同時実行目標数を設定するには、bq mk コマンドを実行します。

bq mk \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --target_job_concurrency=CONCURRENCY \
    --reservation \
    RESERVATION_NAME

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

ADMIN_PROJECT_ID: 予約を有するプロジェクト
LOCATION: 予約のロケーション
CONCURRENCY: 最大同時実行目標数
RESERVATION_NAME: 予約の名前

API

BigQuery Reservation API で最大同時実行目標数を設定するには、予約リソースで concurrency フィールドを設定して、CreateReservationRequest メソッドを呼び出します。

最大同時実行目標数を更新する

最大同時実行目標数は、いつでも更新できます。ただし、目標数を増やしても、より多くのクエリが同時に実行されるとは限りません。実際の同時実行数は、使用可能なリソースによって変わります。最大同時実行目標数を少なくしても、現在実行中のクエリは影響を受けず、キュー内のクエリは同時実行クエリの数が新しい目標数を下回るまで実行されません。

最大同時実行目標数を 0 に設定すると、BigQuery は使用可能なリソースに基づいて同時実行数を動的に決定します（デフォルトの動作）。

必要なロール

予約の最大同時実行目標数を更新するために必要な権限を取得するには、コミットメントの所有権を保持する管理プロジェクトに対する BigQuery リソース編集者（roles/bigquery.resourceEditor）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

この事前定義ロールには、予約の最大同時実行目標数を更新するために必要な bigquery.reservations.update 権限が含まれています。

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

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

予約の最大同時実行目標数を更新する

次のオプションのいずれかを選択します。

コンソール

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

[BigQuery] に移動
ナビゲーションメニューで [容量管理] セクションに移動します。
[スロットの予約] タブをクリックします。
更新する予約を見つけます。
[アクション] オプションを開きます。
[編集] をクリックします。
[詳細設定] セクションを開くには、展開矢印をクリックします。
ターゲットジョブの同時実行数を設定するには、[自動のターゲットジョブ同時実行をオーバーライドする] トグルをオンに切り替えて、ターゲットジョブ同時実行を入力します。
[保存] をクリックします。

SQL

既存の予約の最大同時実行目標数を更新するには、ALTER RESERVATION DDL ステートメントを使用して、target_job_concurrency フィールドを設定します。

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

[BigQuery] に移動
クエリエディタで次のステートメントを入力します。
```
ALTER RESERVATION `ADMIN_PROJECT_ID.LOCATION.RESERVATION_NAME`
SET OPTIONS (
  target_job_concurrency = CONCURRENCY);
```
次のように置き換えます。
- ADMIN_PROJECT_ID: 予約を有するプロジェクト
- LOCATION: 予約のロケーション（region-us など）
- RESERVATION_NAME: 予約の名前
- CONCURRENCY: 最大同時実行目標数
[実行] をクリックします。

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

bq

既存の予約の最大同時実行目標数を更新するには、bq update コマンドを実行します。

bq update \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --target_job_concurrency=CONCURRENCY \
    --reservation \
    RESERVATION_NAME

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

ADMIN_PROJECT_ID: 予約を有するプロジェクト
LOCATION: 予約のロケーション
CONCURRENCY: 最大同時実行目標数
RESERVATION_NAME: 予約の名前

API

BigQuery Reservation API で最大同時実行目標数を更新するには、予約リソースで concurrency フィールドを設定して、UpdateReservationRequest メソッドを呼び出します。

モニタリング

実行中のクエリとキューに入っているクエリは、INFORMATION_SCHEMA.JOBS_BY_* ビューと INFORMATION_SCHEMA.JOBS_TIMELINE_BY_* ビューで確認できます。state フィールドは、アクティブに実行されているクエリの場合は RUNNING に、キューに入っているクエリの場合は PENDING に設定されます。

直近の 1 日で、1 秒あたりの動的同時実行しきい値に達したときに実行された同時実行クエリの数を表示するには、次のクエリを実行します。

SELECT
  t1.period_start,
  t1.job_count AS dynamic_concurrency_threshold
FROM (
  SELECT
    period_start,
    state,
    COUNT(DISTINCT job_id) AS job_count
  FROM
    `PROJECT_ID.REGION_ID`.INFORMATION_SCHEMA.JOBS_TIMELINE
  WHERE
    period_start BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
    AND CURRENT_TIMESTAMP()
    AND reservation_id = "RESERVATION_ID"
  GROUP BY
    period_start,
    state) AS t1
JOIN (
  SELECT
    period_start,
    state,
    COUNT(DISTINCT job_id) AS job_count
  FROM
    `PROJECT_ID.REGION_ID`.INFORMATION_SCHEMA.JOBS_TIMELINE
  WHERE
    state = "PENDING"
    AND period_start BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
    AND CURRENT_TIMESTAMP()
    AND reservation_id = "RESERVATION_ID"
  GROUP BY
    period_start,
    state
  HAVING
    COUNT(DISTINCT job_id) > 0 ) AS t2
ON
  t1.period_start = t2.period_start
WHERE
  t1.state = "RUNNING";

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

PROJECT_ID: クエリを実行したプロジェクトの名前
REGION_ID: クエリが処理されたロケーション
RESERVATION_ID: クエリが実行されている予約の名前

予約のクエリキューの長さは、BigQuery の管理リソースグラフを使用し、指標が保留のジョブの同時実行グラフを選択することでモニタリングできます。

ジョブ数の指標を表示して、保留状態になっているジョブの数でフィルタすることにより、Cloud Monitoring でキューの長さをモニタリングすることもできます。

制限事項

各オンデマンドプロジェクトは、一度に最大 1,000 回のインタラクティブクエリと 20,000 回のバッチクエリをキューに入れることができます。この上限を超えるクエリでは、割り当てエラーが返されます。この上限の引き上げは、リクエストできません。
予約に割り当てられた各プロジェクトは、一度に最大 1,000 回のインタラクティブクエリと 20,000 回のバッチクエリをキューに入れることができます。この上限を超えるクエリでは、割り当てエラーが返されます。この上限の引き上げは、リクエストできません。
デフォルトでは、実行が開始されていないクエリジョブは、インタラクティブクエリの場合で 6 時間、バッチクエリの場合で 24 時間後にタイムアウトします。
オンデマンドプロジェクトで実行されているクエリに、最大同時実行目標数は設定できません。
Standard Edition の予約で実行されるクエリに、最大同時実行目標数は設定できません。エディションの詳細については、BigQuery エディションの概要をご覧ください。

次のステップ

クエリキューの上限エラーの診断と解決について確認する。