Gerenciar configurações

Os administradores do BigQuery e os proprietários de projetos podem gerenciar as configurações no nível da organização e do projeto. É possível definir configurações para reforçar a segurança, controlar custos e otimizar o desempenho das consultas em toda a infraestrutura de dados. Ao definir valores padrão, é possível garantir conformidade e eficiência operacional consistentes, facilitando o gerenciamento do ambiente do BigQuery.

Especificar configurações

As seções a seguir descrevem como especificar as configurações de configuração padrão. As configurações padrão são definidas no nível da organização ou do projeto, mas podem ser substituídas no nível da sessão ou do job. Para aplicar o comportamento padrão, configure as configurações padrão em combinação com políticas organizacionais relacionadas.

Funções exigidas

Para ter a permissão necessária para especificar uma configuração, peça ao administrador para conceder a você o papel do IAM de Administrador do BigQuery (roles/bigquery.admin). Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão bigquery.config.update, que é necessária para especificar uma configuração.

Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

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 da organização

É possível configurar as definições no nível da organização usando as seguintes instruções do GoogleSQL. Ao especificar 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.

Para definir as configurações da organização, use a instrução DDL ALTER ORGANIZATION SET OPTIONS. O exemplo a seguir especifica várias configurações padrão, incluindo:

  • Fuso horário: America/Chicago
  • Chave do Cloud KMS: uma chave definida pelo usuário
  • Tempo limite da consulta: 30 minutos (1.800.000 milissegundos)
  • Tempo limite da fila de consultas interativas: 10 minutos (600.000 milissegundos)
  • Tempo limite da fila de consultas em lote: 20 minutos (1.200.000 milissegundos)
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`= BILLING_MODEL,
  `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, consulte Chaves do Cloud KMS gerenciadas pelo cliente.
  • BILLING_MODEL: o modelo de armazenamento para novos conjuntos de dados. Por exemplo, PHYSICAL para bytes físicos.

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

É possível configurar as definições no nível do projeto usando as seguintes instruções do GoogleSQL. Ao especificar 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.

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. O exemplo a seguir especifica várias configurações padrão:

  • Fuso horário: America/Los_Angeles
  • Chave do Cloud KMS: um exemplo de chave
  • Tempo limite da consulta: 1 hora
  • Tempo limite da fila de consultas interativas: 10 minutos
  • Tempo limite da fila de consultas em lote: 20 minutos
  • Justiça com base em reserva: ativada
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`= BILLING_MODEL,
  `region-REGION.default_max_time_travel_hours` = 72,
  `region-REGION.default_cloud_resource_connection_id` = CONNECTION_ID,
  `region-REGION.default_sql_dialect_option` = 'default_google_sql',
  `region-REGION.enable_reservation_based_fairness` = true);

Substitua:

  • PROJECT_ID: o ID do projeto.
  • 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, consulte Chaves do Cloud KMS gerenciadas pelo cliente.
  • BILLING_MODEL: o modelo de armazenamento para novos conjuntos de dados. Por exemplo, PHYSICAL para bytes físicos.
  • CONNECTION_ID: o ID da conexão a ser usada como a conexão padrão para tabelas e modelos.

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,
  `region-REGION.default_cloud_resource_connection_id` = NULL,
  `region-REGION.default_sql_dialect_option` = NULL,
  `region-REGION.enable_reservation_based_fairness` = 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 configurações

É possível conferir as configurações de uma organização ou projeto usando as seguintes visualizações do INFORMATION_SCHEMA:

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

Funções exigidas

Para ter a permissão necessária para recuperar as configurações, peça ao administrador para conceder a você o papel do IAM de Usuário de jobs do BigQuery (roles/bigquery.jobUser) no projeto especificado. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão bigquery.config.get, que é necessária para recuperar as configurações de configuração.

Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

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;

Configurações

As seções a seguir descrevem as configurações que podem ser especificadas.

Configurações de execução de consultas e jobs

Use as configurações a seguir para controlar como as consultas são executadas, cronometradas e enfileiradas.

  • 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_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_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 tempo limite precisa ser de 5 minutos a 48 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.

  • enable_reservation_based_fairness: a opção que determina como os slots ociosos são compartilhados. O valor padrão é "false", o que significa que os slots ociosos são distribuídos igualmente entre todos os projetos de consulta. Se ativado, os slots ociosos serão compartilhados igualmente entre todas as reservas e, em seguida, entre os projetos dentro da reserva. Para mais informações, consulte justiça baseada em reservas. Essa opção é compatível apenas no nível do projeto. Não é possível especificar no nível da organização ou do trabalho.

  • default_time_zone: o fuso horário padrão a ser usado em funções do GoogleSQL dependentes de fuso horário, quando um fuso horário não é 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_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=on'.

  • default_sql_dialect_option: o dialeto de consulta SQL padrão para executar jobs de consulta usando a ferramenta de linha de comando bq ou a API BigQuery. Alterar essa configuração não afeta o dialeto padrão no console. Essa opção pode ser:

    • 'default_legacy_sql' (padrão): usa o SQL legado se o dialeto de consulta não for especificado no nível do job.
    • 'default_google_sql': use o GoogleSQL se o dialeto de consulta não for especificado no nível do job.
    • 'only_google_sql': use o GoogleSQL se o dialeto de consulta não for especificado no nível do job. Rejeitar jobs com o dialeto de consulta definido como SQL legado.
    • NULL: use a configuração padrão de dialeto de consulta, que é equivalente a 'default_legacy_sql'.

Configurações de gerenciamento de dados

Use as configurações a seguir para definir regras para criação, segurança e ciclo de vida dos dados.

  • 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_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_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 e retenção de dados.

Configurações de custo e recursos

Use as configurações a seguir para determinar como os recursos são faturados e conectados.

  • 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_cloud_resource_connection_id: a conexão padrão a ser usada ao criar tabelas e modelos. Especifique apenas o ID ou o nome da conexão e exclua os prefixos de ID do projeto e região anexados. O uso de conexões padrão pode fazer com que as permissões concedidas à conta de serviço da conexão sejam atualizadas, dependendo do tipo de tabela ou modelo que você está criando. Para mais informações, consulte a Visão geral da conexão padrão.

Preços

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