Trabalhar com reservas de slot

A API BigQuery Reservations permite que você compre slots dedicados, chamados compromissos, crie pools de slots (chamados de reservas) e atribua projetos e organizações para essas reservas. Para mais informações sobre esses conceitos, consulte Introdução ao Reservations. Para informações sobre os planos de compromisso fornecidos pelo BigQuery, consulte Compromissos de capacidade.

As reservas permitem que você atribua um número dedicado de slots de um compromisso para uma carga de trabalho. Por exemplo, talvez você não queira que uma carga de trabalho de produção compita com cargas de trabalho de teste por slots. É possível criar uma reserva chamada prod e atribuir suas cargas de trabalho de produção a essa reserva. Para mais informações, consulte Reservas.

Criar reservas

Permissões necessárias

Para criar uma reserva, você precisa da seguinte permissão de gerenciamento de identidade e acesso (IAM):

Cada um dos seguintes papéis predefinidos do IAM inclui essa permissão:

  • BigQuery Admin
  • BigQuery Resource Admin
  • BigQuery Resource Editor

Para mais informações sobre os papéis do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Criar uma reserva com slots dedicados

Console

  1. No Console do Cloud, acesse a página do BigQuery.

    Ir para o BigQuery

  2. No painel de navegação, acesse a seção Gerenciamento de capacidade.

  3. Clique em Criar reserva.

  4. No campo Nome da reserva, digite um nome para a reserva.

  5. Na lista suspensa Local, selecione o local.

  6. Em Alocar slots, insira o número de slots da reserva.

  7. Clique em Save.

A nova reserva fica visível na guia Reservas.

Visão geral da reserva.

SQL

Use a instrução CREATE RESERVATION para criar uma reserva.

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

Em que:

  • ADMIN_PROJECT_ID é o ID do projeto.
  • LOCATION é o local do projeto.
  • NUMBER_OF_SLOTS é o número de slots a serem alocados para a reserva. O número de slots não alocados é suficiente no compromisso.
  • RESERVATION_NAME é o nome da reserva. Ele precisa começar e terminar com uma letra minúscula ou um número e conter apenas letras minúsculas, números e traços.

    Para mais informações sobre a instrução CREATE RESERVATION, consulte a instrução CREATE RESERVATION na referência de linguagem de controle de dados (DCL, na sigla em inglês).

Para informações sobre como executar consultas, consulte Como executar consultas interativas.

bq

Use o comando bq mk com a sinalização --reservation para criar uma reserva.

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

Em que:

  • ADMIN_PROJECT_ID é o ID do projeto.
  • LOCATION é o local do projeto.
  • NUMBER_OF_SLOTS é o número de slots a serem alocados para a reserva. O número de slots não alocados é suficiente no compromisso.
  • RESERVATION_NAME é o nome da reserva.

Para informações sobre a sinalização --ignore_idle_slots, consulte Slots inativos. O valor padrão é false.

Python

Instale Pacote google-cloud-bigquery-reservation antes de usar esta amostra de código. Crie um ReservationServiceClient. Descreva a reserva que você quer criar com uma Reserva. Crie a reserva com o método 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}")

Atualizar reservas

É possível fazer as seguintes atualizações em um compromisso de capacidade:

  • Adicione ou remova slots para alterar o tamanho da reserva.
  • Configure se as consultas nesta reserva usam slots inativos.

Permissões necessárias

Para atualizar uma reserva, você precisa da seguinte permissão de gerenciamento de identidade e acesso (IAM, na sigla em inglês):

Cada um dos seguintes papéis predefinidos do IAM inclui essa permissão:

  • BigQuery Admin
  • BigQuery Resource Admin
  • BigQuery Resource Editor

Para mais informações sobre os papéis do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Alterar o tamanho de uma reserva

É possível adicionar ou remover slots de uma reserva.

Console

  1. No Console do Cloud, acesse a página do BigQuery.

    Ir para o BigQuery

  2. No painel de navegação, acesse a seção Gerenciamento de capacidade.

  3. Clique na guia Reservas.

  4. Encontre a reserva que você quer excluir.

  5. Expanda a opção Ações.

  6. Clique em Editar.

  7. Na caixa de diálogo Editar slots, digite o número de slots.

  8. Clique em Save.

bq

Use o comando bq update com a sinalização --reservation para atualizar o tamanho de uma reserva.

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

Em que:

  • ADMIN_PROJECT_ID é o ID do projeto.
  • LOCATION é o local do projeto.
  • NUMBER_OF_SLOTS é o número de slots a serem alocados para a reserva.
  • RESERVATION_NAME é o nome da reserva.

Python

Instale Pacote google-cloud-bigquery-reservation antes de usar esta amostra de código. Crie um ReservationServiceClient. Descreva as propriedades atualizadas com uma reserva e a propriedade FieldMask.paths. Atualize a reserva com o método 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}")

Configurar se as consultas usam slots inativos

A sinalização --ignore_idle_slots controla se as consultas em execução em uma reserva podem usar slots inativos de outras reservas. Para mais informações, consulte Slots inativos. É possível atualizar essa configuração em uma reserva existente.

bq

Use o comando bq update com a sinalização --reservation para atualizar uma reserva. O exemplo a seguir define --ignore_idle_slots como true, o que significa que a reserva usará apenas slots alocados para a reserva.

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

Em que:

  • ADMIN_PROJECT_ID é o ID do projeto.
  • LOCATION é o local do projeto.
  • RESERVATION_NAME é o nome da reserva.

Excluir reservas

Quando você exclui uma reserva, qualquer job que esteja sendo executado com slots dessa reserva falhará. Para evitar erros, permita que jobs em execução sejam concluídos antes de excluir a reserva.

Permissões necessárias

Para excluir uma reserva, você precisa da seguinte permissão de gerenciamento de identidade e acesso (IAM, na sigla em inglês):

Cada um dos seguintes papéis predefinidos do IAM inclui essa permissão:

  • BigQuery Admin
  • BigQuery Resource Admin
  • BigQuery Resource Editor

Para mais informações sobre os papéis do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Excluir uma reserva

Console

  1. No Console do Cloud, acesse a página do BigQuery.

    Ir para o BigQuery

  2. No painel de navegação, acesse a seção Gerenciamento de capacidade.

  3. Clique na guia Reservas.

  4. Encontre a reserva que você quer excluir.

  5. Expanda a opção Ações.

  6. Clique em Excluir.

  7. Na caixa de diálogo Excluir reserva, clique em Excluir.

SQL

Use a instrução DROP RESERVATION para excluir uma reserva.

  DROP RESERVATION `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`

Em que:

  • ADMIN_PROJECT_ID é o ID do projeto.
  • LOCATION é o local do projeto.
  • RESERVATION_NAME é o ID da reserva.

    Para mais informações sobre a instrução DROP RESERVATION, consulte a instrução DROP RESERVATION na referência de controle de dados (DCL).

Para informações sobre como executar consultas, consulte Como executar consultas interativas.

bq

Use o comando bq rm com a sinalização --reservation para excluir uma reserva.

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

Em que:

  • ADMIN_PROJECT_ID é o ID do projeto.
  • LOCATION é o local do projeto.
  • RESERVATION_NAME é o nome da reserva.

Python

Instale Pacote google-cloud-bigquery-reservation antes de usar esta amostra de código. Crie um ReservationServiceClient. Exclua a reserva com o método 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}")