Como programar consultas

Nesta página, você aprende a programar consultas recorrentes no BigQuery.

É possível programar consultas para que sejam executadas de maneira recorrente. As consultas programadas precisam ser escritas em GoogleSQL, que pode incluir instruções em linguagem de definição de dados (DDL) e linguagem de manipulação de dados (DML). É possível organizar os resultados da consulta por data e hora parametrizando a string de consulta e a tabela de destino.

Ao criar ou atualizar a programação de uma consulta, o horário programado para a consulta é convertido do seu horário local para UTC. O UTC não é afetado pelo horário de verão.

Antes de começar

Permissões necessárias

Para programar uma consulta, você precisa destas permissões do IAM:

  • Para criar a transferência, você precisa ter as permissões bigquery.transfers.update e bigquery.datasets.get ou bigquery.jobs.create, bigquery.transfers.get e bigquery.datasets.get.

  • Para executar uma consulta programada, você precisa ter:

    • Permissões bigquery.datasets.get no conjunto de dados de destino
    • bigquery.jobs.create

Para modificar ou excluir uma consulta programada, você precisa de uma das seguintes permissões do IAM:

  • bigquery.transfers.update
  • bigquery.jobs.create e propriedade sobre a consulta programada

O papel predefinido roles/bigquery.admin do IAM inclui as permissões necessárias para programar ou modificar uma consulta.

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

Para criar ou atualizar consultas programadas executadas por uma conta de serviço, você precisa ter acesso a essa conta de serviço. Para mais informações sobre como conceder o papel da conta de serviço aos usuários, consulte Papel do usuário da conta de serviço. Para selecionar uma conta de serviço na interface de consulta programada do console do Google Cloud, você precisa das seguintes permissões do IAM:

  • iam.serviceAccounts.list

Opções de configuração

String de consulta

A string de consulta precisa ser válida e escrita em GoogleSQL. Cada execução de uma consulta programada pode receber os parâmetros de consulta a seguir.

Para testar uma string de consulta manualmente com os parâmetros @run_time e @run_date antes de programar uma consulta, use a ferramenta de linha de comando bq.

Parâmetros disponíveis

Parâmetro Tipo do GoogleSQL Valor
@run_time TIMESTAMP Representado no horário UTC. Para consultas programadas regularmente, run_time representa o ambiente de execução pretendido. Por exemplo, se a consulta programada for definida como "a cada 24 horas", a diferença de run_time entre duas consultas consecutivas será exatamente 24 horas, mesmo que o ambiente de execução real seja ligeiramente diferente.
@run_date DATE Representa uma data do calendário lógico.

Exemplo

Neste exemplo, o parâmetro @run_time faz parte da string de consulta, em que é consultado um conjunto de dados público chamado hacker_news.stories.

SELECT @run_time AS time,
  title,
  author,
  text
FROM `bigquery-public-data.hacker_news.stories`
LIMIT
  1000

Tabela de destino

Se a tabela de destino dos resultados não existir quando você configurar a consulta programada, o BigQuery tentará criar a tabela para você.

Se você estiver usando uma consulta em DDL ou DML, no console do Google Cloud, escolha a região ou o Local de processamento. Essa informação é necessária nas consultas em DDL ou DML que criam a tabela de destino.

Se a tabela de destino existir e você estiver usando a preferência de gravação WRITE_APPEND, o BigQuery anexa dados à tabela de destino e tenta mapear o esquema. O BigQuery permite automaticamente adições e reordenações de campos, além de acomodar campos opcionais ausentes. Se o esquema da tabela mudar tanto entre as execuções que o BigQuery não conseguir processar as alterações automaticamente, a consulta programada falhará.

É possível que as colunas se refiram a tabelas de projetos e conjuntos de dados diferentes. Ao configurar a consulta programada, você não precisa incluir o conjunto de dados de destino no nome da tabela. Esse conjunto será especificado separadamente.

O conjunto de dados e a tabela de destino de uma consulta programada precisam estar no mesmo projeto que a consulta programada.

Preferência de gravação

A preferência de gravação selecionada determina como os resultados da consulta são gravados em uma tabela de destino atual.

  • WRITE_TRUNCATE: caso haja uma tabela, os respectivos dados serão substituídos no BigQuery.
  • WRITE_APPEND: caso haja uma tabela, os dados serão anexados a ela no BigQuery.

Caso esteja usando uma consulta em DDL ou DML, não é possível usar a opção de preferência de gravação.

A criação, substituição ou anexação de uma tabela de destino só ocorre se a consulta for concluída no BigQuery. Essas ações ocorrem como uma atualização atômica na conclusão do job.

Cluster

As consultas programadas podem criar clustering somente em novas tabelas. Isso acontece quando as tabelas incluem uma instrução CREATE TABLE AS SELECT em DDL. Consulte Como criar uma tabela em clusters usando o resultado de uma consulta na página Como usar instruções de linguagem de definição de dados.

Opções de particionamento

Nas consultas programadas, pode ocorrer a criação de tabelas de destino particionadas ou não particionadas. O particionamento está disponível no console do Google Cloud, na ferramenta de linha de comando bq e nos métodos de configuração da API. Se você estiver usando uma consulta em DDL ou DML com particionamento, deixe o Campo de particionamento da tabela de destino em branco.

É possível usar os seguintes tipos de particionamento de tabelas no BigQuery:

Para criar uma tabela particionada usando uma consulta programada no console do Google Cloud, use as seguintes opções:

  • Para usar o particionamento por intervalo de números inteiros, deixe o campo Particionamento da tabela de destino em branco.

  • Para usar o particionamento de coluna de unidade de tempo, especifique o nome da coluna no campo Particionamento da tabela de destino ao configurar uma consulta programada.

  • Para usar o particionamento por tempo de ingestão, deixe o Campo de particionamento da tabela de destino em branco e indique o particionamento de data no nome da tabela de destino. Por exemplo, mytable${run_date}. Para mais informações, consulte Sintaxe de modelos de parâmetros.

Parâmetros disponíveis

Ao configurar a consulta programada, é possível especificar o modo de particionamento da tabela de destino com parâmetros de tempo de execução.

Parâmetro Tipo de modelo Valor
run_time Carimbo de data/hora formatado Na hora UTC, de acordo com a programação. Para consultas programadas regularmente, run_time representa o ambiente de execução pretendido. Por exemplo, se a consulta programada for definida como "a cada 24 horas", a diferença run_time entre duas consultas consecutivas será exatamente 24 horas, mesmo que o ambiente de execução real seja ligeiramente diferente.

Consulte TransferRun.runTime.
run_date String de data A data do parâmetro run_time no formato a seguir: %Y-%m-%d; por exemplo, 2018-01-01. Esse formato é compatível com tabelas particionadas por tempo de ingestão.

Sistema de modelo

As consultas programadas são compatíveis com parâmetros de tempo de execução no nome da tabela de destino com uma sintaxe de modelos.

Sintaxe de modelos de parâmetros

A sintaxe de modelos é compatível com modelos básicos de strings e ajuste de horário. A referência aos parâmetros é feita nos seguintes formatos:

  • {run_date}
  • {run_time[+\-offset]|"time_format"}
Parâmetro Objetivo
run_date Este parâmetro é substituído pela data no formato YYYYMMDD.
run_time O parâmetro é compatível com as propriedades a seguir:


offset
Ajuste de horário expresso em horas (h), minutos (m) e segundos (s), nesta ordem.
Não é compatível com dias (d).
Casas decimais são permitidas, por exemplo: 1.5h.

time_format
Uma string de formatação. Os parâmetros de formatação mais comuns são anos (%Y), meses (%m) e dias (%d).
Para tabelas particionadas, YYYYMMDD é o sufixo necessário, equivalente a "%Y%m%d".

Leia mais sobre a formatação de elementos datetime.

Observações sobre o uso:
  • Nenhum espaço em branco é permitido entre run_time, offset e time_format.
  • Para incluir as chaves literais na string, insira caracteres de escape como '\{' and '\}'.
  • Para incluir aspas literais ou uma barra vertical em "time_format", como "YYYY|MM|DD", insira-os como caracteres de escape na string de formatação como '\"' ou '\|'.

Exemplos de modelos de parâmetros

Nestes exemplos, são demonstrados a especificação de nomes de tabelas de destino com formatos de tempo diferentes e o ajuste do ambiente de execução.
run_time (UTC) Parâmetro modelado Nome da tabela de destino da saída
2018-02-15 00:00:00 mytable mytable
2018-02-15 00:00:00 mytable_{run_time|"%Y%m%d"} mytable_20180215
2018-02-15 00:00:00 mytable_{run_time+25h|"%Y%m%d"} mytable_20180216
2018-02-15 00:00:00 mytable_{run_time-1h|"%Y%m%d"} mytable_20180214
2018-02-15 00:00:00 mytable_{run_time+1.5h|"%Y%m%d%H"}
ou
mytable_{run_time+90m|"%Y%m%d%H"}		 mytable_2018021501
2018-02-15 00:00:00 {run_time+97s|"%Y%m%d"}_mytable_{run_time+97s|"%H%M%S"} 20180215_mytable_000137

Usar uma conta de serviço

É possível configurar uma consulta programada para usar uma conta de serviço como autenticação. Uma conta de serviço é uma Conta do Google associada ao seu projeto do Google Cloud. A conta de serviço pode executar jobs, como consultas programadas ou pipelines de processamento em lote, com as próprias credenciais de serviço em vez das credenciais de um usuário final.

Para saber mais sobre usar contas de serviço como método de autenticação, consulte Introdução à autenticação.

Especificar a chave de criptografia com consultas programadas

É possível especificar chaves de criptografia gerenciadas pelo cliente (CMEKs, na sigla em inglês) para criptografar dados de uma execução de transferência. É possível usar uma CMEK para dar suporte a transferências de consultas programadas.

Quando você especifica uma CMEK com uma transferência, o serviço de transferência de dados do BigQuery aplica a CMEK a qualquer cache intermediário no disco de dados ingeridos para que todo o fluxo de trabalho de transferência de dados fique em conformidade com a CMEK.

Não é possível atualizar uma transferência atual para adicionar uma CMEK se a transferência não tiver sido criada originalmente com uma CMEK. Por exemplo, não é possível alterar uma tabela de destino que, originalmente, estava criptografada por padrão, para ser criptografada com CMEKs. Por outro lado, também não é possível alterar uma tabela de destino criptografada por CMEK para ter um tipo diferente de criptografia.

É possível atualizar uma CMEK para uma transferência se a configuração de transferência tiver sido criada originalmente com uma criptografia CMEK. Quando você atualiza uma CMEK para uma configuração de transferência, o serviço de transferência de dados do BigQuery propaga a CMEK para as tabelas de destino na próxima execução da transferência, em que o serviço de transferência de dados do BigQuery substitui todas as CMEKs desatualizadas pela nova CMEK durante a execução da transferência. Para saber mais, consulte Atualizar uma transferência.

Também é possível usar as chaves padrão do projeto. Quando você especifica uma chave padrão do projeto com uma transferência, o serviço de transferência de dados do BigQuery a usa como padrão para qualquer nova configuração de transferência.

Configurar consultas programadas

Para ver uma descrição da sintaxe, consulte Como formatar a programação. Veja mais detalhes sobre a sintaxe de programação em Recurso: TransferConfig.

Console

  1. Abra a página do BigQuery no console do Google Cloud.

    Ir para o BigQuery

  2. Execute a consulta do seu interesse. Quando estiver satisfeito com os resultados, clique em Programar consulta.

    Criar uma nova consulta programada no console do Google Cloud.

  3. As opções de consulta programada são exibidas no painel Nova consulta programada.

    Novo painel de consulta programada.

  4. No painel Nova consulta programada:

    • Em Nome da consulta programada, insira um nome, como My scheduled query. Esse nome pode ser qualquer valor que possa ser identificado mais tarde, caso precise modificar a consulta.

    • Opcional: por padrão, a consulta está programada para ser executada Diariamente. É possível alterar a programação padrão selecionando uma opção no menu suspenso Repete:

      • Para especificar uma frequência personalizada, selecione Personalizado e, em seguida, insira uma especificação de horário do tipo cron no campo Programação personalizada. Por exemplo, every mon 23:30 ou every 6 hours: Para detalhes sobre programações válidas, incluindo intervalos personalizados, consulte o campo schedule em Recurso: TransferConfig.

        Formatar uma consulta programada personalizada.

      • Para mudar o horário de início, selecione a opção Iniciar no horário definido e insira a data e hora de início desejadas.

      • Para especificar um horário de término, selecione a opção Programar horário de término e insira a data e a hora de término desejadas.

      • Para salvar a consulta sem programação para executar sob demanda posteriormente, selecione Sob demanda no menu Repetições.

  5. Para uma consulta SELECT do GoogleSQL, selecione a opção Definir uma tabela de destino para os resultados da consulta e forneça as seguintes informações sobre o conjunto de dados de destino.

    • Em Nome do conjunto de dados, escolha o conjunto de dados de destino apropriado.
    • Em Nome da tabela, insira o nome da tabela de destino.

    • Em Preferência de gravação na tabela de destino, escolha Adicionar ao final da tabela para adicionar ao final da tabela ou Substituir tabela para substituir a tabela de destino.

      Novo destino de consulta programada

  6. Escolha o Tipo de local.

    • Se você tiver ativado a tabela de destino para os resultados da consulta, selecione Seleção automática de local para selecionar automaticamente o local em que a tabela de destino está.

    • Caso contrário, escolha o local onde os dados consultados estão localizados.

  7. Opções avançadas:

    • Opcional: CMEK se você usar chaves de criptografia gerenciadas pelo cliente, selecione Chave gerenciada pelo cliente em Opções avançadas. Uma lista das CMEKs disponíveis será exibida. Para informações sobre como as chaves de criptografia gerenciadas pelo cliente (CMEK) funcionam com o serviço de transferência de dados do BigQuery, consulte Especificar chave de criptografia com consultas programadas.

    • Autenticar com conta de serviço. Se você tem uma ou mais contas de serviço associadas ao projeto do Google Cloud, é possível associar uma conta de serviço à consulta programada em vez de usar as credenciais de usuário. Em Credencial de consulta programada, clique no menu para ver uma lista de contas de serviço disponíveis. Uma conta de serviço é necessária se você fez login como uma identidade federada.

      Opções avançadas de consulta programada.

  8. Outras configurações:

    • Opcional: marque Enviar notificações por e-mail para permitir notificações sobre falhas na execução da transferências.

    • Opcional: em Tópico do Pub/Sub, insira o nome do tópico do Pub/Sub. Por exemplo: projects/myproject/topics/mytopic.

      Nova consulta DDL e DML programada.

  9. Clique em Salvar.

bq

Opção 1: use o comando bq query.

Para criar uma consulta programada, adicione as opções destination_table (ou target_dataset), --schedule e --display_name ao comando bq query.

bq query \
--display_name=name \
--destination_table=table \
--schedule=interval

Substitua:

  • name. O nome de exibição da consulta programada. Ele pode ser qualquer valor que você possa identificar posteriormente, se precisar modificar a consulta.
  • table. A tabela de destino dos resultados da consulta.
    • --target_dataset é uma maneira alternativa de nomear o conjunto de dados de destino para os resultados da consulta, quando usado com consultas DDL e DML.
    • Use --destination_table ou --target_dataset, mas não ambos.
  • interval. Quando usado com bq query, transforma a consulta em uma consulta programada recorrente. É necessário definir uma frequência de execução da consulta. Para detalhes sobre programações válidas, incluindo intervalos personalizados, consulte o campo schedule em Recurso: TransferConfig. Exemplos:
    • --schedule='every 24 hours'
    • --schedule='every 3 hours'
    • --schedule='every monday 09:00'
    • --schedule='1st sunday of sep,oct,nov 00:00'

Sinalizações opcionais:

  • --project_id é a ID do projeto. Se --project_id não for especificado, o projeto padrão será usado.

  • --replace trunca a tabela de destino e grava novos resultados a cada execução da consulta programada.

  • --append_table anexa os resultados à tabela de destino.

  • Nas consultas em DDL e DML, também é possível usar a sinalização --location para especificar uma determinada região de processamento. Se --location não for especificado, será usado o local global do Google Cloud.

Por exemplo, o comando a seguir usa a consulta simples SELECT 1 from mydataset.test para criar uma consulta programada chamada My Scheduled Query. A tabela de destino é mytable, no conjunto de dados mydataset. A consulta programada é criada no projeto padrão:

    bq query \
    --use_legacy_sql=false \
    --destination_table=mydataset.mytable \
    --display_name='My Scheduled Query' \
    --schedule='every 24 hours' \
    --replace=true \
    'SELECT
      1
    FROM
      mydataset.test'


Opção 2: use o comando bq mk.

As consultas programadas são um tipo de transferência. Para programar uma consulta, use a ferramenta de linha de comando bq para fazer uma configuração de transferência.

As consultas precisam estar em SQL padrão para serem programadas.

Digite o comando bq mk e forneça as seguintes sinalizações obrigatórias:

  • --transfer_config
  • --data_source
  • --target_dataset (opcional para consultas DDL e DML)
  • --display_name
  • --params

Sinalizações opcionais:

  • --project_id é a ID do projeto. Se --project_id não for especificado, o projeto padrão será usado.

  • --schedule é a frequência de execução da consulta. Se --schedule não for especificado, o padrão será "a cada 24 horas" com base no horário de criação.

  • Nas consultas em DDL e DML, também é possível usar a sinalização --location para especificar uma determinada região de processamento. Se --location não for especificado, será usado o local global do Google Cloud.

  • --service_account_name serve para autenticar a consulta programada com uma conta de serviço em vez da conta de usuário individual.

  • --destination_kms_key especifica o ID de recurso da chave para a chave se você usar uma chave de criptografia gerenciada pelo cliente (CMEK, na sigla em inglês) para essa transferência. Para informações sobre como as CMEKs funcionam com o serviço de transferência de dados do BigQuery, consulte Especificar chave de criptografia com consultas programadas.

bq mk \
--transfer_config \
--target_dataset=dataset \
--display_name=name \
--params='parameters' \
--data_source=data_source

Substitua:

  • dataset. O conjunto de dados de destino na configuração da transferência.
    • Esse parâmetro é opcional nas consultas DDL e DML, mas necessário em todas as outras.
  • name. O nome de exibição da configuração de transferência. Ele pode ser qualquer valor que você possa identificar posteriormente, se precisar modificar a consulta.
  • parameters. Contém os parâmetros da configuração de transferência criada no formato JSON. Por exemplo, --params='{"param":"param_value"}'.
    • Para uma consulta programada, você precisa fornecer o parâmetro query:
    • O parâmetro destination_table_name_template é o nome da tabela de destino.
      • Esse parâmetro é opcional nas consultas DDL e DML, mas necessário em todas as outras.
    • Para o parâmetro write_disposition, é possível escolher WRITE_TRUNCATE para substituir a tabela de destino ou WRITE_APPEND para anexar os resultados da consulta a ela.
      • Esse parâmetro é opcional nas consultas DDL e DML, mas necessário em todas as outras.
  • data_source. É a fonte de dados: scheduled_query.
  • Opcional: a sinalização --service_account_name serve para autenticar usando uma conta de serviço em vez de uma conta de usuário individual.
  • Opcional: o --destination_kms_key especifica o ID de recurso da chave para a chave do Cloud KMS, por exemplo, projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name.

Por exemplo, o comando a seguir usa a consulta simples SELECT 1 from mydataset.test para criar uma configuração de transferência de consulta programada chamada My Scheduled Query. A tabela de destino mytable é substituída em todas as gravações, e o conjunto de dados de destino é mydataset. A consulta programada é criada no projeto padrão e autenticada como conta de serviço:

bq mk \
--transfer_config \
--target_dataset=mydataset \
--display_name='My Scheduled Query' \
--params='{"query":"SELECT 1 from mydataset.test","destination_table_name_template":"mytable","write_disposition":"WRITE_TRUNCATE"}' \
--data_source=scheduled_query \
--service_account_name=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com

Ao executar o comando pela primeira vez, você recebe uma mensagem como esta:

[URL omitted] Please copy and paste the above URL into your web browser and follow the instructions to retrieve an authentication code.

Siga as instruções na mensagem e cole o código de autenticação na linha de comando.

API

Use o método projects.locations.transferConfigs.create e forneça uma instância do recurso TransferConfig.

Java

Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create a scheduled query
public class CreateScheduledQuery {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    final String datasetId = "MY_DATASET_ID";
    final String query =
        "SELECT CURRENT_TIMESTAMP() as current_time, @run_time as intended_run_time, "
            + "@run_date as intended_run_date, 17 as some_integer";
    Map<String, Value> params = new HashMap<>();
    params.put("query", Value.newBuilder().setStringValue(query).build());
    params.put(
        "destination_table_name_template",
        Value.newBuilder().setStringValue("my_destination_table_{run_date}").build());
    params.put("write_disposition", Value.newBuilder().setStringValue("WRITE_TRUNCATE").build());
    params.put("partitioning_field", Value.newBuilder().build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Scheduled Query Name")
            .setDataSourceId("scheduled_query")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createScheduledQuery(projectId, transferConfig);
  }

  public static void createScheduledQuery(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = dataTransferServiceClient.createTransferConfig(request);
      System.out.println("\nScheduled query created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("\nScheduled query was not created." + ex.toString());
    }
  }
}

Python

Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

# The project where the query job runs is the same as the project
# containing the destination dataset.
project_id = "your-project-id"
dataset_id = "your_dataset_id"

# This service account will be used to execute the scheduled queries. Omit
# this request parameter to run the query as the user with the credentials
# associated with this client.
service_account_name = "abcdef-test-sa@abcdef-test.iam.gserviceaccount.com"

# Use standard SQL syntax for the query.
query_string = """
SELECT
  CURRENT_TIMESTAMP() as current_time,
  @run_time as intended_run_time,
  @run_date as intended_run_date,
  17 as some_integer
"""

parent = transfer_client.common_project_path(project_id)

transfer_config = bigquery_datatransfer.TransferConfig(
    destination_dataset_id=dataset_id,
    display_name="Your Scheduled Query Name",
    data_source_id="scheduled_query",
    params={
        "query": query_string,
        "destination_table_name_template": "your_table_{run_date}",
        "write_disposition": "WRITE_TRUNCATE",
        "partitioning_field": "",
    },
    schedule="every 24 hours",
)

transfer_config = transfer_client.create_transfer_config(
    bigquery_datatransfer.CreateTransferConfigRequest(
        parent=parent,
        transfer_config=transfer_config,
        service_account_name=service_account_name,
    )
)

print("Created scheduled query '{}'".format(transfer_config.name))

Configurar consultas programadas com uma conta de serviço

Java

Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create a scheduled query with service account
public class CreateScheduledQueryWithServiceAccount {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    final String datasetId = "MY_DATASET_ID";
    final String serviceAccount = "MY_SERVICE_ACCOUNT";
    final String query =
        "SELECT CURRENT_TIMESTAMP() as current_time, @run_time as intended_run_time, "
            + "@run_date as intended_run_date, 17 as some_integer";
    Map<String, Value> params = new HashMap<>();
    params.put("query", Value.newBuilder().setStringValue(query).build());
    params.put(
        "destination_table_name_template",
        Value.newBuilder().setStringValue("my_destination_table_{run_date}").build());
    params.put("write_disposition", Value.newBuilder().setStringValue("WRITE_TRUNCATE").build());
    params.put("partitioning_field", Value.newBuilder().build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Scheduled Query Name")
            .setDataSourceId("scheduled_query")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createScheduledQueryWithServiceAccount(projectId, transferConfig, serviceAccount);
  }

  public static void createScheduledQueryWithServiceAccount(
      String projectId, TransferConfig transferConfig, String serviceAccount) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .setServiceAccountName(serviceAccount)
              .build();
      TransferConfig config = dataTransferServiceClient.createTransferConfig(request);
      System.out.println(
          "\nScheduled query with service account created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("\nScheduled query with service account was not created." + ex.toString());
    }
  }
}

Python

Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

# The project where the query job runs is the same as the project
# containing the destination dataset.
project_id = "your-project-id"
dataset_id = "your_dataset_id"

# This service account will be used to execute the scheduled queries. Omit
# this request parameter to run the query as the user with the credentials
# associated with this client.
service_account_name = "abcdef-test-sa@abcdef-test.iam.gserviceaccount.com"

# Use standard SQL syntax for the query.
query_string = """
SELECT
  CURRENT_TIMESTAMP() as current_time,
  @run_time as intended_run_time,
  @run_date as intended_run_date,
  17 as some_integer
"""

parent = transfer_client.common_project_path(project_id)

transfer_config = bigquery_datatransfer.TransferConfig(
    destination_dataset_id=dataset_id,
    display_name="Your Scheduled Query Name",
    data_source_id="scheduled_query",
    params={
        "query": query_string,
        "destination_table_name_template": "your_table_{run_date}",
        "write_disposition": "WRITE_TRUNCATE",
        "partitioning_field": "",
    },
    schedule="every 24 hours",
)

transfer_config = transfer_client.create_transfer_config(
    bigquery_datatransfer.CreateTransferConfigRequest(
        parent=parent,
        transfer_config=transfer_config,
        service_account_name=service_account_name,
    )
)

print("Created scheduled query '{}'".format(transfer_config.name))

Visualizar o status da consulta programada

Console

Para visualizar o status de suas consultas programadas, clique em Consultas programadas no painel de navegação. Atualize a página para ver o status atualizado de suas consultas programadas. Clique em uma consulta programada para saber mais sobre ela.

Listar consultas programadas.

bq

As consultas programadas são um tipo de transferência. Para mostrar os detalhes de uma consulta programada, use a ferramenta de linha de comando bq para listar as configurações de transferência.

Insira o comando bq ls e forneça a sinalização de execução da transferência --transfer_config. As sinalizações abaixo também são obrigatórias:

  • --transfer_location

Por exemplo:

bq ls \
--transfer_config \
--transfer_location=us

Para exibir os detalhes de apenas uma consulta programada, use o comando bq show e forneça o valor de transfer_path da consulta programada/configuração de transferência.

Por exemplo:

bq show \
--transfer_config \
projects/862514376110/locations/us/transferConfigs/5dd12f26-0000-262f-bc38-089e0820fe38

API

Use o método projects.locations.transferConfigs.list e forneça uma instância do recurso TransferConfig.

Java

Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ListTransferConfigsRequest;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import java.io.IOException;

// Sample to get list of transfer config
public class ListTransferConfigs {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    listTransferConfigs(projectId);
  }

  public static void listTransferConfigs(String projectId) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      ListTransferConfigsRequest request =
          ListTransferConfigsRequest.newBuilder().setParent(parent.toString()).build();
      dataTransferServiceClient
          .listTransferConfigs(request)
          .iterateAll()
          .forEach(config -> System.out.print("Success! Config ID :" + config.getName() + "\n"));
    } catch (ApiException ex) {
      System.out.println("Config list not found due to error." + ex.toString());
    }
  }
}

Python

Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

project_id = "my-project"
parent = transfer_client.common_project_path(project_id)

configs = transfer_client.list_transfer_configs(parent=parent)
print("Got the following configs:")
for config in configs:
    print(f"\tID: {config.name}, Schedule: {config.schedule}")

Atualizar consultas programadas

Console

Para atualizar uma consulta programada, siga estas etapas:

  1. No painel de navegação, clique em Consultas programadas.
  2. Na lista de consultas programadas, clique no nome da consulta que você quer alterar.
  3. Na página Detalhes da consulta programada que é aberta, clique em Editar. Edite os detalhes da consulta programada.
  4. Opcional: altere o texto da consulta no painel de edição da consulta.
  5. Clique em Programar consulta e selecione Atualizar consulta programada.
  6. Opcional: altere outras opções de programação da consulta.
  7. Clique em Atualizar.

bq

As consultas programadas são um tipo de transferência. Para atualizar a consulta programada, use a ferramenta de linha de comando bq para fazer uma configuração de transferência.

Insira o comando bq update com a sinalização --transfer_config necessária.

Sinalizações opcionais:

  • --project_id é a ID do projeto. Se --project_id não for especificado, o projeto padrão será usado.

  • --schedule é a frequência de execução da consulta. Se --schedule não for especificado, o padrão será "a cada 24 horas" com base no horário de criação.

  • --service_account_name só entrará em vigor se --update_credentials também estiver definido. Para mais informações, consulte Atualizar credenciais de consultas programadas.

  • --target_dataset (opcional para consultas DDL e DML) é uma maneira alternativa de nomear o conjunto de dados de destino para os resultados da consulta, quando usado com consultas DDL e DML.

  • --display_name é o nome da consulta programada.

  • --params é o parâmetro da configuração de transferência criada no formato JSON. Por exemplo: --params='{"param":"param_value"}'.

  • --destination_kms_key especifica o ID de recurso da chave para a chave do Cloud KMS se você usar uma chave de criptografia gerenciada pelo cliente (CMEK, na sigla em inglês) para essa transferência. Para informações sobre como as chaves de criptografia gerenciadas pelo cliente (CMEK) funcionam com o serviço de transferência de dados do BigQuery, consulte Especificar chave de criptografia com consultas programadas.

bq update \
--target_dataset=dataset \
--display_name=name \
--params='parameters'
--transfer_config \
RESOURCE_NAME

Substitua:

  • dataset. O conjunto de dados de destino na configuração da transferência. Esse parâmetro é opcional nas consultas DDL e DML, mas necessário em todas as outras.
  • name. O nome de exibição da configuração de transferência. Ele pode ser qualquer valor que você possa identificar posteriormente, se precisar modificar a consulta.
  • parameters. Contém os parâmetros da configuração de transferência criada no formato JSON. Por exemplo, --params='{"param":"param_value"}'.
    • Para uma consulta programada, você precisa fornecer o parâmetro query:
    • O parâmetro destination_table_name_template é o nome da tabela de destino. Esse parâmetro é opcional nas consultas DDL e DML, mas necessário em todas as outras.
    • Para o parâmetro write_disposition, é possível escolher WRITE_TRUNCATE para substituir a tabela de destino ou WRITE_APPEND para anexar os resultados da consulta a ela. Esse parâmetro é opcional nas consultas DDL e DML, mas necessário em todas as outras.
  • Opcional: o --destination_kms_key especifica o ID de recurso da chave para a chave do Cloud KMS, por exemplo, projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name.
  • RESOURCE_NAME: o nome do recurso da transferência, também conhecido como configuração da transferência. Se você não souber o nome do recurso da transferência, encontre-o com: bq ls --transfer_config --transfer_location=location.

Por exemplo, o comando a seguir usa a consulta simples SELECT 1 from mydataset.test para atualizar uma configuração de transferência de consulta programada chamada My Scheduled Query. A tabela de destino mytable é substituída em todas as gravações, e o conjunto de dados de destino é mydataset:

bq update \
--target_dataset=mydataset \
--display_name='My Scheduled Query' \
--params='{"query":"SELECT 1 from mydataset.test","destination_table_name_template":"mytable","write_disposition":"WRITE_TRUNCATE"}'
--transfer_config \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

API

Use o método projects.transferConfigs.patch e forneça o nome do recurso da transferência por meio do parâmetro transferConfig.name. Se você não souber o nome do recurso da transferência, use o comando bq ls --transfer_config --transfer_location=location para listar todas as transferências ou chame o método projects.locations.transferConfigs.list e forneça o ID do projeto por meio do parâmetro parent.

Java

Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.cloud.bigquery.datatransfer.v1.UpdateTransferConfigRequest;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

// Sample to update transfer config.
public class UpdateTransferConfig {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setName(configId)
            .setDisplayName("UPDATED_DISPLAY_NAME")
            .build();
    FieldMask updateMask = FieldMaskUtil.fromString("display_name");
    updateTransferConfig(transferConfig, updateMask);
  }

  public static void updateTransferConfig(TransferConfig transferConfig, FieldMask updateMask)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      UpdateTransferConfigRequest request =
          UpdateTransferConfigRequest.newBuilder()
              .setTransferConfig(transferConfig)
              .setUpdateMask(updateMask)
              .build();
      TransferConfig updateConfig = dataTransferServiceClient.updateTransferConfig(request);
      System.out.println("Transfer config updated successfully :" + updateConfig.getDisplayName());
    } catch (ApiException ex) {
      System.out.print("Transfer config was not updated." + ex.toString());
    }
  }
}

Python

Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

from google.cloud import bigquery_datatransfer
from google.protobuf import field_mask_pb2

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"
new_display_name = "My Transfer Config"

transfer_config = bigquery_datatransfer.TransferConfig(name=transfer_config_name)
transfer_config.display_name = new_display_name

transfer_config = transfer_client.update_transfer_config(
    {
        "transfer_config": transfer_config,
        "update_mask": field_mask_pb2.FieldMask(paths=["display_name"]),
    }
)

print(f"Updated config: '{transfer_config.name}'")
print(f"New display name: '{transfer_config.display_name}'")

Atualizar consultas programadas com restrições de propriedade

Se você tentar atualizar uma consulta programada que não é sua, a atualização poderá falhar com a seguinte mensagem de erro:

Cannot modify restricted parameters without taking ownership of the transfer configuration.

O proprietário da consulta programada é o usuário associado à consulta programada ou o usuário que tem acesso à conta de serviço associada à consulta programada. O usuário associado pode ser visto nos detalhes de configuração da consulta programada. Para informações sobre como atualizar a consulta programada para ter propriedade, consulte Atualizar credenciais de consulta programada. Para conceder aos usuários acesso a uma conta de serviço, você precisa ter o papel de usuário da conta de serviço.

Qualquer usuário que não seja o proprietário da consulta programada, mas tenha acesso a todos os recursos mencionados pela consulta, ainda poderá ter permissão para atualizá-la. Esse cenário só será aceito se a consulta puder ser validada em um ou dois minutos. Caso contrário, você vai receber a mesma mensagem de erro mencionada anteriormente. Se a consulta for muito complexa, será possível atualizar as credenciais da consulta programada para assumir a propriedade direta dela ou usar uma conta de serviço.

Atualizar as credenciais de consultas programadas

Se você estiver programando uma consulta existente, talvez precise atualizar as credenciais do usuário na consulta. As credenciais são atualizadas automaticamente para novas consultas programadas.

Algumas outras situações que podem exigir atualização de credenciais incluem:

  • Você quer consultar os dados do drive em uma consulta programada.

  • Você recebe um erro INVALID_USER ao tentar programar a consulta:

    Error code 5 : Authentication failure: User Id not found. Error code: INVALID_USERID

  • Você recebe o seguinte erro de parâmetros restritos ao tentar atualizar a consulta:

    Cannot modify restricted parameters without taking ownership of the transfer configuration.

Console

Para atualizar as credenciais atuais de uma consulta programada:

  1. Encontre e visualize o status de uma consulta programada.

  2. Clique no botão MAIS e selecione Atualizar credenciais.

    Atualizar as credenciais de consultas programadas.

  3. Aguarde de 10 a 20 minutos para que a alteração entre em vigor. Pode ser necessário limpar o cache do navegador.

bq

As consultas programadas são um tipo de transferência. Para atualizar as credenciais de uma consulta programada, use a ferramenta de linha de comando bq para atualizar a configuração de transferência.

Insira o comando bq update e forneça a sinalização de execução da transferência --transfer_config. As sinalizações abaixo também são obrigatórias:

  • --update_credentials

Sinalização opcional:

  • --service_account_name serve para autenticar a consulta programada com uma conta de serviço em vez da conta de usuário individual.

Por exemplo, o comando a seguir atualiza uma configuração de transferência de consulta programada para autenticar como conta de serviço:

bq update \
--update_credentials \
--service_account_name=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com
--transfer_config \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

Java

Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.cloud.bigquery.datatransfer.v1.UpdateTransferConfigRequest;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

// Sample to update credentials in transfer config.
public class UpdateCredentials {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    String serviceAccount = "MY_SERVICE_ACCOUNT";
    TransferConfig transferConfig = TransferConfig.newBuilder().setName(configId).build();
    FieldMask updateMask = FieldMaskUtil.fromString("service_account_name");
    updateCredentials(transferConfig, serviceAccount, updateMask);
  }

  public static void updateCredentials(
      TransferConfig transferConfig, String serviceAccount, FieldMask updateMask)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      UpdateTransferConfigRequest request =
          UpdateTransferConfigRequest.newBuilder()
              .setTransferConfig(transferConfig)
              .setUpdateMask(updateMask)
              .setServiceAccountName(serviceAccount)
              .build();
      dataTransferServiceClient.updateTransferConfig(request);
      System.out.println("Credentials updated successfully");
    } catch (ApiException ex) {
      System.out.print("Credentials was not updated." + ex.toString());
    }
  }
}

Python

Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

from google.cloud import bigquery_datatransfer
from google.protobuf import field_mask_pb2

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

service_account_name = "abcdef-test-sa@abcdef-test.iam.gserviceaccount.com"
transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"

transfer_config = bigquery_datatransfer.TransferConfig(name=transfer_config_name)

transfer_config = transfer_client.update_transfer_config(
    {
        "transfer_config": transfer_config,
        "update_mask": field_mask_pb2.FieldMask(paths=["service_account_name"]),
        "service_account_name": service_account_name,
    }
)

print("Updated config: '{}'".format(transfer_config.name))

Configurar uma execução manual em datas históricas

Além de agendar uma consulta para ser executada no futuro, também é possível acionar execuções imediatas manualmente. É necessário acionar uma execução imediata se sua consulta usar o parâmetro run_date e houver problemas durante uma execução anterior.

Por exemplo: todos os dias às 9h, você consulta uma tabela de origem para as linhas que correspondem à data atual. No entanto, você acha que os dados não foram adicionados à tabela de origem nos últimos três dias. Nessa situação, é possível definir a consulta para ser executada em dados históricos em um período que você especificar. Ela será executada usando combinações de parâmetros run_date e run_time que correspondem às datas que você configurou na consulta programada.

Depois de configurar uma consulta programada, veja como executar a consulta usando um período histórico:

Console

Depois de clicar em Programar para salvar a consulta, clique no botão Consultas programadas para ver todas as consultas relacionadas. Clique em qualquer nome de exibição para ver os detalhes da programação de consulta. No canto superior direito da página, clique em Programar preenchimento para especificar um período histórico.

Botão &quot;Programar preenchimento&quot;.

Os ambientes de execução escolhidos estão todos no intervalo selecionado, incluindo a primeira data e excluindo a última data.

definir datas históricas

Exemplo 1

A consulta programada está definida para ser executada every day 09:00 no horário do Pacífico. Faltam dados de 1º, 2 e 3 de janeiro. Escolha o período histórico de dados a seguir:

Start Time = 1/1/19
End Time = 1/4/19

Sua consulta será executada usando os parâmetros run_date e run_time que correspondem aos horários a seguir:

  • 01/01/19 às 9h, horário do Pacífico
  • 02/01/19 às 9h, horário do Pacífico
  • 03/01/19 às 9h, horário do Pacífico

Exemplo 2

A consulta programada está definida para ser executada every day 23:00 no horário do Pacífico. Faltam dados de 1º, 2 e 3 de janeiro. Escolha os períodos históricos de dados a seguir. Datas posteriores são escolhidas porque o UTC tem uma data diferente às 23h, horário do Pacífico:

Start Time = 1/2/19
End Time = 1/5/19

Sua consulta será executada usando os parâmetros run_date e run_time que correspondem aos horários a seguir:

  • 02/01/19 às 6h UTC ou 01/01/2019 às 23h, horário do Pacífico
  • 03/01/19 às 6h UTC ou 02/01/2019 às 23h, horário do Pacífico
  • 04/01/19 às 6h UTC ou 03/01/2019 às 23h, horário do Pacífico

Depois de configurar execuções manuais, atualize a página para vê-las na lista de execuções.

bq

Para executar manualmente a consulta em um período histórico:

Insira o comando bq mk e forneça a sinalização de execução de transferência --transfer_run. As sinalizações abaixo também são obrigatórias:

  • --start_time
  • --end_time
bq mk \
--transfer_run \
--start_time='start_time' \
--end_time='end_time' \
resource_name

Substitua:

  • start_time e end_time. Os carimbos de data/hora que terminam em Z ou contêm um deslocamento de fuso horário válido. Exemplos:
    • 2017-08-19T12:11:35.00Z
    • 2017-05-25T00:00:00+00:00
  • resource_name. O nome de recurso da transferência ou consulta programada. Ele também é conhecido como a configuração da transferência.

Por exemplo, o comando a seguir programa um preenchimento para o recurso de consulta programada (ou configuração de transferência): projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7.

  bq mk \
  --transfer_run \
  --start_time 2017-05-25T00:00:00Z \
  --end_time 2017-05-25T00:00:00Z \
  projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

Para ver mais informações, consulte bq mk --transfer_run.

API

Use o método projects.locations.transferConfigs.scheduleRun e forneça um caminho do recurso TransferConfig.

Java

Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ScheduleTransferRunsRequest;
import com.google.cloud.bigquery.datatransfer.v1.ScheduleTransferRunsResponse;
import com.google.protobuf.Timestamp;
import java.io.IOException;
import org.threeten.bp.Clock;
import org.threeten.bp.Instant;
import org.threeten.bp.temporal.ChronoUnit;

// Sample to run schedule back fill for transfer config
public class ScheduleBackFill {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    Clock clock = Clock.systemDefaultZone();
    Instant instant = clock.instant();
    Timestamp startTime =
        Timestamp.newBuilder()
            .setSeconds(instant.minus(5, ChronoUnit.DAYS).getEpochSecond())
            .setNanos(instant.minus(5, ChronoUnit.DAYS).getNano())
            .build();
    Timestamp endTime =
        Timestamp.newBuilder()
            .setSeconds(instant.minus(2, ChronoUnit.DAYS).getEpochSecond())
            .setNanos(instant.minus(2, ChronoUnit.DAYS).getNano())
            .build();
    scheduleBackFill(configId, startTime, endTime);
  }

  public static void scheduleBackFill(String configId, Timestamp startTime, Timestamp endTime)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ScheduleTransferRunsRequest request =
          ScheduleTransferRunsRequest.newBuilder()
              .setParent(configId)
              .setStartTime(startTime)
              .setEndTime(endTime)
              .build();
      ScheduleTransferRunsResponse response = client.scheduleTransferRuns(request);
      System.out.println("Schedule backfill run successfully :" + response.getRunsCount());
    } catch (ApiException ex) {
      System.out.print("Schedule backfill was not run." + ex.toString());
    }
  }
}

Python

Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

import datetime

from google.cloud.bigquery_datatransfer_v1 import (
    DataTransferServiceClient,
    StartManualTransferRunsRequest,
)

# Create a client object
client = DataTransferServiceClient()

# Replace with your transfer configuration name
transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"
now = datetime.datetime.now(datetime.timezone.utc)
start_time = now - datetime.timedelta(days=5)
end_time = now - datetime.timedelta(days=2)

# Some data sources, such as scheduled_query only support daily run.
# Truncate start_time and end_time to midnight time (00:00AM UTC).
start_time = datetime.datetime(
    start_time.year, start_time.month, start_time.day, tzinfo=datetime.timezone.utc
)
end_time = datetime.datetime(
    end_time.year, end_time.month, end_time.day, tzinfo=datetime.timezone.utc
)

requested_time_range = StartManualTransferRunsRequest.TimeRange(
    start_time=start_time,
    end_time=end_time,
)

# Initialize request argument(s)
request = StartManualTransferRunsRequest(
    parent=transfer_config_name,
    requested_time_range=requested_time_range,
)

# Make the request
response = client.start_manual_transfer_runs(request=request)

# Handle the response
print("Started manual transfer runs:")
for run in response.runs:
    print(f"backfill: {run.run_time} run: {run.name}")

Excluir consultas programadas

Console

Para excluir uma consulta programada pelo console:

  1. No painel de navegação, clique em Consultas programadas.

  2. Na lista de consultas programadas, clique no nome da consulta que você quer excluir.

  3. Na página Detalhes da consulta programada que é aberta, clique em Excluir. Atualizar as credenciais de consultas programadas.

Java

Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.DeleteTransferConfigRequest;
import java.io.IOException;

// Sample to delete a transfer config
public class DeleteTransferConfig {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // i.e projects/{project_id}/transferConfigs/{config_id}` or
    // `projects/{project_id}/locations/{location_id}/transferConfigs/{config_id}`
    String configId = "MY_CONFIG_ID";
    deleteTransferConfig(configId);
  }

  public static void deleteTransferConfig(String configId) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      DeleteTransferConfigRequest request =
          DeleteTransferConfigRequest.newBuilder().setName(configId).build();
      dataTransferServiceClient.deleteTransferConfig(request);
      System.out.println("Transfer config deleted successfully");
    } catch (ApiException ex) {
      System.out.println("Transfer config was not deleted." + ex.toString());
    }
  }
}

Python

Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

import google.api_core.exceptions
from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"
try:
    transfer_client.delete_transfer_config(name=transfer_config_name)
except google.api_core.exceptions.NotFound:
    print("Transfer config not found.")
else:
    print(f"Deleted transfer config: {transfer_config_name}")

Cotas

As consultas programadas são executadas com as credenciais e o projeto do criador, como se você estivesse executando a consulta. As consultas programadas são sempre executadas como jobs de consulta em lote.

As consultas programadas usam recursos do serviço de transferência de dados do BigQuery, mas não são transferências e não estão sujeitas à cota de jobs de carregamento. As consultas programadas estão sujeitas às mesmas cotas e limites do BigQuery que as consultas manuais.

Preços

As consultas programadas têm o mesmo preço das consultas manuais do BigQuery.

Regiões aceitas

As consultas programadas são compatíveis nos locais a seguir.

Regiões

A tabela a seguir lista as regiões das Américas em que o BigQuery está disponível.
Descrição da região Nome da região Detalhes
Columbus, Ohio us-east5
Dallas us-south1 Ícone de folha Baixo CO2
Iowa us-central1 Ícone de folha CO2 baixo
Las Vegas us-west4
Los Angeles us-west2
Montreal northamerica-northeast1 Ícone de folha CO2 baixo
Norte da Virgínia us-east4
Oregon us-west1 Ícone de folha CO2 baixo
Salt Lake City us-west3
São Paulo southamerica-east1 Ícone de folha Baixo CO2
Santiago southamerica-west1 ícone de folha CO2 baixo
Carolina do Sul us-east1
Toronto northamerica-northeast2 Ícone de folha Baixo CO2
A tabela a seguir lista as regiões da Ásia-Pacífico onde o BigQuery está disponível.
Descrição da região Nome da região Detalhes
Délhi asia-south2
Hong Kong asia-east2
Jacarta asia-southeast2
Melbourne australia-southeast2
Mumbai asia-south1
Osaka asia-northeast2
Seul asia-northeast3
Singapura asia-southeast1
Sydney australia-southeast1
Taiwan asia-east1
Tóquio asia-northeast1
A tabela a seguir lista as regiões da Europa onde o BigQuery está disponível.
Descrição da região Nome da região Detalhes
Bélgica europe-west1 Ícone de folha Baixo CO2
Berlim europe-west10 Ícone de folha Baixo CO2
Finlândia europe-north1 Ícone de folha CO2 baixo
Frankfurt europe-west3 ícone de folha Baixo CO2
Londres europe-west2 ícone de folha Baixo CO2
Madri europe-southwest1 Ícone de folha Baixo CO2
Milão europe-west8
Países Baixos europe-west4 Ícone de folha Baixo CO2
Paris europe-west9 Ícone de folha Baixo CO2
Turim europe-west12
Varsóvia europe-central2
Zurique europe-west6 Ícone de folha Baixo CO2
A tabela a seguir lista as regiões do Oriente Médio em que o BigQuery está disponível.
Descrição da região Nome da região Detalhes
Dammam me-central2
Doha me-central1
Tel Aviv me-west1
A tabela a seguir lista as regiões da África onde o BigQuery está disponível.
Descrição da região Nome da região Detalhes
Johannesburgo africa-south1

Locais multirregionais

Veja na tabela a seguir as multirregiões onde o BigQuery está disponível.
Descrição multirregional Nome multirregional
Data centers dentro de estados membro da União Europeia1 EU
Data centers nos Estados Unidos2 US

1 Os dados localizados na multirregião EU são armazenados apenas em um dos seguintes locais: europe-west1 (Bélgica) ou europe-west4 (Países Baixos). O BigQuery determina automaticamente o local exato em que os dados são armazenados e processados.

2 Os dados localizados na multirregião US são armazenados apenas em um dos seguintes locais: us-central1 (Iowa), us-west1 (Oregon) ou us-central2 (Oklahoma). O local exato em que os dados são armazenados e processados é determinado automaticamente pelo BigQuery.

A seguir