カスタム変数について

概要

カスタム変数とは、転送設定・データマート定義・dbtジョブ設定などの設定項目に埋め込むことができる変数です。
カスタム変数の値は、ジョブの実行時に展開されます。

利用例

たとえば、以下のような目的で利用されます。

• 転送元側のSQL文に埋め込みます。
  ジョブ実行日時が展開されることで、転送対象の行をフィルタリングできます。
  
• 転送先テーブル名にsuffixの形で埋め込みます。
  ジョブ実行日時が展開されることで、シャーディングテーブルを作成できます。
  

カスタム変数の種類

文字列のカスタム変数

ジョブの実行時に文字列を展開できます。
定義する際には、固定の文字列を設定します。

日付・時刻のカスタム変数

カスタム変数に値を展開する際の基準日時に対して、相対的な時間を展開できます。
なお、ここで指定したタイムゾーンに基づいて展開される日時は定まり、指定した日付フォーマットで値が展開されます。
たとえば、以下のケースで基準日時が「2024年04月01日00時00分00秒（日本時間）」となった場合、2024-03-31 00:00:00という値が展開されます。

なお、時刻・日付 (キューイング時) と時刻・日付 (実行時) は、カスタム変数に値を展開する際の基準日時に違いがあります。
詳しくは、後述の基準日時についてを参照ください。

日付・時刻のフォーマット

基準日時が「2024年04月01日00時00分00秒（日本時間）」の場合、以下のように展開されます。

上記例以外にもRuby言語のstrftimeメソッドのフォーマットが利用可能です。
詳しくは、Rubyリファレンスマニュアルを参照ください。

カスタム変数の展開方法

ジョブを実行するときに、以下の3つより選択できます。

• 現在時刻を基準に展開：ジョブの実行開始時間を基準日時とします。
• 指定日時を基準に展開：基準日時を手動で定義できます。
• 変数ごとに値を指定：カスタム変数に展開する値を手動で定義できます。

なお、スケジュール設定によってジョブが実行された場合は、ジョブの実行開始時間が基準日時となります。

仕様に関する補足情報

基準日時について

時刻・日付 (キューイング時) と時刻・日付 (実行時) は、カスタム変数に値を展開する際の基準日時に違いがあります。

• 時刻・日付 (実行時) の場合：
  • 該当ジョブの開始日時を基準に、値が展開されます。
• 時刻・日付 (キューイング時) の場合：
  • 該当ジョブの実行がトリガーされた日時を基準に、値が展開されます。

ワークフロージョブにおけるカスタム変数の展開仕様

カスタム変数ループ実行を設定している場合

カスタム変数ループ実行でループ対象となったカスタム変数には、ループ実行側の設定に基づいて値が展開されます。
すなわち、ワークフロージョブの実行時に選択したカスタム変数の展開方法は、ループ実行側の値の展開設定によって上書きされます。

ワークフロー定義内にワークフロー定義を組み込んだ場合

前者を親ワークフロー、後者を子ワークフローと定義します。
子ワークフローをカスタム変数でループ実行した場合、ループ対象となったカスタム変数の展開値は、子ワークフロー実行時に引き継がれます。
すなわち、カスタム変数の展開値が子ワークフロータスク内にある同名のカスタム変数に展開されます。