Trabalhar com reservas de slots legadas

Observação :as reservas legadas, incluindo o acesso ao faturamento de taxa fixa ou a determinadas durações de compromisso, estão disponíveis somente para clientes da lista de permissões. Para determinar se você tem acesso a esses recursos legados, entre em contato com o administrador. O modelo de faturamento de taxa fixa define como você é cobrado pela computação, mas as reservas e compromissos de taxa fixa funcionam como slots da edição Enterprise.

Com a API BigQuery Reservation, você compra slots dedicados (chamados compromissos), cria pools de slots (chamados reservas) e atribui projetos, pastas e organizações a essas reservas.

As reservas permitem atribuir um número dedicado de slots a 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):

• bigquery.reservations.create no projeto de administração que mantém a propriedade dos compromissos.

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

Selecione uma das seguintes opções:

Console

1. No Console do Google 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, insira um nome para a reserva.

5. Na lista suspensa Local, selecione o local.

6. Na seção Modelo de capacidade, escolha o modelo de capacidade.

7. Se você selecionar a opção Taxa fixa, em Slots de referência, insira o número de slots para a reserva.

   1. Na lista Seletor de tamanho máximo da reserva, escolha o tamanho máximo da reserva.

   2. Opcional: no campo Slots de valor de referência, insira o número de slots de valor de referência para a reserva. Para usar apenas a capacidade do slot especificada, clique no botão Ignorar slots inativos.

      O número de slots de escalonamento automático disponíveis é determinado subtraindo o valor de Slots de valor de referência do valor de tamanho de Reserva máxima. Por exemplo, se você criar uma reserva com 100 slots de valor de referência e um tamanho máximo de 400, sua reserva terá 300 slots de escalonamento automático. Para mais informações sobre slots de valor de referência, consulte Como usar reservas com slots de valor de referência e de escalonamento automático.

8. Para desativar o compartilhamento de slot inativo, clique no botão Ignorar slots inativos.

9. O detalhamento de slots é exibido na tabela Estimativa de custo. Um resumo da reserva será exibido na tabela Resumo da capacidade.

10. Clique em Salvar.

A nova reserva fica visível na guia Reservas.

SQL

Para criar uma reserva, use a instrução DDL CREATE RESERVATION.

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

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   CREATE RESERVATION
     `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`
   OPTIONS (
     slot_capacity = NUMBER_OF_BASELINE_SLOTS,
   );

   Substitua:

   • ADMIN_PROJECT_ID: o ID do projeto de administração que é proprietário do recurso de reserva.
   • LOCATION: o local da reserva. Se você selecionar um local do BigQuery Omni, sua opção de edição será limitada à edição Enterprise.

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

   • NUMBER_OF_BASELINE_SLOTS: o número de slots de referência que serão alocados para a reserva. Não é possível definir a opção slot_capacity e edition na mesma reserva.
   • EDITION: a edição da reserva. A atribuição de uma reserva a uma edição inclui mudanças de recursos e preços. Para mais informações, consulte Introdução às edições do BigQuery.
   • NUMBER_OF_AUTOSCALING_SLOTS: o número de slots de escalonamento automático atribuídos à reserva. Isso é igual a o valor do tamanho máximo da reserva menos o número de slots de referência.

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Para criar uma reserva, use o comando bq mk com a sinalização --reservation:

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

Substitua:

• ADMIN_PROJECT_ID: o ID do projeto
• LOCATION: o local da reserva. Se você selecionar um local do BigQuery Omni, sua opção de edição será limitada à edição Enterprise.

• NUMBER_OF_BASELINE_SLOTS: o número de slots de referência que serão alocados à reserva.

• RESERVATION_NAME: o nome da reserva

• EDITION: a edição da reserva. A atribuição de uma reserva a uma edição inclui mudanças de recursos e preços. Para mais informações, consulte Introdução às edições do BigQuery.

• NUMBER_OF_AUTOSCALING_SLOTS: o número de slots de escalonamento automático atribuídos à reserva. Isso é igual a o valor do tamanho máximo da reserva menos o número de slots de referência.

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

Python

Instale o pacote google-cloud-bigquery-reservation antes de usar este exemplo 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

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

Atualizar reservas

É possível fazer as seguintes atualizações em uma reserva:

• Adicione ou remova slots para alterar o tamanho da reserva.
• Configure se as consultas nesta reserva usam slots inativos.
• Altere a quantidade de slots de valor de referência ou de escalonamento automático alocados para uma reserva.

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

• bigquery.reservations.update no projeto de administração que mantém a propriedade dos compromissos.

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 Google 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 atualizar.

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

6. Clique em Editar.

7. Na caixa de diálogo Seletor de tamanho máximo da reserva, insira o tamanho máximo da reserva.

8. No campo Slots de valor de referência, insira o número de slots de valor de referência.

9. Clique em Salvar.

SQL

Para mudar o tamanho de uma reserva, use a instrução ALTER RESERVATION SET OPTIONS da linguagem de definição de dados (DDL, na sigla em inglês).

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

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   ALTER RESERVATION
     `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`
   SET OPTIONS (
     slot_capacity = NUMBER_OF_BASELINE_SLOTS,
   );

   Substitua:

   • ADMIN_PROJECT_ID: o ID do projeto de administração que é proprietário do recurso de reserva.
   • LOCATION: o local da reserva, por exemplo, europe-west9.

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

   • NUMBER_OF_BASELINE_SLOTS: o número de slots de referência que serão alocados à reserva.

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Para atualizar o tamanho de uma reserva, use o comando bq update com a sinalização --reservation:

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

Substitua:

• ADMIN_PROJECT_ID: o ID do projeto
• LOCATION: o local da reserva
• NUMBER_OF_BASELINE_SLOTS: o número de slots de referência que serão alocados à reserva.
• RESERVATION_NAME: o nome da reserva

Python

Instale o pacote google-cloud-bigquery-reservation antes de usar este exemplo 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

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

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.

Para atualizar uma reserva, use o comando bq update com a sinalização --reservation. 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

Substitua:

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

Listar a configuração de slot inativo

Para listar a configuração slots de inatividade de uma reserva, faça o seguinte:

SQL

Consulte a coluna ignore_idle_slots da visualização INFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT.

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

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instrução:

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

   Substitua:

   • ADMIN_PROJECT_ID: o ID do projeto de administração que é proprietário do recurso de reserva.
   • LOCATION: o local das reservas

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Use o comando bq ls com a sinalização --reservation:

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

Substitua:

• ADMIN_PROJECT_ID: o ID do projeto de administração que é proprietário do recurso de reserva.
• LOCATION: o local das reservas.

O campo ignoreIdleSlots contém a configuração.

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

• bigquery.reservations.delete no projeto de administração que mantém a propriedade dos compromissos.

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

Para excluir uma reserva, use a instrução DDL DROP RESERVATION.

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

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instrução:

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

   Substitua:

   • ADMIN_PROJECT_ID: o ID do projeto de administração que é proprietário do recurso de reserva.
   • LOCATION: o local da reserva
   • RESERVATION_NAME: o ID d reserva.

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Para excluir uma reserva, use o comando bq rm com a sinalização --reservation:

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

Substitua:

• ADMIN_PROJECT_ID: o ID do projeto de administração que é proprietário do recurso de reserva.
• LOCATION: o local da reserva
• RESERVATION_NAME: o nome da reserva

Python

Instale o pacote google-cloud-bigquery-reservation antes de usar este exemplo 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"

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

Adicionar a API BigQuery Reservation ao VPC Service Controls

Observação: esse recurso pode não estar disponível ao usar reservas criadas com determinadas edições do BigQuery. Para mais informações sobre quais recursos estão ativados em cada edição, consulte Introdução às edições do BigQuery.

A API BigQuery Reservation é compatível com o VPC Service Controls. Para integrar a API BigQuery Reservation ao VPC Service Controls, siga as instruções em Criar um perímetro de serviço e adicione a API BigQuery Reservation aos serviços protegidos.

Um perímetro de serviço protege o acesso a reservas, compromissos e atribuições em projetos de administração especificados no perímetro. Ao criar uma atribuição, o VPC Service Controls protege o projeto de administração e o projeto, a pasta e a organização atribuídos.