Como programar consultas

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

Visão geral

É possível programar consultas para que sejam executadas de maneira recorrente. As consultas programadas precisam ser escritas em SQL padrão, que pode incluir instruções em linguagem de definição de dados (DDL, na sigla em inglês) e linguagem de manipulação de dados (DML, na sigla em inglês). A string de consulta e a tabela de destino podem ser parametrizadas, o que possibilita organizar os resultados da consulta por data e hora.

Antes de começar

Antes de criar uma consulta programada:

  • Nas consultas programadas, são usados recursos do serviço de transferência de dados do BigQuery. Verifique se você concluiu todas as ações necessárias em Como ativar o serviço de transferência de dados do BigQuery.

  • Se você estiver criando a consulta programada usando a IU da Web clássica do BigQuery, ative os pop-ups no seu navegador em bigquery.cloud.google.com para poder visualizar a janela de permissões. É preciso conceder ao serviço de transferência de dados do BigQuery a permissão para gerenciar a consulta agendada.

Permissões necessárias

Antes de programar uma consulta:

  • Certifique-se de que a pessoa que está criando a transferência tenha as seguintes permissões necessárias no BigQuery:

    • Permissões bigquery.jobs.create ou bigquery.transfers.update para criar a transferência.
    • Permissões bigquery.datasets.update no conjunto de dados de destino

    O papel predefinido do Cloud IAM bigquery.jobUser inclui as permissões bigquery.jobs.create. Para mais informações sobre os papéis do Cloud IAM no BigQuery, consulte Permissões e papéis predefinidos.

Antes de modificar uma consulta programada:

  • Verifique se a pessoa que está modificando a consulta programada tem uma das seguintes permissões necessárias no BigQuery:
    • As permissões bigquery.jobs.create e a pessoa precisam ser os criadores da programação.
    • Permissões bigquery.transfers.update.

Opções de configuração

String de consulta

A string de consulta precisa ser válida e escrita em SQL padrão. As execuções de consulta programadas recebem os seguintes parâmetros de consulta.

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

Parâmetros disponíveis

Parâmetro Tipo no SQL padrão 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 DATA 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

Na configuração da consulta programada, se não houver uma tabela de destino para os resultados, o BigQuery tentará criá-la para você.

Se estiver usando uma consulta em DDL ou DML:

  • No Console do Cloud, escolha a região ou o Local de processamento. Ele é necessário nas consultas em DDL ou DML que criam a tabela de destino.
  • Na IU da Web clássica do BigQuery, deixe Tabela de destino em branco.

Se houver uma tabela de destino, o respectivo esquema poderá ser atualizado com base nos resultados da consulta caso você adicione colunas ao esquema (ALLOW_FIELD_ADDITION) ou altere o modo de uma coluna de REQUIRED para NULLABLE (ALLOW_FIELD_RELAXATION). Em todos os outros casos, as alterações no esquema da tabela entre execuções causam falha na consulta programada.

É 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.

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.

Se estiver usando uma consulta em DDL ou DML:

  • No Console do Cloud, a opção de preferência de gravação não será exibida.
  • Na IU da Web clássica do BigQuery, deixe Preferência de gravação em branco.

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.

Clustering

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 cluster a partir do 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 não está disponível no Console do Cloud, mas está nos métodos de configuração da IU da Web clássica do BigQuery, da CLI e da API. Se você estiver usando uma consulta em DDL ou DML com particionamento, deixe o Campo de particionamento em branco.

Há dois tipos de particionamento de tabelas no BigQuery:

  • Tabelas particionadas por tempo de ingestão: particionamento com base no ambiente de execução da consulta programada.
  • Tabelas particionadas em uma coluna: particionamento com base em uma coluna TIMESTAMP ou DATE.

Para as tabelas particionadas em uma coluna:

  • Na IU da Web clássica do BigQuery, se a tabela de destino for particionada em uma coluna, especifique o nome da coluna no Campo de particionamento ao Configurar uma consulta programada. Para as tabelas particionadas por tempo de ingestão e tabelas não particionadas, deixe o Campo de particionamento em branco.

Para as tabelas particionadas por tempo de ingestão:

  • Indique o particionamento de data no nome da tabela de destino. Veja abaixo a sintaxe de modelo do nome da tabela.

Exemplos de particionamento

  • Tabela sem particionamento
    • Tabela de destino: mytable
    • Campo de particionamento: deixe em branco
  • Tabela particionada por tempo de ingestão
    • Tabela de destino: mytable$YYYYMMDD
    • Campo de particionamento: deixe em branco
  • Tabela particionada por coluna
    • Tabela de destino: mytable
    • Campo de particionamento: nome da coluna TIMESTAMP ou DATE usada no particionamento da tabela

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, 20180101. 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 Finalidade
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|"%H%M%s"} 20180215_mytable_000137

Como usar uma conta de serviço

É possível configurar uma consulta programada para usar uma conta de serviço como autenticação. Contas de serviço são Contas do Google associadas ao seu projeto do GCP. Contas de serviço podem executar jobs associados às credenciais de serviço delas mesmas em vez de credenciais do usuário final, como um pipeline de processamento em lote ou uma consulta programada.

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

  • Você terá a opção de configurar a consulta programada com uma conta de serviço em Como configurar uma consulta programada, em Opções avançadas.

  • É possível usar a interface de linha de comando (CLI) para atualizar uma consulta programada com as credenciais de uma conta de serviço. Consulte Como atualizar as credenciais de uma consulta programada.

  • Na IU da Web do BigQuery atual, não é possível atualizar uma consulta programada para que ela use credenciais de conta de serviço.

  • A IU da Web clássica não é compatível com a criação ou a atualização de consultas programadas para usar contas de serviço.

Como configurar uma consulta programada

Console

  1. Abra a IU da Web do BigQuery no Console do Cloud.

    Acesse o Console do Cloud

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

    Agendar consulta na IU da Web do BigQuery

  3. As opções de consulta programada são exibidas no painel Nova 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 identifique facilmente a consulta programada, caso seja necessário modificá-la no futuro.
    • Opcional: em Opções de programação, use o valor padrão Diário (a cada 24 horas, com base na hora da criação) ou clique em Programar horário de início para alterar a hora. Também é possível alterar o intervalo para Semanal, Mensal ou Personalizado. Se você selecionar "Personalizada", especifique um horário em estilo Cron, como every 3 hours. O menor período permitido é de 15 minutos. Veja o campo schedule em TransferConfig para saber outros valores de API válidos.

      Nova consulta programada na parte superior

  5. Para uma consulta SELECT em SQL padrão, forneça 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.
    • Nas consultas em DDL ou DML, essa opção não está disponível.
  6. Em Preferência de gravação na tabela de destino, escolha WRITE_TRUNCATE para substituir a tabela de destino ou WRITE_APPEND para anexar dados a ela.

    • Nas consultas em DDL ou DML, essa opção não está disponível.

    Novo destino de consulta programada

  7. (Opcional) Opções avançadas:

    • (Opcional) CMEK: se você usar chaves de criptografia gerenciadas pelo cliente, será possível selecionar Chave gerenciada pelo cliente em Opções avançadas. Uma lista das CMEKs disponíveis será exibida para você escolher uma opção.

    • (Opcional) Autenticar com uma conta de serviço: se você tem uma ou mais contas de serviço associadas ao projeto do GCP, é possível associar uma à consulta programada, em vez de às credenciais do próprio usuário. Em Credencial de consulta programada, clique no menu para ver uma lista de contas de serviço disponíveis.

      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ência.

    • Para consultas em DDL/DML, escolha a região ou o Local de processamento.

    • (Opcional) Em Tópico do Pub/Sub, digite o nome do tópico do Pub/Sub, por exemplo: projects/myproject/topics/mytopic.

      Nova consulta programada em DDL/DML

  9. Clique no botão Programar.

IU clássica

  1. Acesse a IU clássica da Web do BigQuery.

    Acesse a IU da Web clássica do BigQuery

  2. Execute a consulta do seu interesse.

    Programe a consulta na IU da Web clássica do BigQuery.

  3. Quando estiver satisfeito com os resultados, clique em Programar consulta. As opções de consulta programada são exibidas abaixo da caixa da consulta.

  4. Na página Nova consulta programada:

    • Em Conjunto de dados de destino, escolha o conjunto de dados apropriado.
    • Em Nome de exibição, insira um nome para a consulta programada, como My scheduled query. Esse nome pode ser qualquer valor que identifique facilmente a consulta programada, caso seja necessário modificá-la no futuro.
    • Em Tabela de destino:
      • Para uma consulta SQL padrão, insira o nome da tabela de destino.
      • Em caso de consulta DDL ou DML, deixe esse campo em branco.
    • Em Preferência de gravação:
      • Para uma consulta SQL padrão, escolha WRITE_TRUNCATE para substituir a tabela de destino ou WRITE_APPEND para anexar dados a ela.
      • Para uma consulta em DDL ou DML, escolha Não especificado.
    • (Opcional) Em Campo de particionamento:

    • (Opcional) Em Chave do KMS da tabela de destino, se você usar chaves de criptografia gerenciadas pelo cliente, será possível selecionar a chave de criptografia gerenciada pelo cliente.

      Nova consulta programada.

    • Opcional: em Programação, use o valor padrão Diário (a cada 24 horas, com base na hora da criação) ou clique em Editar para alterar a hora. Também é possível alterar o intervalo para Semanal, Mensal ou Personalizado. Se você selecionar "Personalizada", especifique um horário em estilo Cron, como every 3 hours. O menor período permitido é de 15 minutos. Veja o campo schedule em TransferConfig para saber outros valores de API válidos.

      Programe a consulta.

    • Opcional: expanda a seção Avançado e configure as notificações.

      • Em Tópico do Pub/Sub, digite o nome do tópico do Pub/Sub, por exemplo: projects/myproject/topics/mytopic.
      • Marque Enviar notificações por e-mail para permitir notificações sobre falhas na execução da transferência.

        Tópico do Pub/Sub.

  5. Clique em Adicionar.

CLI

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

Com esse método, serão adicionadas as sinalizações destination_table (ou target_dataset), --schedule e --display_name ao comando bq query para criar uma consulta programada.

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

Em que:

  • name é o nome de exibição da consulta programada. Esse nome pode ser qualquer valor que identifique facilmente a consulta programada, caso seja necessário modificá-la no futuro;
  • table é a tabela de destino dos resultados da consulta:
    • --target_dataset é uma maneira alternativa de nomear o conjunto de dados de destino dos resultados da consulta, quando usado com consultas em DDL/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. Exemplos:
    • --schedule='every 24 hours'
    • --schedule='every 3 hours'

Sinalizações opcionais:

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

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

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

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' \
    --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 CLI do serviço de transferência de dados do BigQuery para configurar uma transferência.

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

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

  • --data_source
  • --target_dataset (opcional para consultas DDL/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/DML, também é possível usar a sinalização --location para especificar uma região determinada de processamento. Se --location não for especificado, o local global do Google Cloud será usado.

  • --service_account_name serve para autenticar a consulta programada com uma conta de serviço em vez da conta de usuário individual. Observação: o uso de contas de serviço com consultas programadas está em versão Beta.

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

Em que:

  • dataset é o conjunto de dados de destino na configuração da transferência:
  • Esse parâmetro é opcional nas consultas em DDL/DML, mas necessário em todas as outras.
  • name é o nome de exibição na configuração da transferência. Esse nome pode ser qualquer valor que identifique facilmente a consulta programada (transferência), caso seja necessário modificá-la no futuro;
  • parameters contém os parâmetros para a configuração da 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 em DDL/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 em DDL/DML, mas necessário em todas as outras.
    • (Opcional) O parâmetro destination_table_kms_key é para chaves de criptografia gerenciadas pelo cliente.
    • (Opcional) O parâmetro --service_account_name serve para autenticação usando uma conta de serviço em vez de uma conta de usuário individual.
  • data_source é a fonte de dados: scheduled_query.
  • 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 com uma 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","service_account_name=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com"}' \
    --data_source=scheduled_query
    

    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.

    Python

    Antes de testar esta amostra, siga as instruções de configuração para Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery Python (em inglês).

    from google.cloud import bigquery_datatransfer_v1
    import google.protobuf.json_format
    
    client = bigquery_datatransfer_v1.DataTransferServiceClient()
    
    # TODO(developer): Set the project_id to the project that contains the
    #                  destination dataset.
    # project_id = "your-project-id"
    
    # TODO(developer): Set the destination dataset. The authorized user must
    #                  have owner permissions on the dataset.
    # dataset_id = "your_dataset_id"
    
    # TODO(developer): The first time you run this sample, set the
    # authorization code to a value from the URL:
    # https://www.gstatic.com/bigquerydatatransfer/oauthz/auth?client_id=433065040935-hav5fqnc9p9cht3rqneus9115ias2kn1.apps.googleusercontent.com&scope=https://www.googleapis.com/auth/bigquery%20https://www.googleapis.com/auth/drive&redirect_uri=urn:ietf:wg:oauth:2.0:oob
    #
    # authorization_code = "_4/ABCD-EFGHIJKLMNOP-QRSTUVWXYZ"
    #
    # You can use an empty string for authorization_code in subsequent runs of
    # this code sample with the same credentials.
    #
    # authorization_code = ""
    
    # 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 = client.project_path(project_id)
    
    transfer_config = google.protobuf.json_format.ParseDict(
        {
            "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",
        },
        bigquery_datatransfer_v1.types.TransferConfig(),
    )
    
    response = client.create_transfer_config(
        parent, transfer_config, authorization_code=authorization_code
    )
    
    print("Created scheduled query '{}'".format(response.name))

    Como visualizar o status de uma consulta programada

    IU da Web

    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.

    IU clássica

    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.

    CLI

    As consultas programadas são um tipo de transferência. Para exibir os detalhes de uma consulta programada, use a CLI do serviço de transferência de dados do BigQuery 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

    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.

    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.

    Como atualizar as credenciais de uma consulta programada

    IU da Web

    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.

    No momento, não é possível alterar as credenciais usadas em uma consulta programada para uma conta de serviço na IU da Web.

    IU clássica

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

    2. Clique em uma consulta programada na lista e o botão Atualizar credenciais será exibido abaixo dos detalhes da consulta programada.

      Atualizar as credenciais de consultas programadas.

    CLI

    As consultas programadas são um tipo de transferência. Para atualizar as credenciais de uma consulta programada, é possível usar a CLI do serviço de transferência de dados do BigQuery 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 com uma conta de serviço:

    bq update \
    --transfer_config \
    --update_credentials \
    --service_account_name=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com projects/862514376110/locations/us/transferConfigs/5dd12f26-0000-262f-bc38-089e0820fe38 \
    

    Como 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. Sua consulta é executada usando combinações de 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

    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

    Sua consulta programada está definida para ser executada every day 09:00 no horário do Pacífico. Você está perdendo dados de 1º, 2 e 3 de janeiro. Escolha o período histórico 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

    Sua consulta programada está definida para ser executada every day 23:00 no horário do Pacífico. Você está perdendo dados de 1º, 2 e 3 de janeiro. Escolha os períodos históricos a seguir. As 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 9h UTC ou 01/01/2019 às 23h, horário do Pacífico
    • 03/01/19 às 9h UTC ou 02/01/2019 às 23h, horário do Pacífico
    • 04/01/19 às 9h 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.

    IU clássica

    Depois de clicar em Adicionar para salvar a consulta programada, você verá os respectivos detalhes. Abaixo desses detalhes, clique no botão Iniciar execuções manuais para especificar um período histórico.

    botão

    Refine ainda mais o período para ter um horário de início e término ou deixe os campos de horário como 00:00:00.

    definir datas históricas

    Exemplo 1

    Se a consulta programada estiver configurada executar every day 14:00 e você aplicar o período histórico a seguir:

    Start Time = 2/21/2018 00:00:00 AM
    End Time = 2/24/2018 00:00:00 AM

    a consulta será executada nos horários a seguir:

    • 21/2/2018 14:00:00
    • 22/2/2018 14:00:00
    • 23/2/2018 14:00:00

    Exemplo 2

    Se a consulta programada estiver configurada para ser executada every fri at 01:05 e você aplicar o período histórico a seguir:

    Start Time = 2/1/2018 00:00:00(uma quinta-feira)
    End Time = 2/24/2018 00:00:00 AM (também uma quinta-feira)

    a consulta será executada nos horários a seguir:

    • 2/2/2018 01:05:00
    • 9/2/2018 01:05:00

    CLI

    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
    

    Em que:

    • start_time e end_time são carimbos de data/hora que terminam em Z ou contêm uma diferença de fuso horário válida. 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
    

    API

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

    Cotas

    A consulta programada é executada com as credenciais e o projeto do criador, como se você estivesse executando a consulta por conta própria. Assim como as consultas manuais, ela está sujeita às mesmas Cotas e limites do BigQuery.

    Preços

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

    Limitações e problemas conhecidos

    Regiões

    Não há suporte para consultas entre regiões, e a tabela de destino da consulta programada precisa estar na mesma região dos dados que estão sendo consultados. Para mais informações sobre regiões e multirregiões, veja os locais dos conjuntos de dados.

    Google Drive

    É possível consultar os dados do Google Drive em uma consulta programada. Se você estiver programando uma consulta atual, talvez precise clicar em "Atualizar credenciais" na tela de detalhes da consulta. Aguarde de 10 a 20 minutos para que a alteração entre em vigor. Pode ser necessário limpar o cache do navegador. As credenciais são atualizadas automaticamente para novas consultas programadas.

    Atualizar credenciais