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

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

  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. Encontrar a reserva na tabela de reservas

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

  6. Clique em Criar atribuição.

  7. Na seção Criar uma atribuição, clique em Procurar.

  8. Procure ou pesquise a organização e a selecione.

  9. Na seção Tipo de job, selecione um tipo de job para atribuir a essa reserva. As opções incluem:

    Para mais informações sobre tipos de jobs, consulte Atribuições de reserva. Esse valor padrão é QUERY.

    Para saber mais sobre como permitir que os usuários usem o Gemini no BigQuery com atribuições da edição Enterprise Plus, consulte Configurar o Gemini no BigQuery.

  10. Clique em Criar.

SQL

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

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

  3. 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:

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

  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. Encontrar a reserva na tabela de reservas

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

  6. Clique em Criar atribuição.

  7. Na seção Criar uma atribuição, clique em Procurar.

  8. Procure ou pesquise o projeto ou a pasta e selecione-o.

  9. Na seção Tipo de job, selecione um tipo de job para atribuir a essa reserva. As opções incluem:

    Para mais informações sobre tipos de jobs, consulte Atribuições de reserva. Esse valor padrão é QUERY.

  10. Clique em Criar.

SQL

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

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

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

  1. Inicie o Cloud Shell.
  2. 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.

  1. 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
  2. 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.

  3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
  4. Salve as alterações.
  5. 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

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

  2. 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!".

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

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

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

  1. Inicie o Cloud Shell.
  2. 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.

  1. 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
  2. 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.

  3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
  4. Salve as alterações.
  5. 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

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

  2. 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!".

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

As seções a seguir fornecem informações sobre os requisitos de atribuição de reserva para modelos do BigQuery ML. Para criar essas atribuições, siga os procedimentos em Atribuir uma organização a uma reserva ou Atribuir um projeto ou pasta a uma reserva.

Modelos externos

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

É possível atribuir slots reservados a consultas com esses serviços criando uma atribuição de reserva que usa o tipo de job ML_EXTERNAL. Se nenhuma atribuição de reserva com um tipo de job ML_EXTERNAL for encontrada, o job de consulta será executado usando o preço sob demanda.

Para jobs treinamento de modelo externos, os slots na atribuição de reserva são usados nas etapas de pré-processamento, treinamento e pós-processamento. Durante o treinamento, os slots não são preemptivos, mas durante o pré-processamento e o pós-processamento, slots inativos podem ser usados.

Modelos de fatoração de matrizes

Para criar um modelo de fatoração de matrizes, você precisa criar uma reserva que use a edição Enterprise ou Enterprise Plus do BigQuery, e depois criar uma atribuição de reserva que use o tipo de job QUERY.

Outros tipos de modelos

Para modelos do BigQuery ML que não são externos ou modelos de fatorização de matriz, é possível atribuir slots reservados a consultas usando esses serviços criando uma atribuição de reserva que usa o tipo de job QUERY. Se nenhuma atribuição de reserva com um tipo de job QUERY for encontrada, o job de consulta será executado usando o preço sob demanda.

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

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

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

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

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

  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. Na tabela de reservas, expanda a reserva para encontrar o projeto.

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

  6. Clique em Excluir.

SQL

Use a instrução DDL DROP ASSIGNMENT.

  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 ASSIGNMENT
      `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME.ASSIGNMENT_ID`;

    Substitua:

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