スロット予約の操作

BigQuery Reservation API を使用すると、専用スロットを購入し（コミットメントと呼ぶ）、スロットのプールを作成し（予約と呼ぶ）、それらの予約にプロジェクト、フォルダ、組織を割り当てることができます。

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

予約を作成する

必要な権限

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

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

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

BigQuery Resource Editor
BigQuery Resource Admin

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

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

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

コンソール

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

[BigQuery] に移動
ナビゲーションパネルで [容量管理] セクションに移動し、[予約を作成] をクリックします。
[予約名] フィールドに、予約の名前を入力します。
[ロケーション] プルダウンリストで、ロケーションを選択します。BigQuery Omni のロケーションを選択した場合、エディションオプションは Enterprise エディションに限定されます。
[エディション] リストでエディションを選択します。自動スケーリングはエディション内でのみ利用可能です。詳細については、BigQuery エディションの概要をご覧ください。
[最大予約サイズセレクタ] リストで、最大予約サイズを選択します。
省略可: [ベースラインスロット] フィールドに、予約用のベースラインスロット数を入力します。

使用可能な自動スケーリングスロットの数は、[最大予約サイズ] から [ベースラインスロット] の値を引いた値になります。たとえば、ベースラインスロットを 100 個、最大予約サイズを 400 個として予約を作成した場合、その予約には 300 個の自動スケーリングスロットがあります。ベースラインスロットの詳細については、ベースラインスロットと自動スケーリングスロットを使用した予約の使用をご覧ください。
アイドルスロットの共有を無効にして、指定したスロット容量のみを使用するには、[アイドルスロットを無視する] トグルをクリックします。
[詳細設定] セクションを開くには、展開矢印をクリックします。
省略可: ターゲットジョブの同時実行を設定するには、[自動のターゲットジョブ同時実行をオーバーライドする] トグルをオンに切り替えて、ターゲットジョブの同時実行を入力します。
スロットの内訳は、[費用見積もり] テーブルに表示されます。予約の概要が [容量の概要] テーブルに表示されます。
[保存] をクリックします。

新しい予約が [スロットの予約] タブに表示されます。

SQL

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

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

[BigQuery] に移動
クエリエディタで次のステートメントを入力します。
```
CREATE RESERVATION
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`
OPTIONS (
  slot_capacity = NUMBER_OF_SLOTS,
  edition = EDITION,
  autoscale_max_slots = NUMBER_OF_AUTOSCALING_SLOTS);
```
次のように置き換えます。
- ADMIN_PROJECT_ID: 予約リソースを所有する管理プロジェクトのプロジェクト ID
- LOCATION: 予約のロケーション。BigQuery Omni のロケーションを選択した場合、エディションオプションは Enterprise エディションに限定されます。
- RESERVATION_NAME: 予約の名前
  
  先頭と末尾は英小文字または数字にしてください。使用できるのは英小文字、数字、ダッシュのみです。
- NUMBER_OF_SLOTS: 予約に割り当てるスロットの数。コミットメントには、十分な数の未割り当てのスロットが必要です。slot_capacity オプションと edition オプションを同じ予約内で設定することはできません。
- EDITION: 予約のエディション。予約をエディションに割り当てると、機能と料金が変更されます。詳細については、BigQuery エディションの概要をご覧ください。
- NUMBER_OF_AUTOSCALING_SLOTS: 予約に割り当てられている自動スケーリングスロットの数。edition オプションを指定した場合のみ使用できます。
[実行] をクリックします。

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

bq

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

bq mk \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation \
    --slots=NUMBER_OF_SLOTS \
    --ignore_idle_slots=false \
    --edition=EDITION \
    --autoscale_max_slots=NUMBER_OF_AUTOSCALING_SLOTS \
    RESERVATION_NAME

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

ADMIN_PROJECT_ID: プロジェクト ID
LOCATION: 予約のロケーション。BigQuery Omni のロケーションを選択した場合、エディションオプションは Enterprise エディションに限定されます。
NUMBER_OF_SLOTS: 予約に割り当てるスロットの数

コミットメントには、十分な数の未割り当てのスロットが必要です。
RESERVATION_NAME: 予約の名前
EDITION: 予約のエディション。予約をエディションに割り当てると、機能と料金が変更されます。詳細については、BigQuery エディションの概要をご覧ください。
NUMBER_OF_AUTOSCALING_SLOTS: 予約に割り当てられている自動スケーリングスロットの数。edition オプションを指定した場合のみ使用できます。

--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

# TODO(developer): Choose a transport to use. Either 'grpc' or 'rest'
transport = "grpc"

# ...

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(
    transport=transport
)

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 のロールの詳細については、事前定義ロールと権限をご覧ください。

予約のサイズを変更する

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

コンソール

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

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

SQL

予約のサイズを変更するには、データ定義言語（DDL）ステートメント ALTER RESERVATION SET OPTIONS を使用します。

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

[BigQuery] に移動
クエリエディタで次のステートメントを入力します。
```
ALTER RESERVATION
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`
SET OPTIONS (
  slot_capacity = NUMBER_OF_SLOTS,
  autoscale_max_slots = NUMBER_OF_AUTOSCALING_SLOTS);
```
次のように置き換えます。
- ADMIN_PROJECT_ID: 予約リソースを所有する管理プロジェクトのプロジェクト ID
- LOCATION: 予約のロケーション（例: europe-west9）。
- RESERVATION_NAME: 予約の名前先頭と末尾は英小文字または数字にしてください。使用できるのは英小文字、数字、ダッシュのみです。
- NUMBER_OF_SLOTS: 予約に割り当てるスロットの数。
- NUMBER_OF_AUTOSCALING_SLOTS: 予約に割り当てられている自動スケーリングスロットの数。このオプションは、edition 内の予約専用です。
[実行] をクリックします。

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

bq

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

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

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

ADMIN_PROJECT_ID: プロジェクト ID
LOCATION: 予約のロケーション
NUMBER_OF_SLOTS: 予約に割り当てるスロットの数
RESERVATION_NAME: 予約の名前
NUMBER_OF_AUTOSCALING_SLOTS: 予約に割り当てられている自動スケーリングスロットの数。edition オプションを指定した場合のみ使用できます。

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

# TODO(developer): Choose a transport to use. Either 'grpc' or 'rest'
transport = "grpc"

# ...

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(
    transport=transport
)

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

予約を更新するには、--reservation フラグを指定して bq update コマンドを使用します。次の例では、--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 列のクエリを実行します。

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

[BigQuery] に移動
クエリエディタで次のステートメントを入力します。
```
SELECT
  reservation_name,
  ignore_idle_slots
FROM
  `ADMIN_PROJECT_ID.region-LOCATION`.INFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT;
```
次のように置き換えます。
- ADMIN_PROJECT_ID: 予約リソースを所有する管理プロジェクトのプロジェクト ID
- LOCATION: 予約のロケーション
[実行] をクリックします。

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

bq

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

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 のロールの詳細については、事前定義ロールと権限をご覧ください。

予約の削除

コンソール

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

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

SQL

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

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

[BigQuery] に移動
クエリエディタで次のステートメントを入力します。
```
DROP RESERVATION
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`;
```
次のように置き換えます。
- ADMIN_PROJECT_ID: 予約リソースを所有する管理プロジェクトのプロジェクト ID
- LOCATION: 予約のロケーション
- RESERVATION_NAME: 予約の ID
[実行] をクリックします。

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

bq

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

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"

# TODO(developer): Choose a transport to use. Either 'grpc' or 'rest'
transport = "grpc"

# ...

from google.cloud.bigquery_reservation_v1.services import reservation_service

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

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

スロット予約の操作

予約を作成する

必要な権限

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

コンソール

SQL

bq

Python

予約を更新する

必要な権限

予約のサイズを変更する

コンソール

SQL

bq

Python

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

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

SQL

bq

予約を削除する

必要な権限

予約の削除

コンソール

SQL

bq

Python

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

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