Como usar parâmetros de ambiente de execução em transferências

Ao configurar uma transferência do Cloud Storage ou do Amazon S3, é possível parametrizar o URI e a tabela de destino. Assim, você carrega dados de buckets organizados por data. Esses parâmetros são chamados de runtime parameters 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 ou do 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 seguinte formato: %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 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 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

Opções de particionamento

As transferências do Cloud Storage e do Amazon S3 podem gravar em tabelas de destino particionadas ou não. Há dois tipos de particionamento de tabelas no BigQuery:

  • Tabelas particionadas por tempo de ingestão: particionadas com base no tempo de ingestão. Para transferências do Cloud Storage e do Amazon S3, o tempo de ingestão é o ambiente de execução da transferência.
  • Tabelas particionadas: tabelas que são 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 do Cloud Storage em combinação com parâmetros no nome da tabela de destino. Para mais informações sobre caracteres curinga, consulte Suporte a caracteres curinga para URIs do Cloud Storage.

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.

Como transferir dados do Cloud Storage ou Amazon S3 para uma tabela não particionada

Este caso de uso se aplica ao carregamento de novos arquivos de um bucket do Cloud Storage ou do Amazon S3 em uma tabela não particionada. Este exemplo usa um caractere curinga no URI e uma transferência ad hoc de atualização para selecionar novos arquivos com pelo menos uma hora.

Origem de dados URI de origem Nome da tabela de destino
Cloud Storage gs://bucket/*.csv mytable
Amazon S3 s3://bucket/*.csv mytable

Carregar um snapshot de todos os dados em uma tabela particionada por tempo de ingestão

Nesse caso, todos os dados no URI 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.

Origem de dados URI de origem 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

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.

Origem de dados URI parametrizado Nome da tabela de destino parametrizada URI 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

A seguir