クエリキューを使用する

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

概要

BigQuery では、同時に実行できるクエリの数が、使用可能なコンピューティング リソースに基づいて動的に決定されます。同時に実行できるクエリの数は、オンデマンド プロジェクトまたは予約ごとに計算されます。それ以上のクエリは、実行の開始に十分な容量が確保されるまで、キューに配置されます。プロジェクトがオンデマンドか予約を使用するかに関係なく、キューの長さは、プロジェクトごと、リージョンごとに 1,000 回のインタラクティブ クエリと 20,000 回のバッチクエリに制限されています。次の例では、計算されたクエリの同時実行数が 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 のロールの詳細については、事前定義ロールと権限をご覧ください。

予約の最大同時実行ターゲットを設定する

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

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

最大同時実行ターゲットを更新する

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

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

必要なロール

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

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

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

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

予約の最大同時実行ターゲットを更新する

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

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

モニタリング

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

最後の 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 エディションの概要をご覧ください。

次のステップ

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