使用槽预留

通过 BigQuery Reservation API，您可以购买专用槽（称为承诺）、创建槽池（称为预留），以及将项目、文件夹和组织分配给这些预留。

通过预留，您可以为工作负载分配专用数量的槽。例如，您可能不希望提供的工作负载与槽的测试工作负载竞争。您可以创建一个名为 prod 的预留，并将生产工作负载分配给此预留。如需了解详情，请参阅预留。

创建预留

所需权限

如需创建预留，您需要以下 Identity and Access Management (IAM) 权限：

• 对维持承诺所有权的管理项目拥有 bigquery.reservations.create 权限。

以下每个预定义的 IAM 角色都具有此权限：

• BigQuery Resource Editor
• BigQuery Resource Admin

如需详细了解 BigQuery 中的 IAM 角色，请参阅预定义的角色和权限。

创建包含专用槽的预留

从下列选项中选择一项：

控制台

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在导航面板中，转到容量管理部分，然后点击创建预留。

3. 在预留名称字段中，输入预留的名称。

4. 在位置下拉列表中，选择位置。如果您选择 BigQuery Omni 位置，则您的版本选项仅限于企业版。

5. 在版本列表中，选择版本。自动扩缩仅在版本内可用。如需了解详情，请参阅 BigQuery 版本简介。

6. 在预留大小上限选择器列表中，选择预留大小上限。

7. 可选：在基准槽数字段中，输入预留的基准槽数。

   可用自动扩缩槽的数量是从预留槽大小上限中减去基准槽值来确定的。例如，如果您创建了一个包含 100 个基准槽且预留大小上限为 400 的预留，则该预留包含 300 个自动扩缩槽。如需详细了解基准槽，请参阅将预留与基准槽和自动扩缩槽搭配使用。

8. 如需停用空闲槽共享并仅使用指定的槽容量，请点击忽略空闲槽切换开关。

9. 如需展开高级设置部分，请点击 展开箭头。

10. 可选：如需设置目标作业并发，请点击替换自动目标作业并发切换开关，然后输入目标作业并发。

11. 槽明细显示在费用估算表中。预留摘要显示在容量摘要表中。

12. 点击保存。

新预留会显示在槽预留标签页中。

SQL

如需创建预留，请使用 CREATE RESERVATION DDL 语句。

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在查询编辑器中，输入以下语句：

   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 位置，则您的版本选项仅限于企业版。

   • RESERVATION_NAME：预留的名称

     该字段必须以小写字母或数字开头和结尾，并且只能包含小写字母、数字和短划线。

   • NUMBER_OF_SLOTS：要分配给此预留的槽数。承诺使用合约中必须有足够未分配的槽。您不能在同一预留中设置 slot_capacity 选项和 edition 选项。
   • EDITION：预留的版本。为版本分配预留会改变功能和价格。如需了解详情，请参阅 BigQuery 版本简介。
   • NUMBER_OF_AUTOSCALING_SLOTS：分配给预留的自动扩缩槽数。仅在指定 edition 选项时可用。

3. 点击 运行。

如需详细了解如何运行查询，请参阅运行交互式查询。

bq

如需创建预留，请将 bq mk 命令与 --reservation 标志结合使用：

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 位置，则您的版本选项仅限于企业版。

• NUMBER_OF_SLOTS：要分配给预留的槽数

  承诺使用合约中必须有足够未分配的槽。

• RESERVATION_NAME：预留的名称

• EDITION：预留的版本。为版本分配预留会改变功能和价格。如需了解详情，请参阅 BigQuery 版本简介。

• NUMBER_OF_AUTOSCALING_SLOTS：分配给预留的自动扩缩槽数。仅在指定 edition 选项时可用。

如需了解 --ignore_idle_slots 标志，请参阅空闲槽。默认值为 false。

Terraform

使用 google_bigquery_reservation 资源。

注意：如需使用 Terraform 创建 BigQuery 对象，您必须启用 Cloud Resource Manager API。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

以下示例将创建一个名为 my-reservation 的预留：

resource "google_bigquery_reservation" "default" {
  name              = "my-reservation"
  location          = "us-central1"
  slot_capacity     = 100
  edition           = "ENTERPRISE"
  ignore_idle_slots = false # Use idle slots from other reservations
  concurrency       = 0     # Automatically adjust query concurrency based on available resources
  autoscale {
    max_slots = 200 # Allow the reservation to scale up to 300 slots (slot_capacity + max_slots) if needed
  }
}

如需在 Google Cloud 项目中应用 Terraform 配置，请完成以下部分中的步骤。

准备 Cloud Shell

1. 启动 Cloud Shell。

2. 设置要在其中应用 Terraform 配置的默认 Google Cloud 项目。

   您只需为每个项目运行一次以下命令，即可在任何目录中运行它。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 配置文件中设置显式值，则环境变量会被替换。

准备目录

每个 Terraform 配置文件都必须有自己的目录（也称为“根模块”）。

1. 在 Cloud Shell 中，创建一个目录，并在该目录中创建一个新文件。文件名必须具有 .tf 扩展名，例如 main.tf。在本教程中，该文件称为 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您按照教程进行操作，可以在每个部分或步骤中复制示例代码。

   将示例代码复制到新创建的 main.tf 中。

   （可选）从 GitHub 中复制代码。如果端到端解决方案包含 Terraform 代码段，则建议这样做。

3. 查看和修改要应用到您的环境的示例参数。
4. 保存更改。
5. 初始化 Terraform。您只需为每个目录执行一次此操作。

   terraform init

   （可选）如需使用最新的 Google 提供程序版本，请添加 -upgrade 选项：

   terraform init -upgrade

应用更改

1. 查看配置并验证 Terraform 将创建或更新的资源是否符合您的预期：

   terraform plan

   根据需要更正配置。

2. 通过运行以下命令并在提示符处输入 yes 来应用 Terraform 配置：

   terraform apply

   等待 Terraform 显示“应用完成！”消息。

3. 打开您的 Google Cloud 项目以查看结果。在 Google Cloud 控制台的界面中找到资源，以确保 Terraform 已创建或更新它们。

注意：Terraform 示例通常假定您的 Google Cloud 项目中启用了所需的 API。

Python

在使用此代码示例之前，请安装 google-cloud-bigquery-reservation 软件包。 构建 ReservationServiceClient。使用预留描述您要创建的预留。使用 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

# 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 角色，请参阅预定义的角色和权限。

更改预留大小

您可以在现有预留中添加或移除槽。

控制台

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在导航面板中，转到容量管理部分。

3. 点击槽预留标签页。

4. 找到要更新的预留。

5. 展开 操作选项。

6. 点击修改。

7. 在预留大小上限选择器对话框中，输入预留大小上限。

8. 在基准槽字段中，输入基准槽数。

9. 如需展开高级设置部分，请点击 展开箭头。

10. 可选：如需设置目标作业并发，请点击替换自动目标作业并发切换开关，然后输入目标作业并发。

11. 点击保存。

SQL

如需更改预留的大小，请使用 ALTER RESERVATION SET OPTIONS 数据定义语言 (DDL) 语句。

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在查询编辑器中，输入以下语句：

   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 的预留。

3. 点击 运行。

如需详细了解如何运行查询，请参阅运行交互式查询。

bq

如需更新预留的大小，请将 bq update 命令与 --reservation 标志结合使用：

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。使用预留和 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

# 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 标志控制某一个预留中运行的查询是否可以使用其他预留中的空闲槽。如需了解详情，请参阅空闲槽。您可以在现有预留上更新此配置。

如需更新预留，请将 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 列。

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在查询编辑器中，输入以下语句：

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

   请替换以下内容：

   • ADMIN_PROJECT_ID：拥有预留资源的管理项目的 ID
   • LOCATION：预留的位置

3. 点击 运行。

如需详细了解如何运行查询，请参阅运行交互式查询。

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 角色，请参阅预定义的角色和权限。

删除预留

控制台

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在导航面板中，转到容量管理部分。

3. 点击预留标签页。

4. 找到要删除的预留。

5. 展开 操作选项。

6. 点击删除。

7. 在删除预留对话框中，点击删除。

SQL

如需删除预留，请使用 DROP RESERVATION DDL 语句。

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在查询编辑器中，输入以下语句：

   DROP RESERVATION
     `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`;

   请替换以下内容：

   • ADMIN_PROJECT_ID：拥有预留资源的管理项目的 ID
   • LOCATION：预留的位置
   • RESERVATION_NAME：预留的 ID。

3. 点击 运行。

如需详细了解如何运行查询，请参阅运行交互式查询。

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"

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