スロット予約の操作

BigQuery Reservations API を使用すると、専用スロット(コミットメント)を購入し、スロットのプール(予約)を作成して、プロジェクトと組織をそれらの予約に割り当てることができます。これらのコンセプトの詳細については、Reservations の概要をご覧ください。BigQuery が提供するコミットメント プランについては、容量コミットメントをご覧ください。

Reservations を使用すると、コミットメントから一定数の専用のスロットをワークロードに割り当てることができます。たとえば、本番環境のワークロードがスロット用のテスト ワークロードと競合するのを回避することが必要な場合が考えられます。prod という名前の予約を作成し、本番環境のワークロードをこの予約に割り当てることができます。詳細については、Reservations をご覧ください。

予約を作成する

必要な権限

予約を作成するには、次の Identity and Access Management(IAM)権限が必要です。

この権限は、次の各 IAM 事前定義ロールに含まれています。

  • BigQuery Admin
  • BigQuery Resource Admin
  • BigQuery Resource Editor

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

専用スロットを使用して予約を作成する

Console

  1. Cloud Console で、BigQuery ページに移動します。

    BigQuery に移動

  2. ナビゲーション パネルで [容量管理] セクションに移動します。

  3. [予約を作成] をクリックします。

  4. [予約名] フィールドに、予約の名前を入力します。

  5. [ロケーション] プルダウン リストで、ロケーションを選択します。

  6. [スロットの割り当て] に、予約のスロットの数を入力します。

  7. [保存] をクリックします。

新しい予約が [予約] タブに表示されます。

予約の概要。

SQL

CREATE RESERVATION ステートメントを使用して、予約を作成します。

  CREATE RESERVATION `ADMIN_PROJECT_ID.region-LOCATION
  .RESERVATION_NAME`
     AS JSON """{
     "slot_capacity": NUMBER_OF_SLOTS
     }"""

ここで

  • ADMIN_PROJECT_ID は、プロジェクト ID です。
  • LOCATION は、プロジェクトのロケーションです。
  • NUMBER_OF_SLOTS は、予約に割り当てるスロットの数です。コミットメントには、十分な数の未割り当てのスロットが必要です。
  • RESERVATION_NAME は、予約の名前です。先頭と末尾は英小文字または数字にしてください。使用できるのは英小文字、数字、ダッシュのみです。

    CREATE RESERVATION ステートメントの詳細については、データ制御言語(DCL)リファレンスの CREATE RESERVATION ステートメントをご覧ください。

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

bq

予約を作成するには、--reservation フラグを指定した bq mk コマンドを使用します。

bq mk \
  --project_id=ADMIN_PROJECT_ID \
  --location=LOCATION \
  --reservation \
  --slots=NUMBER_OF_SLOTS \
  --ignore_idle_slots=false \
  RESERVATION_NAME

ここで

  • ADMIN_PROJECT_ID は、プロジェクト ID です。
  • LOCATION は、プロジェクトのロケーションです。
  • NUMBER_OF_SLOTS は、予約に割り当てるスロットの数です。コミットメントには、十分な数の未割り当てのスロットが必要です。
  • RESERVATION_NAME は、予約の名前です。

--ignore_idle_slots フラグの詳細については、アイドル スロットをご覧ください。デフォルト値は false です。

Python

このコードサンプルを使用する前に、google-cloud-bigquery-reservation パッケージをインストールしてください。 ReservationServiceClient を作成します。Reservation を使用して、作成する予約を記述します。create_reservation メソッドを使用して予約を作成します。
# TODO(developer): Set project_id to the project ID containing the
# reservation.
project_id = "your-project-id"

# TODO(developer): Set location to the location of the reservation.
# See: https://cloud.google.com/bigquery/docs/locations for a list of
# available locations.
location = "US"

# TODO(developer): Set reservation_id to a unique ID of the reservation.
reservation_id = "sample-reservation"

# TODO(developer): Set slot_capicity to the number of slots in the
# reservation.
slot_capacity = 100

# ...

from google.cloud.bigquery_reservation_v1.services import reservation_service
from google.cloud.bigquery_reservation_v1.types import (
    reservation as reservation_types,
)

reservation_client = reservation_service.ReservationServiceClient()

parent = reservation_client.common_location_path(project_id, location)

reservation = reservation_types.Reservation(slot_capacity=slot_capacity)
reservation = reservation_client.create_reservation(
    parent=parent, reservation=reservation, reservation_id=reservation_id,
)

print(f"Created reservation: {reservation.name}")

予約を更新する

容量コミットメントには、次の更新を行うことができます。

  • 予約サイズを変更するには、スロットを追加または削除します。
  • この予約のクエリがアイドル スロットを使用するかどうかを構成します。

必要な権限

予約を更新するには、次の Identity and Access Management(IAM)権限が必要です。

この権限は、次の各 IAM 事前定義ロールに含まれています。

  • BigQuery Admin
  • BigQuery Resource Admin
  • BigQuery Resource Editor

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

予約のサイズを変更する

既存の予約に対して、スロットを追加または削除できます。

Console

  1. Cloud Console で、BigQuery ページに移動します。

    BigQuery に移動

  2. ナビゲーション パネルで [容量管理] セクションに移動します。

  3. [予約] タブをクリックします。

  4. 削除する予約を見つけます。

  5. [アクション] オプションを展開します。

  6. [編集] をクリックします。

  7. [スロットの編集] ダイアログで、スロットの数を入力します。

  8. [保存] をクリックします。

bq

予約のサイズを更新するには、--reservation フラグを指定した bq update コマンドを使用します。

bq update \
  --project_id=ADMIN_PROJECT_ID \
  --location=LOCATION \
  --slots=NUMBER_OF_SLOTS \
  --reservation RESERVATION_NAME

ここで

  • ADMIN_PROJECT_ID は、プロジェクト ID です。
  • LOCATION は、プロジェクトのロケーションです。
  • NUMBER_OF_SLOTS は、予約に割り当てるスロットの数です。
  • RESERVATION_NAME は、予約の名前です。

Python

このコードサンプルを使用する前に、google-cloud-bigquery-reservation パッケージをインストールしてください。 ReservationServiceClient を作成します。Reservation プロパティと FieldMask.paths プロパティを使用して、更新されたプロパティを記述します。update_reservation メソッドで予約を更新します。
# TODO(developer): Set project_id to the project ID containing the
# reservation.
project_id = "your-project-id"

# TODO(developer): Set location to the location of the reservation.
# See: https://cloud.google.com/bigquery/docs/locations for a list of
# available locations.
location = "US"

# TODO(developer): Set reservation_id to a unique ID of the reservation.
reservation_id = "sample-reservation"

# TODO(developer): Set slot_capicity to the new number of slots in the
# reservation.
slot_capacity = 50

# ...

from google.cloud.bigquery_reservation_v1.services import reservation_service
from google.cloud.bigquery_reservation_v1.types import (
    reservation as reservation_types,
)
from google.protobuf import field_mask_pb2

reservation_client = reservation_service.ReservationServiceClient()

reservation_name = reservation_client.reservation_path(
    project_id, location, reservation_id
)
reservation = reservation_types.Reservation(
    name=reservation_name, slot_capacity=slot_capacity,
)
field_mask = field_mask_pb2.FieldMask(paths=["slot_capacity"])
reservation = reservation_client.update_reservation(
    reservation=reservation, update_mask=field_mask
)

print(f"Updated reservation: {reservation.name}")
print(f"\tslot_capacity: {reservation.slot_capacity}")

クエリでアイドル スロットを使用するかどうかを構成する

--ignore_idle_slots フラグは、予約で実行中のクエリから他の予約のアイドル スロットを使用できるかどうかを制御します。詳細については、アイドル スロットをご覧ください。この構成は既存の予約で更新できます。

bq

bq update コマンドに --reservation フラグを指定して、予約を更新します。次の例では、--ignore_idle_slotstrue に設定しています。つまり、予約は、その予約に割り当てられたスロットのみを使用します。

bq update \
--project_id=ADMIN_PROJECT_ID \
--location=LOCATION \
--ignore_idle_slots=true \
--reservation RESERVATION_NAME

ここで

  • ADMIN_PROJECT_ID は、プロジェクト ID です。
  • LOCATION は、プロジェクトのロケーションです。
  • RESERVATION_NAME は、予約の名前です。

予約を削除する

予約を削除すると、その予約のスロットで実行中のジョブが失敗します。エラーが発生しないようにするには、実行中のジョブを完了させてから予約を削除してください。

必要な権限

予約を削除するには、次の Identity and Access Management(IAM)権限が必要です。

この権限は、次の各 IAM 事前定義ロールに含まれています。

  • BigQuery Admin
  • BigQuery Resource Admin
  • BigQuery Resource Editor

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

予約の削除

Console

  1. Cloud Console で、BigQuery ページに移動します。

    BigQuery に移動

  2. ナビゲーション パネルで [容量管理] セクションに移動します。

  3. [予約] タブをクリックします。

  4. 削除する予約を見つけます。

  5. [アクション] オプションを展開します。

  6. [削除] をクリックします。

  7. [予約の削除] ダイアログで、[削除] をクリックします。

SQL

DROP RESERVATION ステートメントを使用して、予約を削除します。

  DROP RESERVATION `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`

ここで

  • ADMIN_PROJECT_ID は、プロジェクト ID です。
  • LOCATION は、プロジェクトのロケーションです。
  • RESERVATION_NAME は、予約の ID です。

    DROP RESERVATION ステートメントの詳細については、データ制御言語(DCL)リファレンスの DROP RESERVATION ステートメントをご覧ください。

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

bq

bq rm コマンドに --reservation フラグを指定して、予約を削除します。

bq rm \
--project_id=ADMIN_PROJECT_ID \
  --location=LOCATION \
  --reservation RESERVATION_NAME

ここで

  • ADMIN_PROJECT_ID は、プロジェクト ID です。
  • LOCATION は、プロジェクトのロケーションです。
  • RESERVATION_NAME は、予約の名前です。

Python

このコードサンプルを使用する前に、google-cloud-bigquery-reservation パッケージをインストールしてください。 ReservationServiceClient を作成します。delete_reservation メソッドを使用して予約を削除します。
# TODO(developer): Set project_id to the project ID containing the
# reservation.
project_id = "your-project-id"

# TODO(developer): Set location to the location of the reservation.
# See: https://cloud.google.com/bigquery/docs/locations for a list of
# available locations.
location = "US"

# TODO(developer): Set reservation_id to a unique ID of the reservation.
reservation_id = "sample-reservation"

# ...

from google.cloud.bigquery_reservation_v1.services import reservation_service

reservation_client = reservation_service.ReservationServiceClient()
reservation_name = reservation_client.reservation_path(
    project_id, location, reservation_id
)
reservation_client.delete_reservation(name=reservation_name)

print(f"Deleted reservation: {reservation_name}")