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 configurações padrão para as seguintes configurações:

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

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

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

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

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

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;