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 時間ごと」に設定されている場合、実際の実行時間が多少異なる場合でも、連続する 2 つのクエリ間の run_time の差は、ちょうど 24 時間になります。

TransferRun.runTime をご覧ください。
run_date 日付文字列 %Y%m%d の形式の run_time パラメータの日付（たとえば、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 形式の間に空白文字は使用できません。
  • 文字列にリテラル中かっこを含めるには、'\{' 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 には次の 2 種類のパーティション分割テーブルがあります。

  • 取り込み時間で分割されたテーブル。Cloud Storage、Blob Storage、Amazon S3 の転送では、取り込み時間は転送の実行時間です。
  • 列を基準にしてパーティション分割されたテーブル。列の型は TIMESTAMP または DATE でなければなりません。

宛先テーブルが特定の列でパーティション分割されている場合は、宛先テーブルを作成する際にパーティショニング列を確認してそのスキーマを指定します。列ベースのパーティション分割テーブルの作成については、パーティション分割テーブルの作成と使用をご覧ください。

パーティショニングの例

パラメータの使用に関する注意事項

  • ローカルのタイムゾーンを基準にしてデータをパーティション分割する場合、テンプレート構文のオフセット メカニズムを使用して、UTC からの時間オフセットを手動で計算する必要があります。
  • パラメータで分を指定することはできません。
  • 宛先テーブルの URI またはデータパスにワイルドカードを使用する場合、パラメータ名を使用できます。

ランタイム パラメータの例

次の例は、一般的なユースケースとしてワイルドカード文字とパラメータを組み合わせる方法を示しています。例のすべてで、テーブル名は mytable であり、run_time は 2018-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 Storage *.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 Storage *.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 Storage events-{run_time|"%Y%m%d"}/*.csv mytable${run_time|"%Y%m%d"} events-20180215/*.csv mytable$20180215

次のステップ