TROCCO®ワークフローのカスタム変数とループ実行を完全に理解する

Posted at 2024-08-16

概要

TROCCO®の機能のなかでユニークなものであるカスタム変数について取り扱います。
カスタム変数は便利な機能ではありますが、初心者の方には少し複雑に見えるかもしれません。ここでは展開される値の優先度やされ方について特に焦点を当てたものとしたいと思います。
また、ワークフローにおけるカスタム変数ループについても同様に紹介したいと思います。

この記事を読むことでわかるようになること

TROCCO®ワークフローにおけるカスタム変数、およびループ実行の変数の優先度や展開のされ方について理解できる
カスタム変数のループ実行がわかるということは複雑なパイプラインがよりかんたんに構築できるかも

TROCCO®のワークフローとは

データのフローとして例えば Google AdsからS3にデータを蓄積させ、S3からDWH、最後にBIツールで可視化するために中間テーブルを作成する、といった一連のパイプラインを簡単に構築できるような機能となります。
他にもDWHのデータのレコード数に応じて失敗としてハンドリングするデータチェック機能や任意のHTTPリクエストをパイプラインに入れることができたりします。

HTTPリクエストについては下記記事が参考になりそうです。
https://qiita.com/hgkcho/items/27ef005401ff91f7154d

カスタム変数とは

転送設定やデータマート定義、ワークフローのタスクにもカスタム変数という可変な値を入れることができる機能があります。キューイングされた日時や実行時間などを記録するための用途や転送設定やデータマートの定義時に定めることができない値を変数として定義しておき実行時にバインドすることができます。このあたり詳しく後述します。

カスタム変数ループとは

その名の通り、カスタム変数をループして実行する機能です。今回深堀りたい機能となります。
日時を範囲指定して1日ごとに転送設定をループで実行したりBigqueryやsnowflakeに実際にselectした結果を元にループ実行といった高度なことまで対応しています。

準備

まずはカスタム変数が定義されている転送設定を用意しよう

カスタム変数ループをするものが必要なので、カスタム変数の定義された転送設定を用意します。
ここでは転送元snowflakeから転送先snowflakeに転送する設定で以下のカスタム変数を用意しました。

$var_string$
- データ型を文字列としてデフォルトの値を default_stringとしてます
$var_queued_date$
- 時刻・日付（キューイング時）としました
$var_execution_date$
時刻・日付（実行時）としました

転送先のテーブル名に以下のようにカスタム変数を元に名前が決定するようにして検証がわかりやすくします。

転送設定を単体で動かしたときにどうなるかを確かめる

↑で作成した転送を手動で一度実行してみます。カスタム変数の展開方法は現在時刻を基準に展開をします。これはスケジュール実行の場合もこの設定で実行されます。余談ですが、現在時刻以外にも指定した時刻での実行と変数ごとに指定の値を入れて実行ができます。いずれも名前の通り、指定した時間がそのままカスタム変数に入ったり、文字列の場合はその文字列がカスタム変数に展開されます。

実行した結果が以下です

実際にできたテーブル名

<DATABASE>.<SCHEMA>."qiita_test_default_string_2024-07-31 20:59:32_2024-07-31 20:59:44"

ここでわかったこと

文字列としてのカスタム変数は現在時刻で実行するとデフォルトの値で展開される
キューイング時の時刻での展開は　カスタム変数展開時刻と一致した時間で展開された
実行時の時刻での展開は 実行開始日時一致した時間で展開された

キューイング時の時刻は「実行ボタン」を押した時間に一致した時間で、実行時の時刻は実際にTROCCO®で処理を開始した時間が展開されています。

これで準備と事前知識は理解しました。早速次からワークフローでカスタム変数のループ実行をしてみましょう。

ワークフローでループ実行を定義してみよう

ループ実行にはいくつか種類がありますが、シンプルな期間でのループでカスタム変数の展開のされ方を見ていきます。以下ように定義してみました。違いがわかるように $var_execution_date$ のほうを現在から1年前 $var_queud_date$ から2年前に設定します。

これでワークフローを保存すればループ実行を含むワークフローの完成です。早速実行してどう展開されるのか見ていきましょう。

ワークフロー実行を「現在時刻を基準に展開」で展開してみる

↑で作成したループ実行を含むワークフローを「現在時刻を基準に展開」で展開してみます。転送設定を単体で実行したときとの差があるのか見ていきます。実際に実行した結果が以下です。

ここからわかること

キューイング時の時刻での展開としたカスタム変数はループ実行側で指定した値を現在時刻を元に展開された
実行時の時刻での展開としたカスタム変数も同じくループ実行側で指定した値を現在時刻を元に展開された

-> 転送設定単体で実行したときはキューイング時と実行時で展開される日時は違いましたが、ループ実行の場合はワークフローのループ実行側の設定が優先されることがわかった

ワークフロー実行を「指定時刻を基準に展開」で展開してみる

現在時刻を基準に展開について挙動がわかったので、つぎに「指定日時を基準に展開」での実行を検証してみます。

ここではわかりやすく2000年の日付を指定して実行します。実行結果は以下です

ここからわかること

キューイング時の時刻での展開としたカスタム変数はループ実行側で指定した値を現在時刻を元に展開された
実行時の時刻での展開としたカスタム変数も同じくループ実行側で指定した値を現在時刻を元に展開された

-> 転送設定単体で実行する場合指定した日時が $var_queued_date$ 　には指定した日時が、 $var_exection_date$ には実際に実行を開始した日時が入りますが、ループ実行の場合はループ定義のほうが優先されます。

ループ実行のまとめ

まとめると以下です（自明ですが・・。）

ワークフローの実行	転送ジョブのカスタム変数	ループの結果
現在時刻を基準に展開	時刻・日付（キューイング）	ループ実行側で指定した値を現在時刻を元に展開
現在時刻を基準に展開	時刻・日付（実行時）	ループ実行側で指定した値を現在時刻を元に展開
指定日時を基準に展開	時刻・日付（キューイング）	ループ実行側で指定した値を現在時刻を元に展開
指定日時を基準に展開	時刻・日付（実行時）	ループ実行側で指定した値を現在時刻を元に展開

比較のため、転送設定を単体またはループ実行でない状態でワークフロー実行した場合も記載しておきます。

実行パラメータ	転送ジョブのカスタム変数	結果
現在時刻を基準に展開	時刻・日付（キューイング）	「実行ボタン」を押したタイミング(スケジュール実行が開始された時刻)
現在時刻を基準に展開	時刻・日付（実行時）	実際に処理を始めた時刻
指定日時を基準に展開	時刻・日付（キューイング）	指定した時刻
指定日時を基準に展開	時刻・日付（実行時）	実際に処理を始めた時刻

ループ実行の場合、手動実行時に上書きをした時刻は適用されず、あくまでループ実行で定めた値が優先されます。もしワークフローで定義したカスタム変数とループ実行で定義したカスタム変数が重複している場合（紛らわしいのでそのようなワークフロー定義をそもそも作成しないとしたほうが良さそう）はこのような変数の展開順序について注意をしたうえで設定することをおすすめします。

他に細かい挙動をいくつか見てみる

ここまでで基本的な挙動については理解できたと思います。ここからはエッジケースにいくつか焦点を当ててどういう挙動となるのかを見ていきたいと思います。

転送設定のカスタムにカスタム変数が複数あり、一部を上書きしないときの挙動

先ほど取り上げた転送設定には $var_string$ $var_queued_date$ $var_execution_date$ の3つがありました。
カスタム変数の展開方法として「変数ごとに値を指定」という項目があり、その名の通り展開値を指定した文字列で展開するという機能になります。

手動実行画面で以下のように展開してみます。 $var_execution_date$ については指定せず実行してみます。

展開値は以下となりました。

実際に実行した日時ではなく空文字で展開されました。指定しなかった値は転送設定で指定した「実行時間」が展開されるのではなく空文字で上書きしたと解釈するのが良さそうです。

カスタム変数ループで一部の変数のみループで変数を定義した時にそれ以外の変数はどうなるのか

先ほど作成した転送設定で定義されている $var_string$ $var_queued_date$ $var_execution_date$ のうち $var_execution_date$ それぞれどれかを指定しないカスタム変数ループをそれぞれ実行してみて指定しなかった場合どのような値で実行されるのかを見ていきます。