Faça a gestão das definições de configuração

Este documento descreve como especificar e obter definições de configuração do BigQuery ao nível da organização ou do projeto.

Por exemplo, para ajudar a gerir trabalhos, pode usar este serviço para configurar as predefinições dos trabalhos. As predefinições são configuradas ao nível da organização ou do projeto, mas podem ser substituídas ao nível da sessão ou da tarefa. Pode configurar as predefinições em combinação com políticas organizacionais relacionadas para aplicar o comportamento predefinido.

Definições de configuração

Pode especificar as seguintes definições de configuração:

  • default_batch_query_queue_timeout_ms: o tempo predefinido, em milissegundos, que uma consulta em lote fica na fila. Se não estiver definida, a predefinição é 24 horas. O valor mínimo é de 1 milissegundo. O valor máximo é de 48 horas. Para desativar a colocação em fila de consultas em lote, defina o valor como -1.
  • default_column_name_character_map: o âmbito e o processamento predefinidos de carateres nos nomes das colunas. Se não estiver definido, os trabalhos de carregamento que usam carateres não suportados nos nomes das colunas falham com uma mensagem de erro. Algumas tabelas mais antigas podem estar definidas para substituir carateres não suportados nos nomes das colunas. Para mais informações, consulte load_option_list.
  • default_interactive_query_queue_timeout_ms: a quantidade predefinida de tempo, em milissegundos, que uma consulta interativa é colocada em fila. Se não estiver definida, a predefinição é de seis horas. O valor mínimo é de 1 milissegundo. O valor máximo é de 48 horas. Para desativar o processamento em fila de consultas interativas, defina o valor como -1.

  • default_kms_key_name: a chave predefinida do Cloud Key Management Service para encriptar dados de tabelas, incluindo tabelas temporárias ou anónimas. Para mais informações, consulte o artigo Chaves do Cloud KMS geridas pelo cliente.

  • default_query_job_timeout_ms: o tempo predefinido após o qual uma tarefa de consulta excede o limite de tempo, incluindo o tempo em que a tarefa está na fila e o tempo gasto na execução. O período de limite de tempo tem de ser entre cinco minutos e seis horas. Este limite de tempo aplica-se apenas a tarefas de consulta individuais e às tarefas secundárias de scripts. Para definir um limite de tempo para tarefas de scripts, deve usar o método da API jobs.insert e definir o campo jobTimeoutMs.

  • default_query_optimizer_options: as otimizações de consultas baseadas no histórico. Esta opção pode ser uma das seguintes:

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

  • default_time_zone: o fuso horário predefinido a usar em funções SQL dependentes do fuso horário, quando não é especificado um fuso horário como argumento. Esta configuração não se aplica a tabelas particionadas por colunas de unidades de tempo (que usam o UTC como fuso horário), às transferências agendadas do Serviço de transferência de armazenamento ou ao carregamento de dados com a ferramenta de linha de comandos bq. Para mais informações, consulte o artigo sobre os fusos horários.

  • default_storage_billing_model: o modelo de faturação de armazenamento predefinido para novos conjuntos de dados. Defina o valor como PHYSICAL para usar bytes físicos ao calcular os custos de armazenamento ou como LOGICAL para usar bytes lógicos. Tenha em atenção que a alteração do modelo de faturação de armazenamento predefinido não afeta os conjuntos de dados existentes. Para mais informações, consulte o artigo Modelos de faturação de armazenamento.

  • default_max_time_travel_hours: o período de deslocamento no tempo predefinido em horas para novos conjuntos de dados. Esta duração tem de estar no intervalo de 48 a 168, inclusive, e tem de ser divisível por 24. A alteração do tempo máximo de viagem predefinido em horas não afeta os conjuntos de dados existentes. Para mais informações, consulte o artigo Viagem no tempo.

  • default_cloud_resource_connection_id: a associação predefinida a usar quando criar tabelas e modelos. Especifique apenas o ID ou o nome da ligação e exclua o ID do projeto anexado e os prefixos da região. A utilização de ligações predefinidas pode fazer com que as autorizações concedidas à conta de serviço da ligação sejam atualizadas, consoante o tipo de tabela ou modelo que está a criar. Para mais informações, consulte a vista geral da associação predefinida.

  • default_sql_dialect_option: O dialeto de consulta SQL predefinido para executar tarefas de consulta através da ferramenta de linhas de comando bq ou da API BigQuery. A alteração desta definição não afeta o dialeto predefinido na consola. Esta opção pode ser uma das seguintes:

    • 'default_legacy_sql' (predefinição): use SQL antigo se o dialeto de consulta não for especificado ao nível da tarefa.
    • 'default_google_sql': use o GoogleSQL se o dialeto de consulta não for especificado ao nível da tarefa.
    • 'only_google_sql': use o GoogleSQL se o dialeto de consulta não for especificado ao nível da tarefa. Rejeitar trabalhos com o dialeto de consulta definido como SQL antigo.
    • NULL: use a predefinição do dialeto de consulta, que é equivalente a 'default_legacy_sql'.

  • enable_reservation_based_fairness: a opção que determina como os espaços ociosos são partilhados. O valor predefinido é falso, o que significa que os espaços inativos são distribuídos igualmente por todos os projetos de consulta. Se estiver ativada, os espaços inativos são partilhados igualmente por todas as reservas primeiro e, em seguida, por todos os projetos na reserva. Para mais informações, consulte o artigo sobre a equidade baseada em reservas. Esta opção só é suportada ao nível do projeto. Não pode especificá-lo ao nível da organização ou do trabalho.

Especifique as definições de configuração

Esta secção descreve como especificar uma definição de configuração.

Autorizações necessárias

Para especificar uma definição de configuração, precisa da autorização de bigquery.config.update gestão de identidade e de acesso (IAM). A função de IAM predefinida roles/bigquery.admin inclui as autorizações necessárias para especificar uma definição de configuração.

Para mais informações sobre as funções e as autorizações do IAM no BigQuery, consulte o artigo Funções e autorizações predefinidas.

Configure as definições

Pode configurar as definições ao nível da organização ou do projeto através das seguintes declarações SQL. Quando especifica a configuração, tem de especificar a região onde se aplica. Só pode usar uma região para cada declaração.

Configure as definições da organização

Para configurar as definições da organização, use a ALTER ORGANIZATION SET OPTIONS declaração DDL. O exemplo seguinte define o fuso horário predefinido como America/Chicago, a chave do Cloud KMS predefinida como uma chave definida pelo utilizador, o limite de tempo da consulta predefinido como 30 minutos, o limite de tempo da fila de consultas interativas predefinido como 10 minutos e o limite de tempo da fila de consultas em lote predefinido como 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 o seguinte:

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

O exemplo seguinte limpa todas as predefinições ao 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);

Configure as definições do projeto

Para configurar as definições do projeto, use a ALTER PROJECT SET OPTIONS declaração DDL. A declaração DDL aceita opcionalmente a variável ALTER PROJECT SET OPTIONSPROJECT_ID. Se o PROJECT_ID não for especificado, a predefinição é o projeto atual onde a consulta é executada. O exemplo seguinte define o fuso horário predefinido como America/Los_Angeles, a chave do Cloud KMS predefinida como uma chave de exemplo, o limite de tempo da consulta predefinido como 1 hora, o limite de tempo da fila de consultas interativas predefinido como 10 minutos, o limite de tempo da fila de consultas em lote predefinido como 20 minutos e ativa a equidade baseada em reservas.

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,
  `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 o seguinte:

  • PROJECT_ID: o ID do projeto.
  • REGION: a região associada ao seu projeto ou organização. Por exemplo, us ou europe-west6.
  • KMS_KEY: uma chave do Cloud KMS definida pelo utilizador. Para mais informações sobre as chaves do Cloud KMS, consulte o artigo Chaves do Cloud KMS geridas pelo cliente.
  • CONNECTION_ID: o ID da associação a usar como associação predefinida para tabelas e modelos.

O exemplo seguinte limpa todas as predefinições ao nível do projeto. As predefinições usam quaisquer predefinições ao nível da organização, se existirem. Caso contrário, todas as predefinições são definidas como a predefiniçã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);

As configurações ao nível do projeto substituem as configurações ao nível da organização. As configurações ao nível do projeto podem, por sua vez, ser substituídas por configurações ao nível da sessão, que podem ser substituídas por configurações ao nível da tarefa.

Obtenha definições de configuração

Pode ver as definições de configuração de uma organização ou um projeto através das seguintes vistas do esquema de informações:

As novas configurações podem demorar alguns minutos a entrar em vigor e a serem refletidas na vista INFORMATION_SCHEMA.

Autorizações necessárias

Para obter as definições de configuração, precisa da bigquery.config.getautorização do IAM para o projeto especificado.

Cada uma das seguintes funções de IAM predefinidas inclui as autorizações de que precisa para obter a configuração da visualização INFORMATION_SCHEMA:

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

Para mais informações sobre as funções e as autorizações do IAM no BigQuery, consulte o artigo Funções e autorizações predefinidas.

Exemplos

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

SELECT * FROM region-us.INFORMATION_SCHEMA.ORGANIZATION_OPTIONS;

Para ver as configurações eficazes no seu projeto predefinido na usregião, execute a seguinte consulta:

SELECT * FROM region-us.INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS;

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

SELECT * FROM region-us.INFORMATION_SCHEMA.PROJECT_OPTIONS;

Preços

Não existe nenhum custo adicional para usar o serviço de configuração do BigQuery. Para mais informações, consulte os preços.