スロット予約の操作

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

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

予約を作成する

必要な権限

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

コミットメントの所有権を持つ管理プロジェクトに対する bigquery.reservations.create。

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

BigQuery Admin
BigQuery Resource Admin
BigQuery Resource Editor

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

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

Console

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

BigQuery に移動
ナビゲーションパネルで [容量管理] セクションに移動します。
[予約を作成] をクリックします。
[予約名] フィールドに、予約の名前を入力します。
[ロケーション] プルダウンリストで、ロケーションを選択します。
[スロットの割り当て] に、予約のスロットの数を入力します。
[保存] をクリックします。

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

予約の概要。

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 ステートメントの詳細については、データ定義言語（DDL）リファレンスの 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 メソッドを使用して予約を作成します。

GitHub で表示フィードバック

# 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）権限が必要です。

コミットメントの所有権を持つ管理プロジェクトに対する bigquery.reservations.update。

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

BigQuery Admin
BigQuery Resource Admin
BigQuery Resource Editor

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

予約のサイズを変更する

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

Console

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

BigQuery に移動
ナビゲーションパネルで [容量管理] セクションに移動します。
[予約] タブをクリックします。
削除する予約を見つけます。
[アクション] オプションを展開します。
[編集] をクリックします。
[スロットの編集] ダイアログで、スロットの数を入力します。
[保存] をクリックします。

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 メソッドで予約を更新します。

GitHub で表示フィードバック

# 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_slots を true に設定しています。つまり、予約は、その予約に割り当てられたスロットのみを使用します。

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

ここで

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

アイドルスロット構成を一覧表示する

予約のアイドルスロットの設定を一覧表示するには、次のようにします。

SQL

INFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT ビューの ignore_idle_slots 列をクエリします。

SELECT reservation_name, ignore_idle_slots
FROM `ADMIN_PROJECT_ID.region-LOCATION`.INFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT

ここで

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

bq

bq ls コマンドを使用し、--reservation フラグを指定します。

bq ls --reservation \
--project_id=ADMIN_PROJECT_ID \
--location=LOCATION \

ここで

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

ignoreIdleSlots フィールドには、構成設定が含まれています。

予約の削除

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

必要な権限

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

コミットメントの所有権を持つ管理プロジェクトに対する bigquery.reservations.delete。

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

BigQuery Admin
BigQuery Resource Admin
BigQuery Resource Editor

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

予約の削除

Console

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

BigQuery に移動
ナビゲーションパネルで [容量管理] セクションに移動します。
[予約] タブをクリックします。
削除する予約を見つけます。
[アクション] オプションを展開します。
[削除] をクリックします。
[予約の削除] ダイアログで、[削除] をクリックします。

SQL

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

  DROP RESERVATION `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`

ここで

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

DROP RESERVATION ステートメントの詳細については、データ定義言語（DDL）リファレンスの 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 メソッドを使用して予約を削除します。

GitHub で表示フィードバック

# 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}")

スロット予約の操作

予約を作成する

必要な権限

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

Console

SQL

bq

Python

予約を更新する

必要な権限

予約のサイズを変更する

Console

bq

Python

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

bq

アイドル スロット構成を一覧表示する

SQL

bq

予約の削除

必要な権限

予約の削除

Console

SQL

bq

Python

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

アイドルスロット構成を一覧表示する