カスタム変数について
  • 07 May 2024
  • PDF

カスタム変数について

  • PDF

記事の要約

概要

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

利用例

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

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

ワークフロー定義では、カスタム変数が埋め込まれたタスクに対して複数の値を順次展開することで、擬似的にループ処理をさせることができます。
詳しくは、カスタム変数ループ実行を参照ください。

転送設定にカスタム変数を埋め込む際の注意事項
  • 転送元側で定義したカスタム変数は、転送先側の設定項目には埋め込めません。同様に、転送先側で定義したカスタム変数は、転送元側の設定項目には埋め込めません。
  • 転送元側と転送先側で同名のカスタム変数が定義された場合、以下のケースにおいて転送先側のカスタム変数が優先されます。この場合、転送先側のカスタム変数の展開値が、転送元側のカスタム変数にも展開されます。
    • ワークフローのループ実行時
    • 転送設定STEP2のカラム定義のデフォルト値
    • TROCCO APIを利用したジョブの実行
    • 変数ごとに値を指定したジョブの実行

カスタム変数の種類

文字列のカスタム変数

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

固定の文字列が利用されるケース

文字列のカスタム変数は、ジョブ実行時に値が展開(上書き)されず、固定の文字列がそのまま用いられるケースがあります。
たとえば、以下のケースにおいて固定の文字列が利用されます。

  • ジョブ実行時に選択するカスタム変数展開方法にて、現在時刻を基準に展開または指定日時を基準に展開を選択した場合
  • ジョブがスケジュール実行された場合
  • ワークフロータスクのカスタム変数でループ実行にて、期間(相対指定)でループが選択されている場合

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

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

image

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

カスタム変数の展開方法

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

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

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

仕様に関する補足情報

基準日時について

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

  • 時刻・日付 (実行時) の場合:
    • 該当ジョブの開始日時を基準に、値が展開されます。
  • 時刻・日付 (キューイング時) の場合:
    • 該当ジョブの実行がトリガーされた日時を基準に、値が展開されます。
ワークフロージョブにおける、両者の基準となる日時の違い

時刻・日付 (キューイング時)時刻・日付 (実行時) における基準日時の差異は、ワークフロージョブの実行時において顕著となります。

  • 時刻・日付 (キューイング時)
    • ワークフロー定義内に存在する時刻・日付 (キューイング時) が埋め込まれたタスク(子ワークフロー内に定義されたタスクも含む)がある場合、それらの基準日時はすべてワークフロージョブが初回実行を開始した日時となります。
    • また、ワークフロージョブが自動リトライされた結果実行されるタスクの基準日時も、ワークフロージョブが初回実行を開始した日時となります。
  • 時刻・日付 (実行時)
    • 一方、ワークフロー定義に時刻・日付 (実行時) が埋め込まれたタスクがある場合、それらの基準日時は該当タスクのジョブが実際に実行を開始した日時となります

なお、スケジュール設定を用いてジョブを実行する運用の場合、時刻・日付 (キューイング時) の利用を推奨しています。
万一ジョブが失敗して翌日以降に再実行する場合に、前回のジョブの基準日時でカスタム変数に値を展開できるためです。

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

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

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

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

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


この記事は役に立ちましたか?

What's Next