Parâmetros do ambiente de execução em transferências do Cloud Storage

Ao configurar uma transferência de dados no Cloud Storage, no Armazenamento de blobs do Azure ou no Amazon Simple Storage Service (Amazon S3), é possível parametrizar o URI (ou caminho de dados) e a tabela de destino. A parametrização permite carregar dados de buckets organizados por data. Esses parâmetros são chamados de parâmetros de ambiente de execução para diferenciá-los dos parâmetros de consulta.

Ao usar os parâmetros de ambiente de execução em uma transferência, é possível:

  • especificar o modo de particionamento da tabela de destino;
  • recuperar arquivos que correspondem a uma data específica.

Parâmetros de ambiente de execução disponíveis

Ao configurar a transferência do Cloud Storage, Armazenamento de blobs ou Amazon S3, é possível especificar como você quer particionar a tabela de destino usando parâmetros de ambiente 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 transferências programadas regularmente, run_time representa o tempo de execução pretendido. Por exemplo, se a transferência for definida como “a cada 24 horas”, a diferença de run_time entre duas consultas consecutivas será de exatamente 24 horas, mesmo que o tempo real de execução varie um pouco.

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 transferências do Cloud Storage, Armazenamento de blobs e do Amazon S3 são compatíveis com os parâmetros de ambiente de execução no nome da tabela de destino usando uma sintaxe de modelo.

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 Purpose
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

Opções de particionamento

Há dois tipos de tabelas particionadas no BigQuery:

  • Tabelas particionadas por tempo de ingestão. Para transferências do Cloud Storage, do Armazenamento de blobs e do Amazon S3, o tempo de ingestão é o ambiente de execução da transferência.
  • Tabelas particionadas com base em uma coluna. O tipo de coluna precisa ser TIMESTAMP ou DATE.

Se a tabela de destino estiver particionada em uma coluna, você identificará a coluna de particionamento quando criar a tabela de destino e especificar o esquema. Saiba mais sobre como criar tabelas particionadas baseadas em colunas nesta página.

Exemplos de particionamento

Observações sobre o uso de parâmetros

  • Se você particionar os dados com base no fuso horário local, precisará calcular manualmente o deslocamento de hora a partir do UTC. Basta usar o mecanismo de deslocamento na sintaxe de modelo.
  • Os minutos não podem ser especificados em parâmetros.
  • É permitido usar caracteres curinga no URI ou no caminho de dados em combinação com parâmetros no nome da tabela de destino.

Exemplos de parâmetros de ambiente de execução

Os exemplos a seguir mostram maneiras de combinar o caractere curinga e os parâmetros em casos de uso comuns. Suponha que o nome da tabela seja mytable e run_time seja 2018-02-15 00:00:00 (UTC) em todos os exemplos.

Transferir dados para uma tabela não particionada

Este caso de uso se aplica ao carregamento de novos arquivos de um bucket do Cloud Storage, Armazenamento de blobs ou do Amazon S3 em uma tabela não particionada. Neste exemplo, usamos um caractere curinga no URI ou caminho de dados e uma transferência de atualização ad hoc para coletar novos arquivos.

Fonte de dados URI de origem ou caminho de dados Nome da tabela de destino
Cloud Storage gs://bucket/*.csv mytable
Amazon S3 s3://bucket/*.csv mytable
Armazenamento de blobs *.csv mytable

Carregar um snapshot de todos os dados em uma tabela particionada por tempo de processamento

Nesse caso, todos os dados no URI ou caminho de dados especificado são transferidos para uma tabela particionada até a data de hoje. Em uma transferência de atualização, essa configuração seleciona os arquivos adicionados desde o último carregamento e os inclui em uma partição específica.

Fonte de dados URI de origem ou caminho de dados Nome da tabela de destino parametrizada Nome da tabela de destino avaliada
Cloud Storage gs://bucket/*.csv mytable${run_time|"%Y%m%d"} mytable$20180215
Amazon S3 s3://bucket/*.csv mytable${run_time|"%Y%m%d"} mytable$20180215
Armazenamento de blobs *.csv mytable${run_time|"%Y%m%d"} mytable$20180215

Este caso de uso transfere os dados de hoje para uma tabela particionada na data de hoje. Este exemplo também se aplica a uma transferência de atualização que recupera arquivos recém-adicionados que correspondem a uma determinada data, além de carregar os dados na partição correspondente.

Fonte de dados Caminho de dados ou URI parametrizado Nome da tabela de destino parametrizada URI ou caminho de dados avaliado Nome da tabela de destino avaliada
Cloud Storage gs://bucket/events-{run_time|"%Y%m%d"}/*.csv mytable${run_time|"%Y%m%d"} gs://bucket/events-20180215/*.csv mytable$20180215
Amazon S3 s3://bucket/events-{run_time|"%Y%m%d"}/*.csv mytable${run_time|"%Y%m%d"} s3://bucket/events-20180215/*.csv mytable$20180215
Armazenamento de blobs events-{run_time|"%Y%m%d"}/*.csv mytable${run_time|"%Y%m%d"} events-20180215/*.csv mytable$20180215

A seguir