ExcelTLにおけるジョブ実行の設計 ― Variables と Job Dependency
― 再利用・安全・保守性を高める設定の作り方と、複雑ワークフローを壊れにくく繋ぐ依存制御 ―
こんにちは、ExcelTL チームです。この記事では、日々のデータ連携や移行を「速く・安全に・繰り返し」回すための基盤要素である Variables（変数）とJob Dependency（ジョブ依存）の設計思想と実装方法について紹介します。
🎥 デモ動画（字幕が付く）
Part 1：Variables（変数）― ジョブを再利用可能・移植可能・安全にする要
1. 変数とは？なぜ使う？
変数は「一度だけ定義して、どこからでも参照できる名前付きの値」です。SQL、ファイルパス、接続設定、マッピング、通知テンプレートなどで繰り返し使う値をハードコードせずに参照化することで、 設定の再利用性と保守性を高めます。
-
再利用性：重複更新を排除し、1か所の変更で全体に反映。
-
環境移植：Dev / Stg / Prod で値を差し替えるだけで同じジョブが実行可能。
-
セキュリティ：パスワードやトークンを定義ファイルに残さない。
-
保守性：設定の単一情報源（Single Source of Truth）を確立。
2. ExcelTL における4種類の変数スコープ
-
一時調整：Job 変数
-
共有設定：Global 変数（複合属性はグループ化）
-
秘密・環境差：Environment 変数
-
時刻・文脈：System 変数
3. Environment 変数（秘密と環境差）
-
参照例：{!env.DB_HOST}, {!env.SF_PASSWORD}, {!env.S3_REGION}
-
命名：UPPER_SNAKE_CASE（DB_HOST, SF_TOKEN など）
-
用途：接続情報、HTTP ヘッダ、ファイルパス、S3 キー、SQL 内の値など
-
ポイント：ジョブ定義には書かず、OS や .env 側で管理する。
4. Global 変数（共有設定・認証ブロック）
-
定義方法：ジョブ定義に set_variable 行を並べ、同一 step_name に details.var_key / details.var_value を列挙。（属性の束として登録）
-
参照：
-
全体参照：{!global.postgres_auth}（ExcelTL 側で属性展開）
-
個別参照：{!global.postgres_auth.host}
-
-
運用：ExcelTL Studio の「変数一覧」で可視化・編集可能（新規はジョブ定義→実行で反映、編集・削除は DB 側で対応）。
💡整合性のコツ： 定義ファイルと DB を同期させたい場合は、Studio 側で該当グローバルを削除し、 ジョブ定義を再アップロード・実行することで再生成できる。
5. Job 変数（実行時限定パラメータ）
-
定義例（1 行＝1 変数）：
step_name=batch_size / step=set_variable / variable_scope=job / details.var_value=5
-
利用例（SQL）：
SELECT * FROM {!job.table_name} LIMIT {!job.batch_size} → 実行時に account / 5 に展開
-
注意点：
-
文字列・日付はクォート必須（例：WHERE created_at >= '{!job.start_date}'）
-
数値はクォート不要（例：LIMIT {!job.batch_size}）
-
つづりを正確に（batchsize ≠ batch_size）
-
6. System 変数（時間・境界・文脈）
-
点：{!system.TODAY}, {!system.NOW}, {!system.YESTERDAY}
-
境界：{!system.THIS_MONTH.start}, {!system.THIS_MONTH.end}
-
文脈：{!system.JOB_STATUS}, {!system.JOB_CREATED_AT}, {!system.JOB_LAST_RUN_AT}
例：SELECT * FROM sales_orders WHERE created_at BETWEEN '{!system.THIS_MONTH.start}' AND '{!system.THIS_MONTH.end}';
-
タイムゾーンの解決順：ETL_TZ → TIMEZONE → TZ → OS → 最後は UTC（標準化したい場合は、ETL_TZ=Asia/Tokyo のように明示的に指定する）。
Part 2：Job Dependency（ジョブ依存）― 大きな1本より、賢く繋ぐ
1. ねらい
巨大な1本のジョブではなく、論理的に分割した複数ジョブを条件付きで繋ぎ、壊れにくいパイプラインを構築することが目的です。
-
可観測性と再実行性：どの段階で失敗したかを特定し、該当ジョブのみ再実行可能。
-
再利用：共通の抽出ジョブを他パイプラインでも利用できる。
-
柔軟性：直列や並列の組み合わせ、条件による分岐制御が可能。
2. 基本語彙
-
Dependency（依存）：主ジョブが従ジョブの完了条件を満たすまで待機するルール。
-
Condition（条件）：
-
AFTER_SUCCESS … 従ジョブが成功したら起動
-
AFTER_FINISH … 成否を問わず完了したら起動
-
AFTER_FAIL … 失敗したら起動
-
WAIT_ALL … すべての依存が満たされたら起動
-
WAIT_ANY … いずれか一つが満たされたら起動
-
-
Trigger Type：SCHEDULE / DEPENDENCY / MANUAL
3. 代表的な設計パターン
-
直列構成（E→T→L）
-
extract：SCHEDULE（毎日 02:00）
-
transform：AFTER_SUCCESS(extract)
-
load：AFTER_SUCCESS(transform)
-
-
並列→集約
-
extract_A, extract_B を並列実行
-
unify は WAIT_ALL + AFTER_SUCCESS(extract_A, extract_B) で起動。
-
-
失敗時ハンドラ
-
AFTER_FAIL(target_job) で通知やリトライ準備ジョブを起動。
-
ビジネス要件に応じて AFTER_FINISH を使い冪等な片付けを先に回す設計も可
-
4. 設計のポイント
-
ジョブを小さく保ち、I/O 境界や責務で分離する。
-
共通ジョブは資産として再利用する。
-
WAIT_ALL + AFTER_SUCCESS を集約点の基本とする。
-
通知は AFTER_FAIL で制御する。
-
変数と併用し、Job 変数で日付窓や出力先を切り替える。
Part 3：Variables × Dependency の組み合わせ（実践例）
日次パイプライン例（部分再実行に強い構成）
-
job_extract（SCHEDULE 01:00）
SQL の日付窓：BETWEEN '{!system.YESTERDAY:datetime}' AND '{!system.END_OF_DAY}'
-
job_transform（AFTER_SUCCESS(job_extract)）
参照テーブル名：{!job.table_name}
-
job_load（AFTER_SUCCESS(job_transform)）
認証：{!global.postgres_auth}（環境差は {!env.*} で注入）
-
job_notify（AFTER_FAIL(job_extract | job_transform | job_load)）
チェックポイント
-
秘密情報や環境差分は Environment に退避する。
-
共通接続設定は Global にまとめる。
-
一時的な値は Job 変数で管理する。
-
時刻や境界条件は System 変数を利用する。
-
SQL のクォートルールを守る（文字列・日付＝クォート、数値＝非クォート）。
-
依存条件を明確に定義する（SUCCESS / FINISH / FAIL × ALL / ANY）。
-
通知や後処理を AFTER_FAIL / AFTER_FINISH で設定する。
まとめ
Variables は設定の再利用性と安全性を高め、Job Dependency は壊れにくく柔軟な実行制御を可能にします。Environment、Global、Job、System の役割分担と WAIT_ALL、WAIT_ANY、AFTER 条件を正しく設計することで、 ExcelTL のパイプラインは「小さく作り、強く繋ぐ」構成を実現できます。
関連記事
