Trabalhar com atribuições de reserva

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.

Criar atribuições de reserva

Para usar os slots comprados, crie uma atribuição que atribui um projeto, uma pasta ou uma organização a uma reserva de slot.

Os projetos usam a reserva mais específica na hierarquia de recursos a que são atribuídos. Uma atribuição de pasta substitui uma atribuição de organização, e uma atribuição de projeto modifica uma atribuição de pasta. As atribuições de pasta e organização não estão disponíveis para reservas da edição padrão.

Para criar uma atribuição em uma reserva, ela precisa atender a pelo menos um dos seguintes critérios:

Ele é configurado com uma quantidade diferente de zero de slots de valor de referência atribuídos.
Ele é configurado com uma quantidade diferente de zero de slots de escalonamento automático.
Ele é configurado para usar slots ociosos e há slots ociosos disponíveis no projeto.

Se você tentar atribuir um recurso a uma reserva que não atende a pelo menos um desses critérios, a seguinte mensagem será exibida: Assignment is pending, your project will be executed as on-demand..

É possível atribuir um recurso a uma reserva de failover, mas a atribuição fica pendente no local secundário.

Permissões necessárias

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

bigquery.reservationAssignments.create no projeto de administração e responsável.

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.

Atribuir uma organização a uma reserva

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 Reservas.
Encontrar a reserva na tabela de reservas
Expanda a opção Ações.
Clique em Criar atribuição.
Na seção Criar uma atribuição, clique em Procurar.
Procure ou pesquise a organização e a selecione.
Na seção Tipo de job, selecione um tipo de job para atribuir a essa reserva. As opções incluem:
- QUERY
- CONTINUOUS (Pré-lançamento)
- PIPELINE
- BACKGROUND
- ML_EXTERNAL
Para mais informações sobre tipos de jobs, consulte Atribuições de reserva. Esse valor padrão é QUERY.
Clique em Criar.

SQL

Para atribuir uma organização a uma reserva, use a instrução DDL CREATE ASSIGNMENT.

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

Ir para o BigQuery
No editor de consultas, digite a seguinte instrução:
```
CREATE ASSIGNMENT
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME.ASSIGNMENT_ID`
OPTIONS (
  assignee = 'organizations/ORGANIZATION_ID',
  job_type = 'JOB_TYPE');
```
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
- ASSIGNMENT_ID: o ID da atribuição.
  
  Ele precisa ser exclusivo do projeto e do local, começar e terminar com uma letra minúscula ou um número e conter apenas letras minúsculas, números e traços.
- ORGANIZATION_ID: o ID da organização.
- JOB_TYPE: o tipo de job a ser atribuído a essa reserva, como QUERY, CONTINUOUS (Pré-lançamento), PIPELINE, BACKGROUND ou ML_EXTERNAL
Clique em Executar.

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

bq

Para atribuir os jobs de uma organização a uma reserva, use o comando bq mk com a sinalização --reservation_assignment:

bq mk \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment \
    --reservation_id=RESERVATION_NAME \
    --assignee_id=ORGANIZATION_ID \
    --job_type=JOB_TYPE \
    --assignee_type=ORGANIZATION

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
ORGANIZATION_ID: o ID da organização.
JOB_TYPE: o tipo de job a ser atribuído a essa reserva, como QUERY, CONTINUOUS (Pré-lançamento), PIPELINE, BACKGROUND ou ML_EXTERNAL

Ao criar uma atribuição de reserva, aguarde pelo menos cinco minutos antes de executar uma consulta. Caso contrário, a consulta poderá ser cobrada por meio de preços sob demanda.

Atribuir um projeto ou uma pasta a uma reserva

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 Reservas.
Encontrar a reserva na tabela de reservas
Expanda a opção Ações.
Clique em Criar atribuição.
Na seção Criar uma atribuição, clique em Procurar.
Procure ou pesquise o projeto ou a pasta e selecione-o.
Na seção Tipo de job, selecione um tipo de job para atribuir a essa reserva. As opções incluem:
- QUERY
- CONTINUOUS (Pré-lançamento)
- PIPELINE
- BACKGROUND
- ML_EXTERNAL
Para mais informações sobre tipos de jobs, consulte Atribuições de reserva. Esse valor padrão é QUERY.
Clique em Criar.

SQL

Para atribuir um projeto a uma reserva, use a instrução DDL CREATE ASSIGNMENT.

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

Ir para o BigQuery
No editor de consultas, digite a seguinte instrução:
```
CREATE ASSIGNMENT
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME.ASSIGNMENT_ID`
OPTIONS(
  assignee="projects/PROJECT_ID",
  job_type="JOB_TYPE");
```
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
- ASSIGNMENT_ID: o ID da atribuição.
  
  Ele precisa ser exclusivo do projeto e do local, começar e terminar com uma letra minúscula ou um número e conter apenas letras minúsculas, números e traços.
- PROJECT_ID: o ID do projeto a ser atribuído à reserva.
- JOB_TYPE: o tipo de job a ser atribuído a essa reserva, como QUERY, CONTINUOUS (Pré-lançamento), PIPELINE, BACKGROUND ou ML_EXTERNAL
Clique em Executar.

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

bq

Para atribuir jobs a uma reserva, use o comando bq mk com a sinalização --reservation_assignment:

bq mk \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment \
    --reservation_id=RESERVATION_NAME \
    --assignee_id=PROJECT_ID \
    --job_type=JOB_TYPE \
    --assignee_type=PROJECT

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
PROJECT_ID: o ID do projeto a ser atribuído a essa reserva.
JOB_TYPE: o tipo de job a ser atribuído a essa reserva, como QUERY, CONTINUOUS (Pré-lançamento), PIPELINE, BACKGROUND ou ML_EXTERNAL

Terraform

Use o recurso google_bigquery_reservation_assignment.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

O exemplo a seguir atribui um projeto à reserva chamada 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
  }
}

data "google_project" "project" {}

resource "google_bigquery_reservation_assignment" "default" {
  assignee    = "projects/${data.google_project.project.project_id}"
  job_type    = "QUERY"
  reservation = google_bigquery_reservation.default.id
}

Para aplicar a configuração do Terraform em um projeto do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

Inicie o Cloud Shell.
Defina o projeto padrão do Google Cloud em que você quer aplicar as configurações do Terraform.

Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

Copie o exemplo de código no main.tf recém-criado.

Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.
Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
Salve as alterações.
Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.
```
terraform init
```
Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade:
```
terraform init -upgrade
```

Aplique as alterações

Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas:
```
terraform plan
```
Faça as correções necessárias na configuração.
Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:
```
terraform apply
```
Aguarde até que o Terraform exiba a mensagem "Apply complete!".
Abra seu projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU para verificar se foram criados ou atualizados pelo Terraform.

Ao criar uma atribuição de reserva, aguarde pelo menos cinco minutos antes de executar uma consulta. Caso contrário, a consulta poderá ser cobrada por meio de preços sob demanda.

Para criar um projeto que usa apenas slots inativos, crie uma reserva com 0 slots atribuídos e siga as etapas acima para atribuir o projeto a ela.

Atribuir um projeto a `none`

Atribuir para none representa a ausência de atribuição. Os projetos atribuídos a none usam preços sob demanda.

SQL

Para atribuir um projeto a none, use a instrução DDL CREATE ASSIGNMENT.

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

Ir para o BigQuery
No editor de consultas, digite a seguinte instrução:
```
CREATE ASSIGNMENT
  `ADMIN_PROJECT_ID.region-LOCATION.none.ASSIGNMENT_ID`
OPTIONS(
  assignee="projects/PROJECT_ID",
  job_type="QUERY");
```
Substitua:
- LOCATION: o local dos jobs que precisam usar preços sob demanda
- ASSIGNMENT_ID: o ID da atribuição.
  
  Ele precisa ser exclusivo do projeto e do local, começar e terminar com uma letra minúscula ou um número e conter apenas letras minúsculas, números e traços.
- PROJECT_ID: o ID do projeto a ser atribuído à reserva.
Clique em Executar.

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

bq

Para atribuir um projeto a none, use o comando bq mk com a sinalização --reservation_assignment:

bq mk \
    --location=LOCATION \
    --reservation_assignment \
    --reservation_id=none \
    --job_type=QUERY \
    --assignee_id=PROJECT_ID \
    --assignee_type=PROJECT

Substitua:

LOCATION: o local dos jobs que precisam usar preços sob demanda
PROJECT_ID: o ID do projeto a ser atribuído a none.

Terraform

Use o recurso google_bigquery_reservation_assignment.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

O exemplo a seguir atribui um projeto a none:

data "google_project" "project" {}

resource "google_bigquery_reservation_assignment" "default" {
  assignee    = "projects/${data.google_project.project.project_id}"
  job_type    = "QUERY"
  reservation = "projects/${data.google_project.project.project_id}/locations/us/reservations/none"
}

Para aplicar a configuração do Terraform em um projeto do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

Inicie o Cloud Shell.
Defina o projeto padrão do Google Cloud em que você quer aplicar as configurações do Terraform.

Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

Copie o exemplo de código no main.tf recém-criado.

Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.
Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
Salve as alterações.
Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.
```
terraform init
```
Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade:
```
terraform init -upgrade
```

Aplique as alterações

Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas:
```
terraform plan
```
Faça as correções necessárias na configuração.
Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:
```
terraform apply
```
Aguarde até que o Terraform exiba a mensagem "Apply complete!".
Abra seu projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU para verificar se foram criados ou atualizados pelo Terraform.

Atribuir slots a cargas de trabalho do BigQuery ML

Os seguintes tipos de modelo do BigQuery ML usam serviços externos:

É possível atribuir slots reservados a consultas com esses serviços usando o tipo de atribuição ML_EXTERNAL. Se nenhum tipo de atribuição ML_EXTERNAL for encontrado, o job de consulta será executado sob demanda.

Use o comando bq mk com a sinalização --reservation_assignment e defina a sinalização --job_type como ML_EXTERNAL.

bq mk \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment \
    --reservation_id=RESERVATION_NAME \
    --job_type=ML_EXTERNAL\
    --assignee_id=PROJECT_ID \
    --assignee_type=PROJECT

Substitua:

ADMIN_PROJECT_ID: o ID do projeto que é proprietário do recurso de reserva.
LOCATION: o local da reserva
RESERVATION_NAME: o nome da reserva
PROJECT_ID: o ID do projeto a ser atribuído a essa reserva.

Encontrar atribuições de reserva

Permissões necessárias

Para pesquisar uma atribuição de reserva para um determinado projeto, pasta ou organização, você precisa da seguinte permissão de gerenciamento de identidade e acesso (IAM):

bigquery.reservationAssignments.list no projeto de administração.

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.

Encontrar a atribuição de reserva de um projeto

Para descobrir se o projeto, a pasta ou a organização está atribuída a uma reserva, faça o seguinte:

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 Reservas.
Na tabela de reservas, expanda uma reserva para conferir quais recursos estão atribuídos a ela ou use o campo Filtro para filtrar por nome do recurso.

SQL

Para encontrar a reserva a que os jobs de consulta do projeto estão atribuídos, consulte a visualização INFORMATION_SCHEMA.ASSIGNMENTS_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
    assignment_id
  FROM `region-LOCATION`.INFORMATION_SCHEMA.ASSIGNMENTS_BY_PROJECT
  WHERE
    assignee_id = 'PROJECT_ID'
    AND job_type = 'JOB_TYPE';
```
Substitua:
- LOCATION: o local das reservas para visualizar
- ADMIN_PROJECT_ID: o ID do projeto de administração que é proprietário do recurso de reserva.
- PROJECT_ID: o ID do projeto a ser atribuído à reserva.
- JOB_TYPE: o tipo de job a ser atribuído a essa reserva, como QUERY, CONTINUOUS (Pré-lançamento), PIPELINE, BACKGROUND ou ML_EXTERNAL
Clique em Executar.

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

bq

Para descobrir a qual reserva os jobs de consulta do projeto estão atribuídos, use o comando bq show com a sinalização --reservation_assignment:

bq show \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment \
    --job_type=JOB_TYPE \
    --assignee_id=PROJECT_ID \
    --assignee_type=PROJECT

Substitua:

ADMIN_PROJECT_ID: o ID do projeto que é proprietário do recurso de reserva.
LOCATION: o local das reservas para visualizar
JOB_TYPE: o tipo de job a ser atribuído a essa reserva, como QUERY, CONTINUOUS (Pré-lançamento), PIPELINE, BACKGROUND ou ML_EXTERNAL
PROJECT_ID: o ID do projeto

Atualizar atribuições de reserva

Como mover uma atribuição para outra reserva

Você pode mover uma atribuição de uma reserva para outra.

Para mover uma atribuição de reserva, é preciso ter as seguintes permissões de gerenciamento de identidade e acesso (IAM) no projeto de administração e no responsável.

bigquery.reservationAssignments.create
bigquery.reservationAssignments.delete

Cada um dos papéis predefinidos do IAM a seguir inclui estas permissões:

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.

Para mover uma atribuição, use o comando bq update:

bq update \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment \
    --destination_reservation_id=DESTINATION_RESERVATION \
    ADMIN_PROJECT_ID:LOCATION.RESERVATION_NAME.ASSIGNMENT_ID

Substitua:

ADMIN_PROJECT_ID: o ID do projeto que é proprietário do recurso de reserva.
LOCATION: o local da nova reserva
RESERVATION_NAME: a reserva de onde a atribuição será movida
DESTINATION_RESERVATION: a reserva para onde a atribuição será movida.
ASSIGNMENT_ID: o ID da atribuição.

Para conseguir o ID da atribuição, consulte Listar a atribuição da reserva de um projeto.

Excluir atribuições de reserva

É possível remover um projeto de uma reserva excluindo a atribuição da reserva. Se um projeto não estiver atribuído a nenhuma reserva, ele herdará todas as atribuições nas pastas ou organizações pai. Caso contrário, se não existirem atribuições pai, usará preços sob demanda.

Quando você exclui uma atribuição de reserva, os jobs em execução com slots dessa reserva continuam sendo executados até a conclusão.

Permissões necessárias

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

bigquery.reservationAssignments.delete no projeto de administração e responsável.

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

BigQuery Admin
BigQuery Resource Admin
BigQuery Resource Editor

Remover um projeto de uma reserva

Para remover um projeto de uma reserva:

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 Reservas.
Na tabela de reservas, expanda a reserva para encontrar o projeto.
Expanda a opção Ações.
Clique em Excluir.

SQL

Use a instrução DDL DROP ASSIGNMENT.

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

Ir para o BigQuery
No editor de consultas, digite a seguinte instrução:
```
DROP ASSIGNMENT
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME.ASSIGNMENT_ID`;
```
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
- ASSIGNMENT_ID: o ID da atribuição.
  
  Para encontrar o ID da atribuição, consulte Listar a atribuição da reserva de um projeto.
Clique em Executar.

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

bq

Para remover um projeto de uma reserva, use o comando bq rm com a sinalização --reservation_assignment:

bq rm \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment RESERVATION_NAME.ASSIGNMENT_ID

Substitua:

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

Para conseguir o ID da atribuição, consulte Listar a atribuição da reserva de um projeto.

Trabalhar com atribuições de reserva

Criar atribuições de reserva

Permissões necessárias

Atribuir uma organização a uma reserva

Console

SQL

bq

Atribuir um projeto ou uma pasta a uma reserva

Console

SQL

bq

Terraform

Preparar o Cloud Shell

Preparar o diretório

Aplique as alterações

Atribuir um projeto a none

SQL

bq

Terraform

Preparar o Cloud Shell

Preparar o diretório

Aplique as alterações

Atribuir slots a cargas de trabalho do BigQuery ML

Encontrar atribuições de reserva

Permissões necessárias

Encontrar a atribuição de reserva de um projeto

Console

SQL

bq

Atualizar atribuições de reserva

Como mover uma atribuição para outra reserva

Excluir atribuições de reserva

Permissões necessárias

Remover um projeto de uma reserva

Console

SQL

bq

Atribuir um projeto a `none`