Comprar e gerenciar compromissos de slot

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.

Um compromisso de capacidade é uma compra de capacidade de computação do BigQuery por um período mínimo. Comprar um compromisso de capacidade é opcional na criação de uma reserva com uma edição, mas pode oferecer economia de custos.

Compromissos são um recurso regional. Compromissos comprados em uma região ou multirregião não podem ser usados em outra região ou multirregião. Não é possível mover os compromissos entre regiões ou entre regiões e multirregiões.

Ativar a API Reservations

A API BigQuery Reservation é diferente da API do BigQuery atual e precisa ser ativada de forma independente. Para mais informações, consulte Como ativar e desativar APIs.

O nome da API é "API BigQuery Reservations".
O endpoint da API BigQuery Reservation é bigqueryreservation.googleapis.com.

Comprar slots

Para reservar capacidade por um período mínimo de tempo, é possível adquirir um compromisso de capacidade. Isso dá um desconto e economiza dinheiro. Para mais informações sobre os custos específicos, consulte Preços do BigQuery.

Permissões necessárias

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

bigquery.capacityCommitments.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

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

Criar um compromisso de capacidade

Console

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

Ir para o BigQuery
No painel de navegação, acesse a seção Gerenciamento de capacidade.
Clique em Criar compromisso.
Em Configurar:
1. Selecione o local.
2. Na seção Modelo de capacidade, escolha o modelo de capacidade.
3. Se você selecionar a opção de escalonamento automático (edição):
  1. Na lista Edição, selecione a edição. Os compromissos de capacidade só são compatíveis com as edições Enterprise e Enterprise Plus. O escalonamento automático está disponível apenas em uma edição. Para mais informações sobre edições, consulte Introdução às edições do BigQuery.
4. Selecione a Duração do compromisso, que especifica seu plano de compromisso.
5. Se você estiver comprando um compromisso anual, selecione o plano de renovação que quer entrar em vigor quando o compromisso expirar:
  1. Renovar anualmente Quando o compromisso anual expirar, ele será renovado por mais um ano como compromisso anual.
  Para mais informações, consulte Compromissos.
6. Digite o Número de slots que você quer comprar.
7. Clique em Próxima.
Analise a estimativa de custo da compra.
Em Confirmar e enviar:
1. Digite CONFIRMAR para confirmar a compra.
2. Clique em Comprar para comprar os slots.
Para visualizar o compromisso, clique em Visualizar compromissos de slot. Depois que a capacidade for provisionada, o compromisso de capacidade solicitado exibirá um status verde.

Observação: os slots geralmente são provisionados rapidamente, mas em casos raros podem levar várias horas. Se você tiver uma carga de trabalho crítica que espera aumentar a demanda, reserve seus slots com pelo menos um dia de antecedência.

Na primeira vez que você comprar capacidade, uma reserva default será criada.

SQL

Para excluir um compromisso de capacidade, use a instrução DDL CREATE CAPACITY.

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

Ir para o BigQuery
No editor de consultas, digite a seguinte instrução:
```
CREATE CAPACITY
  `ADMIN_PROJECT_ID.region-LOCATION.COMMITMENT_ID`
OPTIONS (
  slot_count = NUMBER_OF_SLOTS,
  edition = EDITION,
  plan = 'PLAN_TYPE');
```
Substitua:
- ADMIN_PROJECT_ID: o ID do projeto de administração que vai manter a propriedade desse compromisso.
- LOCATION: o local do compromisso.
- COMMITMENT_ID: o ID do compromisso
  
  Ele precisa ser exclusivo do projeto e do local. 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_SLOTSO número de slots para compra.
- EDITION: a edição associada ao compromisso de capacidade. Só é possível criar um compromisso de capacidade com as edições Enterprise ou Enterprise Plus. Para saber mais sobre edições, consulte Introdução às edições do BigQuery.
- PLAN_TYPE: o tipo de plano, como ANNUAL ou THREE_YEAR.
Clique em Executar.

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

bq

Use o comando bq mk com a sinalização--capacity_commitment para comprar slots.

bq mk \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --capacity_commitment=true \
    --edition=EDITION \
    --plan=PLAN_TYPE \
    --renewal_plan=RENEWAL_PLAN_TYPE \
    --slots=NUMBER_OF_SLOTS

Substitua:

ADMIN_PROJECT_ID: o ID do projeto de administração que vai manter a propriedade desse compromisso.
LOCATION: o local do compromisso.
EDITION: a edição associada ao compromisso de capacidade. Só é possível criar um compromisso de capacidade com as edições Enterprise ou Enterprise Plus. Para saber mais sobre edições, consulte Introdução às edições do BigQuery.
PLAN_TYPE: o tipo de plano, como ANNUAL ou THREE_YEAR.
RENEWAL_PLAN_TYPE: o tipo de plano de renovação, como NONE, ANNUAL ou THREE_YEAR.
NUMBER_OF_SLOTS: o número de slots para compra.

Ver compromissos de capacidade

Permissões necessárias

Para ver os compromissos, é preciso ter a seguinte permissão de gerenciamento de identidade e acesso (IAM):

bigquery.capacityCommitments.list 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
BigQuery Resource Viewer
BigQuery User

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

Ver compromissos de capacidade por projeto

Para visualizar seus compromissos de capacidade por projeto:

Console

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

Ir para o BigQuery
No painel de navegação, acesse a seção Gerenciamento de capacidade.
Clique na guia Compromissos de slot. Os compromissos de capacidade são listados na tabela em Compromissos.

SQL

Para ver os compromissos de um projeto de administração, consulte a visualização INFORMATION_SCHEMA.CAPACITY_COMMITMENTS_BY_PROJECT.

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

Ir para o BigQuery

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

SELECT
  capacity_commitment_id
FROM
  `region-LOCATION`.INFORMATION_SCHEMA.CAPACITY_COMMITMENTS_BY_PROJECT
WHERE
  project_id = 'ADMIN_PROJECT_ID'
  AND slot_count = 100;

Substitua:

LOCATION: o local dos compromissos
ADMIN_PROJECT_ID: o ID do projeto do projeto de administração que tem os compromissos

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--capacity_commitment para listar os compromissos de um projeto de administração.

bq ls \
    --capacity_commitment=true \
    --location=LOCATION \
    --project_id=ADMIN_PROJECT_ID

Substitua:

LOCATION: o local dos compromissos
ADMIN_PROJECT_ID: o ID do projeto de administração que contém os compromissos.

Atualizar compromissos de capacidade

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

Atualizar o plano de renovação do compromisso
Converta um compromisso em um plano de compromisso com uma duração mais longa.
Dividir um compromisso em dois compromissos.
Mesclar dois compromissos em um único compromisso.

Permissões necessárias

Para atualizar os compromissos de capacidade, você precisa da seguinte permissão de gerenciamento de identidade e acesso (IAM):

bigquery.capacityCommitments.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

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

Atualizar um compromisso

Os compromissos anuais têm um plano de renovação, que você especifica ao criar ou converter em um compromisso anual. É possível alterar seu plano de renovação do compromisso anual a qualquer momento antes da data de término do compromisso.

Console

É possível alterar seu plano de renovação de um compromisso anual da seguinte maneira:

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

Ir para o BigQuery
No painel de navegação, acesse a seção Gerenciamento de capacidade.
Clique na guia Compromissos de slot.
Localize o compromisso que você quer editar.
Clique em Ações e selecione a opção Editar plano de renovação.
Selecione o novo plano de renovação.

bq

Para alterar a escolha do plano de renovação de um compromisso anual, use o bq update comando com o --capacity_commitment bandeira e a--renewal_plan bandeira de dados.

bq update \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --renewal_plan=PLAN_TYPE \
    --capacity_commitment=true \
    COMMITMENT_ID

Substitua:

ADMIN_PROJECT_ID: o ID do projeto de administração que vai manter a propriedade desse compromisso.
LOCATION: o local do compromisso.
PLAN_TYPE: o tipo de plano, como ANNUAL ou THREE_YEAR.
COMMITMENT_ID: o ID do compromisso

Para conseguir o ID, consulte Ver compromissos adquiridos.

Converter um compromisso para que tenha uma duração maior

Você pode optar por converter seu compromisso em um tipo de maior duração a qualquer momento.

Assim que você atualizar o compromisso, será cobrado pela taxa de associação ao novo plano e a data de término será redefinida.

Para converter um compromisso, use o comandobq update com a sinalização--plan.

bq update \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --plan=PLAN_TYPE \
    --renewal_plan=RENEWAL_PLAN \
    --capacity_commitment=true \
    COMMITMENT_ID

Substitua:

ADMIN_PROJECT_ID: o ID do projeto;
LOCATION: o local do compromisso.
PLAN_TYPE: o tipo de plano, como ANNUAL ou THREE_YEAR.
RENEWAL_PLAN: o plano de renovação

Isso se aplicará somente se PLAN_TYPE for ANNUAL.
COMMITMENT_ID: o ID do compromisso

Para conseguir o ID, consulte Ver compromissos adquiridos.

Dividir um compromisso

É possível dividir seu compromisso em dois compromissos. Isso pode ser útil se você quiser renovar parte de um compromisso. Por exemplo, se você tiver um compromisso anual de 1.000 slots, poderá dividir 300 slots em um novo compromisso, deixando 700 slots no compromisso original. Em seguida, é possível renovar 700 slots pela taxa anual e converter 300 slots em um compromisso de três anos.

Quando você divide um compromisso, o novo tem o mesmo plano e a mesma data de término do compromisso original.

Console

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

Ir para o BigQuery
No painel de navegação, acesse a seção Gerenciamento de capacidade.
Clique na guia Compromissos de slot.
Selecione o compromisso que você quer dividir.
Clique em Dividir.
Na página Dividir compromisso, use o controle deslizante Configurar divisão para selecionar quantos slots são colocados em cada divisão, em incrementos de 100 slots.
Clique em Dividir para dividir o compromisso. O novo compromisso é listado na guia Compromissos de slot.

bq

Para dividir compromissos, use o comando bq update.

bq update \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --split \
    --slots=SLOTS_TO_SPLIT \
    --capacity_commitment=true \
    COMMITMENT_ID

Substitua:

ADMIN_PROJECT_ID: o ID do projeto;
LOCATION: o local do compromisso.
SLOTS_TO_SPLIT é o número de slots a serem divididos do compromisso original em um novo compromisso.
COMMITMENT_ID: o ID do compromisso

Para conseguir o ID, consulte Ver compromissos adquiridos.

Mesclar dois compromissos

É possível mesclar vários compromissos em um compromisso. Os compromissos mesclados precisam ser do mesmo tipo (ANNUAL ou THREE_YEAR). A data de término do compromisso combinado é a data de término máxima dos compromissos originais. Se algum dos compromissos tiver uma data de término anterior, eles serão estendidos para a data posterior e você será cobrado por um valor proporcional para esses slots.

Console

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

Ir para o BigQuery
No painel de navegação, acesse a seção Gerenciamento de capacidade.
Clique na guia Compromissos de slot.
Selecione os compromissos que você quer mesclar.
Clique em Merge.
Na página Mesclar compromissos, revise os detalhes da mesclagem e clique em Mesclar. O novo compromisso mesclado está listado na guia Compromissos de slot.

bq

Para mesclar dois compromissos em um compromisso, use o comando bq update:

bq update \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --merge=true \
    --capacity_commitment=true \
    COMMITMENT1,COMMITMENT2

Substitua:

ADMIN_PROJECT_ID: o ID do projeto;
LOCATION: o local dos compromissos
COMMITMENT1: o primeiro compromisso a ser mesclado.
COMMITMENT2: o segundo compromisso a ser mesclado

Expiração do compromisso

Os compromissos expiram ao final da duração. Não é possível excluir um compromisso enquanto ele ainda está ativo. Se o plano de renovação estiver definido como NONE, o compromisso será excluído automaticamente. Caso contrário, ele será renovado com um compromisso anual ou de três anos, dependendo do plano de renovação. Para alterar o plano de renovação para NONE, siga as etapas em Renovar um compromisso.

Depois de renovar um compromisso, o valor de Horário de início não é alterado. Ele se refere ao horário de início do compromisso original. O valor de End time é o horário de expiração do compromisso renovado. Por exemplo, se você tiver um compromisso anual criado em 13 de dezembro de 2022 e renovado em 13 de dezembro de 2023. Se você consultar os detalhes do contrato em 14 de dezembro de 2023, o valor de Início será 13 de dezembro de 2022, e o valor de Término será 12 de dezembro de 2024.

Os slots de valor de referência sempre são carregados. Se um compromisso de capacidade expirar, talvez seja necessário ajustar manualmente a quantidade de slots de valor de referência nas reservas para evitar cobranças indesejadas. Por exemplo, considere que você tem um compromisso de um ano com 100 slots e uma reserva com 100 slots de valor de referência. O compromisso expira e não tem um plano de renovação. Quando o compromisso expirar, você pagará por 100 slots de valor de referência com a taxa de pagamento por utilização.

Controlar a criação de compromissos de capacidade

É possível usar políticas de negação do IAM para ter mais controle sobre quem pode criar compromissos de capacidade.

As políticas de negação podem ser criadas para um conjunto de usuários ou para todos e podem ser configuradas com exceções e condições.

Por exemplo, a política a seguir nega a todos os usuários a permissão para criar compromissos de capacidade, com exceção do principal "lucian@example.com":

{
  "deniedPrincipals": [
    "principalSet://goog/public:all"
  ],
  "deniedPermissions": [
    "bigquery.googleapis.com/capacityCommitments.create"
  ],
  "exceptionPrincipals": [
    "principal://goog/subject/lucian@example.com"
  ]
}

Essa política pode ser anexada a uma organização para controlar quem pode criar os compromissos.

Lembre-se que essas políticas têm precedência sobre os papéis do IAM. Portanto, mesmo um usuário com o papel bigquery.admin não poderia criar um compromisso, a menos que a política seja excluída ou modificada.

Para mais informações, consulte Negar acesso a recursos.

Como resolver problemas de compromissos de capacidade

Nesta seção, descrevemos etapas de solução de problemas que podem ser úteis se você tiver problemas ao usar o BigQuery Reservations.

Slots comprados pendentes

Os slots estão sujeitos à capacidade disponível. Quando você compra compromissos de slot e o BigQuery os aloca, a coluna Status mostra uma marca de verificação. Se o BigQuery não conseguir alocar os slots solicitados imediatamente, a coluna Status permanecerá pendente. Talvez seja necessário aguardar várias horas para que os slots fiquem disponíveis. Se você precisar de acesso aos slots mais cedo, tente o seguinte:

Excluir o compromisso pendente.
Adquira um novo compromisso para um número menor de slots. Dependendo da capacidade, o compromisso menor pode ficar ativo imediatamente.
Compre os slots restantes como um compromisso separado. Esses slots podem ser exibidos como pendentes na coluna Status, mas geralmente ficam ativos em algumas horas.
Opcional: quando ambos os compromissos estiverem disponíveis, é possível mesclá-los em um único compromisso, desde que você tenha comprado o mesmo plano para ambos.

Se um compromisso de slot falhar ou demorar muito para ser concluído, considere usar o preço sob demanda temporariamente. Com essa solução, pode ser necessário executar consultas críticas em um projeto diferente que não está atribuído a nenhuma reserva, ou talvez seja preciso remover completamente a atribuição do projeto.