Gerenciar configurações padrão

Este documento descreve como criar e recuperar as configurações padrão no nível da organização ou para envolvidos no projeto.

Para ajudar a gerenciar jobs, defina configurações padrão no BigQuery. As configurações que usam esse serviço são definidas no nível da organização ou para envolvidos no projeto, mas podem ser substituídas no nível da sessão ou do job. É possível definir configurações padrão em conjunto com políticas da organização relacionadas para aplicar o comportamento padrão.

Preços

Não há cobrança adicional por usar o serviço de configuração do BigQuery. Para saber mais informações, consulte Preços.

Configurações padrão

É possível especificar as seguintes configurações padrão:

  • default_batch_query_queue_timeout_ms: o tempo padrão, em milissegundos, que uma consulta em lote fica na fila. Quando não está definido, o padrão é 24 horas. O valor mínimo é 1 milissegundo. O valor máximo é 48 horas. Para desativar o enfileiramento de consultas em lote, defina o valor como -1.
  • default_column_name_character_map: o escopo e o processamento padrão de caracteres em nomes de colunas. Se não for definido, os jobs de carregamento que usam caracteres incompatíveis nos nomes de colunas vão apresentar falha com uma mensagem de erro. Algumas tabelas mais antigas podem ser definidas para substituir caracteres não compatíveis nos nomes das colunas. Para mais informações, consulte load_option_list.
  • default_interactive_query_queue_timeout_ms: o tempo padrão, em milissegundos, que uma consulta interativa fica na fila. Quanto não está definido, o padrão é seis horas. O valor mínimo é 1 milissegundo. O valor máximo é 48 horas. Para desativar o enfileiramento de consultas interativas, defina o valor como -1.
  • default_kms_key_name: a chave padrão do Cloud Key Management Service para criptografar dados de tabela, incluindo tabelas temporárias ou anônimas. Para mais informações, consulte Chaves do Cloud KMS gerenciadas pelo cliente.
  • default_query_job_timeout_ms: o tempo padrão após o qual um job de consulta expira, incluindo o tempo do job na fila e o tempo gasto na execução. O período do tempo limite precisa ser de 5 minutos a 6 horas. Esse tempo limite se aplica apenas a jobs de consulta individuais e aos jobs filhos de scripts. Para definir um tempo limite para jobs de script, use o método da API jobs.insert e defina o campo jobTimeoutMs.

  • default_query_optimizer_options: as otimizações de consulta baseadas no histórico. Essa opção pode ser:

    • 'adaptive=on': use otimizações de consulta baseadas no histórico.
    • 'adaptive=off': não use otimizações de consulta baseadas no histórico.
    • NULL (padrão): use as otimizações de consulta baseadas no histórico padrão, que é equivalente a 'adaptive=off'.

  • default_time_zone: o fuso horário padrão a ser usado em funções SQL dependentes de fuso horário, quando um fuso horário não for especificado como um argumento. Essa configuração não se aplica a tabelas particionadas por coluna de unidade de tempo (que usam UTC como fuso horário), transferências programadas do Serviço de transferência do Cloud Storage ou carregamento de dados com a ferramenta de linha de comando bq. Para mais informações, consulte Fusos horários.

  • default_storage_billing_model: o modelo de faturamento de armazenamento padrão para os novos conjuntos de dados. Defina o valor como PHYSICAL para usar bytes físicos ao calcular as cobranças de armazenamento ou como LOGICAL para usar bytes lógicos. A alteração do modelo de faturamento padrão de armazenamento não afeta os conjuntos de dados atuais. Para mais informações, consulte Modelos de faturamento do Storage.

  • default_max_time_travel_hours: a janela de viagem no tempo padrão em horas para novos conjuntos de dados. Essa duração precisa estar no intervalo de 48 a 168, inclusive, e ser divisível por 24. Mudar o tempo máximo de viagem padrão não afeta os conjuntos de dados atuais. Para mais informações, consulte Viagem no tempo.

Criar configurações padrão

Nesta seção, descrevemos como criar uma configuração.

Permissões necessárias

Para criar uma configuração, você precisa da permissão bigquery.config.update do Identity and Access Management (IAM). O papel predefinido roles/bigquery.admin do IAM inclui as permissões necessárias para criar uma configuração.

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

Definir as configurações padrão

É possível definir as configurações padrão no nível da organização ou para envolvidos no projeto usando as seguintes instruções SQL. Ao criar a configuração, é necessário especificar a região em que ela será aplicada. Só é possível usar uma região em cada instrução.

Definir as configurações da organização

Para definir as configurações da organização, use a instrução DDL ALTER ORGANIZATION SET OPTIONS. No exemplo a seguir, definimos o fuso horário padrão como America/Chicago, a chave padrão do Cloud KMS como uma chave definida pelo usuário, o tempo limite padrão da consulta como 30 minutos, o tempo limite padrão da fila de consultas interativas como 10 minutos e o tempo limite padrão da fila de consultas em lote para 20 minutos:

ALTER ORGANIZATION
SET OPTIONS (
  `region-REGION.default_time_zone`= 'America/Chicago',
  -- Ensure all service accounts under the organization have permission to KMS_KEY
  `region-REGION.default_kms_key_name` = KMS_KEY,
  `region-REGION.default_query_job_timeout_ms` = 1800000,
  `region-REGION.default_interactive_query_queue_timeout_ms` = 600000,
  `region-REGION.default_batch_query_queue_timeout_ms` = 1200000,
  `region-REGION.default_storage_billing_model`= PHYSICAL,
  `region-REGION.default_max_time_travel_hours` = 72);

Substitua:

  • REGION: a região associada ao projeto ou à organização. Por exemplo, us ou europe-west6.
  • KMS_KEY: uma chave do Cloud KMS definida pelo usuário. Para mais informações sobre as chaves do Cloud KMS, consulte Chaves do Cloud KMS gerenciadas pelo cliente.

O exemplo a seguir limpa todas as configurações padrão no nível da organização:

ALTER ORGANIZATION
SET OPTIONS (
  `region-REGION.default_time_zone` = NULL,
  `region-REGION.default_kms_key_name` = NULL,
  `region-REGION.default_query_job_timeout_ms` = NULL,
  `region-REGION.default_interactive_query_queue_timeout_ms` = NULL,
  `region-REGION.default_batch_query_queue_timeout_ms` = NULL,
  `region-REGION.default_storage_billing_model`= NULL,
  `region-REGION.default_max_time_travel_hours` = NULL);

Definir configurações do projeto

Para definir as configurações do projeto, use a instrução DDL ALTER PROJECT SET OPTIONS. A instrução DDL ALTER PROJECT SET OPTIONS aceita opcionalmente a variável project_id. Quando o project_id não é especificado, o padrão é o projeto atual em que a consulta é executada. No exemplo a seguir, definimos o fuso horário padrão como America/Los_Angeles, a chave padrão do Cloud KMS como um exemplo de chave, o tempo limite padrão da consulta como 1 hora, o tempo limite padrão da fila de consultas interativas como 10 minutos e o tempo limite padrão da fila de consultas em lote para 20 minutos:

ALTER PROJECT project_id
SET OPTIONS (
  `region-REGION.default_time_zone` = 'America/Los_Angeles',
  -- Ensure all service accounts under the project have permission to KMS_KEY
  `region-REGION.default_kms_key_name` = KMS_KEY,
  `region-REGION.default_query_job_timeout_ms` = 3600000,
  `region-REGION.default_interactive_query_queue_timeout_ms` = 600000,
  `region-REGION.default_batch_query_queue_timeout_ms` = 1200000,
  `region-REGION.default_storage_billing_model`= PHYSICAL,
  `region-REGION.default_max_time_travel_hours` = 72);

O exemplo a seguir limpa todas as configurações padrão para envolvidos no projeto. As configurações padrão usarão aquelas no nível da organização, se houver. Caso contrário, todas as configurações padrão serão definidas como o padrão global.

ALTER PROJECT project_id
SET OPTIONS (
  `region-REGION.default_time_zone` = NULL,
  `region-REGION.default_kms_key_name` = NULL,
  `region-REGION.default_query_job_timeout_ms` = NULL,
  `region-REGION.default_interactive_query_queue_timeout_ms` = NULL,
  `region-REGION.default_batch_query_queue_timeout_ms` = NULL,
  `region-REGION.default_storage_billing_model`= NULL,
  `region-REGION.default_max_time_travel_hours` = NULL);

As configurações no nível do projeto modificam as da organização. As configurações para envolvidos no projeto podem ser substituídas por configurações no nível da sessão, que podem ser substituídas por configurações no nível do job.

Recuperar valores de configuração

É possível ver as configurações padrão de uma organização ou de um projeto visualizando o esquema de informações. Há três visualizações diferentes a serem consultadas:

Pode levar alguns minutos para que as novas configurações entrem em vigor e sejam refletidas na visualização INFORMATION_SCHEMA.

Permissões necessárias

Para recuperar valores de configuração, você precisa da permissão bigquery.config.get do IAM.

Cada um dos seguintes papéis predefinidos do IAM inclui as permissões necessárias para acessar a configuração da visualização INFORMATION_SCHEMA:

  • roles/bigquery.jobUser
  • roles/bigquery.dataEditor
  • roles/bigquery.dataUser

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

Exemplos

Para ver as configurações em uma organização na região us, execute a seguinte consulta:

SELECT * FROM region-us.INFORMATION_SCHEMA.ORGANIZATION_OPTIONS;

Para ver as configurações efetivas no projeto padrão na região us, execute a seguinte consulta:

SELECT * FROM region-us.INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS;

Para ver as configurações no projeto padrão na região us, execute a seguinte consulta:

SELECT * FROM region-us.INFORMATION_SCHEMA.PROJECT_OPTIONS;