Cloud Storage 转移作业中的运行时参数

在 Cloud Storage、Azure Blob Storage 或 Amazon Simple Storage Service (Amazon S3) 中设置数据转移作业时,您可以将 URI(或数据路径)和目标表参数化。参数化允许您从按日期整理的存储桶加载数据。这些参数称为运行时参数,以便与查询参数区分开来。

如果您在转移作业中使用运行时参数,则可以执行以下操作:

  • 指定您要对目标表进行分区的方式
  • 检索与特定日期匹配的文件

可用的运行时参数

设置 Cloud Storage、Blob Storage 或 Amazon S3 转移作业时,您可以使用运行时参数指定如何对目标表进行分区。

参数 模板类型
run_time 带格式的时间戳 采用世界协调时间 (UTC),基于计划。对于定期运行的计划转移作业,run_time 表示预期执行时间。例如,如果转移作业设置为“每 24 小时”执行一次,则连续两次查询之间的 run_time 差值将正好为 24 小时,即使实际的执行时间可能略有不同也是如此。

请参阅 TransferRun.runTime
run_date 日期字符串 run_time 参数的日期格式为 %Y%m%d,例如“20180101”。此格式与提取时间分区表兼容。

模板系统

Cloud Storage、Blob Storage 和 Amazon S3 转移作业支持使用模板语法在目标表名称中采用运行时参数。

参数模板语法

模板语法支持基本的字符串模板和时间偏移量设置。您可以采用以下格式来引用参数:

  • {run_date}
  • {run_time[+\-offset]|"time_format"}
参数 用途
run_date 此参数将替换成格式为 YYYYMMDD 的日期。
run_time 此参数支持以下属性:


offset
按小时 (h)、分钟 (m) 和秒 (s) 的顺序表示的时间偏移量。
不支持天 (d)。
允许使用小数,例如 1.5h

time_format
带格式的字符串。最常见的格式参数是年 (%Y)、月 (%m) 和日 (%d)。
对于分区表,YYYYMMDD 是必需的后缀,等效于“%Y%m%d”。

详细了解带格式的 datetime 元素

使用说明
  • run_time、offset 和 time_format 之间不允许有空格。
  • 如需在字符串中包含文本大括号,您可以将其转义为 '\{' and '\}'
  • 如需在 time_format 中包含文本引号或竖线(例如 "YYYY|MM|DD"),您可以在格式字符串中将其转义为 '\"''\|'

参数模板示例

以下示例演示了如何使用不同的时间格式指定目标表名称,以及如何设置运行时间的偏移量。
run_time (UTC) 模板化参数 输出目标表名称
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"}

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

分区选项

BigQuery 中有两种类型的分区表:

  • 按提取时间分区的表。对于 Cloud Storage、Blob Storage 和 Amazon S3 转移作业,提取时间就是转移作业的运行时间。
  • 根据列分区的表。列类型必须是 TIMESTAMPDATE 列。

如果目标表是基于某一列进行分区的,则在创建目标表并指定其架构时,您应确定分区列。如需详细了解如何创建基于列的分区表,请参阅创建和使用分区表

分区示例

  • 没有分区的表
    • 目标表:mytable
  • 提取时间分区表
    • 目标表:mytable$YYYYMMDD
    • 请注意,无法指定分钟数。
  • 列分区表
    • 目标表:mytable
    • 在创建表的架构时,将分区列指定为 TIMESTAMPDATE 列。

有关参数用法的注意事项

  • 如果您根据自己的本地时区对数据进行分区,则需要使用模板语法中的偏移机制手动计算相对于世界协调时间 (UTC) 的小时偏移量。
  • 无法在参数中指定分钟数。
  • 系统允许将 URI 或数据路径的通配符与目标表名称中的参数搭配使用。

运行时参数示例

以下示例展示了将通配符和参数搭配用于常见用例的方法。对于所有示例,假设表的名称为 mytablerun_time2018-02-15 00:00:00(世界协调时间 (UTC))。

将数据转移到非分区表

此用例适用于将新文件从 Cloud Storage、Blob Storage 或 Amazon S3 存储桶加载到非分区表中。此示例在 URI 或数据路径中使用通配符,并使用临时刷新转移作业来选取新文件。

数据源 来源 URI 或数据路径 目标表名称
Cloud Storage gs://bucket/*.csv mytable
Amazon S3 s3://bucket/*.csv mytable
Blob 存储 *.csv mytable

将包含所有数据的快照加载到注入时间分区表中

在此示例中,指定的 URI 或数据路径中的所有数据都将转移到一个按当天日期分区的表中。在一项刷新转移作业中,此配置会选取自从上次加载后添加的文件,并将其添加到某个特定的分区中。

数据源 来源 URI 或数据路径 参数化的目标表名称 计算的目标表名称
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
Blob 存储 *.csv mytable${run_time|"%Y%m%d"} mytable$20180215

此用例将当天的数据转移到按当天日期分区的表中。此示例还适用于刷新转移作业,该作业检索与某一日期相匹配的新增文件,并将数据加载到相应的分区中。

数据源 参数化 URI 或数据路径 参数化的目标表名称 评估的 URI 或数据路径 计算的目标表名称
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
Blob 存储 events-{run_time|"%Y%m%d"}/*.csv mytable${run_time|"%Y%m%d"} events-20180215/*.csv mytable$20180215

后续步骤