Macro Run ステップ

説明

マクロワークフローを、実行ごとに分離されたサブ呼び出しとして実行します。ワークフローの実行とは異なり、Macro Run ステップの各呼び出しには次の特徴があります。

• 新しい一意の run_id が割り当てられます。
• プロジェクトのカタログ内にある専用の一時スクラッチスキーマ（macrorun_<run_id>）で実行されます。
• コピーイン時に、呼び出し元側のテーブルと変数をマクロで宣言された入力ポートにバインドします。
• 成功時に、マクロで宣言された出力テーブルを呼び出し元側の宛先にコピーして戻します。
• 呼び出しが終了したとき（成功、エラー、停止のいずれでも）、必ずスクラッチスキーマを削除します。

この分離により、同じマクロを同時に呼び出しても安全です。親ループから、同時に実行される独立したワークフローから、あるいは別のマクロから再帰的に呼び出しても、実行間で中間テーブル名が衝突しません。

対象のワークフローは、マクロとしてフラグが設定されている必要があります。マクロ以外のワークフローを対象とする Macro Run ステップは、わかりやすいエラーメッセージとともに失敗します。逆に、ワークフローの実行ステップや Workflow Loop ステップは、マクロを対象にできません（これらのステップには、実行ごとの分離ライフサイクルがないためです）。

実行するマクロ

• プロジェクト — マクロを含むプロジェクトです。v1では、呼び出し元と同じプロジェクトである必要があります。
• マクロ — 呼び出すマクロワークフローです。選択すると、マクロで宣言された入力ポートと出力ポートが、下のバインディング一覧に反映されます。

入力ポートバインディング

マクロで宣言された入力ポートごとにバインディングを追加します。バインディングは2つのパスで処理されます。最初にスカラー／ディメンションの入力（マクロの実行スコープの変数オーバーレイに書き込まれます）、次にテーブルの入力が処理されるため、テーブル入力のフィルターからスカラー入力を参照できます。

テーブル入力ポート:

• ソース — 呼び出し元側のテーブル（名前またはID）です。その内容は、ポート名でマクロのスクラッチスキーマにコピーされます。
• 列 — 任意の列プロジェクションです。サブセットを選択し、必要に応じて名前を変更できます（source → target）。列は引用符で囲まれてコピーイン時に適用されるため、プロジェクションされた列だけが実体化されます。
• フィルター — コピーイン時に適用する任意の WHERE 句です。マクロの入力変数を名前で参照できます（上記のスカラーバインディングから解決されます）。たとえば、month = {month} を指定すると、複数年にわたるテーブルから1か月分だけをコピーインするよう制限できます。

スカラー／ディメンション入力ポート:

• 変数 — 設定するマクロ側の変数名です（マクロで宣言されたポートと一致します）。
• 値 — バインドする値です。リテラル、または呼び出し元側の変数参照のいずれかを指定します（後者は、サブ呼び出しのオーバーレイに書き込まれる前に、呼び出し元の変数に対して解決されます）。

出力ポートバインディング

マクロで宣言された出力ポートごとに、呼び出し元側の宛先テーブルを指すバインディングを追加します。宛先がまだ存在しない場合は、その場で作成されます。出力のコピーアウトには次の特徴があります。

• マクロが正常に完了した後（状態が done または warn）に行われます。
• マクロが実行中に手動で停止された場合（stop 状態）はスキップされます。そうしないと、部分的な出力が呼び出し元の永続スキーマに黙って書き込まれてしまうためです。
• 任意の列プロジェクションは、入力バインディングの場合と同じように動作します。

失敗時の動作

マクロの結果	呼び出し元側への影響
done / warn	出力テーブルが呼び出し元の宛先にコピーされ、スクラッチスキーマが削除されます。
stop（手動停止）	コピーアウトはスキップされ、スクラッチスキーマが削除され、呼び出し元に警告が記録されます。
実行中のエラー	Macro Run ステップがエラーになり、スクラッチスキーマが削除され、出力は書き込まれません。

マクロのワークフローが失敗した場合、Macro Run ステップのログにはマクロ自身のエラーメッセージ（「Child workflow run failed:」に続くメッセージ）が表示されるため、マクロの実行を開いて確認しなくても、何を修正すればよいかがわかります。

スクラッチスキーマは常に finally ブロックで回収されるため、失敗または停止したマクロが中間テーブルをプロジェクトスキーマに残すことはありません。

例

例はまだありません…

関連項目

• Create a Macro — ワークフローをマクロとして宣言し、そのポートコントラクトを定義します。
• ワークフローの実行 — 分離されないサブワークフローの呼び出し元です（マクロは対象にできません）。