転送でのランタイム パラメータの使用

Cloud Storage または Amazon S3 の転送を設定する際は、URI と宛先テーブルの両方をパラメータ化して、日付で整理されたバケットからデータを読み込むことができます。このようなパラメータは、クエリ パラメータと区別するために「ランタイム パラメータ」と呼ばれます。

転送でランタイム パラメータを使用する場合は、次のことができます。

  • 宛先テーブルを分割方法を指定する
  • 特定の日付に一致するファイルを取得する

使用可能なランタイム パラメータ

Cloud 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 と 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|"%H%M%s"} 20180215_mytable_000137

分割のオプション

Cloud Storage 転送および Amazon S3 転送では、分割された宛先テーブルまたは分割されていない宛先テーブルに書き込むことができます。BigQuery には次の 2 つのタイプのテーブル分割があります。

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

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

パーティショニングの例

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

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

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

次の例は、一般的なユースケースとしてワイルドカード文字とパラメータを組み合わせる方法を示しています。例のすべてで、テーブル名は mytable であり、run_time2018-02-15 00:00:00(UTC)であると想定しています。

Cloud Storage または Amazon S3 のデータをパーティション分割されていないテーブルに転送する

この使用例は、Cloud Storage または Amazon S3 のバケットからパーティション分割されていないテーブルに新しいファイルを読み込む際に適用されます。この例では、URI でワイルドカードを使用し、アドホックの更新転送によって、作成後 1 時間以上経過した新しいファイルを転送対象にしています。

データソース 抽出元 URI 宛先テーブル名
Cloud Storage gs://bucket/*.csv mytable
Amazon S3 s3://bucket/*.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

この使用例では、今日のデータが今日の日付で分割されたテーブルに転送されます。この使用例は更新転送にも適用されます。更新転送では、特定の日付に一致する新たに追加されたファイルが取得され、対応するパーティションに読み込まれます。

データソース パラメータ化された 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

次のステップ