マクロを作成する

マクロは、入出力コントラクトを宣言した、再利用可能な高度な（DAG）ワークフローです。別のワークフローから Macro Run ステップまたは Macro Concurrent ステップでマクロを呼び出します。呼び出しごとに専用の分離されたスクラッチスキーマで実行されるため、同じマクロを複数の親ワークフローや複数のドライバー行から同時に呼び出しても、実行同士が衝突しません。

繰り返し実行できるパラメーター化されたデータ変換（たとえば「1つの地域の1か月分の売上データを処理する」）があり、それを月ごと、地域ごと、またはその両方でドライバーワークフローから呼び出したい場合は、マクロを使用します。呼び出し元は、テーブルと変数をマクロで宣言された入力ポートにバインドします。マクロが完了すると、宣言された出力テーブルが呼び出し元側の宛先にコピーされます。

手順

マクロにしたいワークフローを含むプロジェクトを開きます。
ワークフロータブに切り替えて、ワークフローの行を選択します。
右側のワークフローの詳細パネルで、ワークフロータイプが高度になっていることを確認します。標準の場合は、先に高度なワークフローに変換アクションを使用してください。
ワークフローの詳細パネルのマクロセクションで、マクロに変換… をクリックし、ダイアログで確定します。ワークフローがマクロモードに切り替わり、ポートエディターが表示されます。
ポートを追加をクリックして、マクロが受け取る入力、または生成する出力を宣言します。各ポートには次を指定します。
- 名前 — 呼び出し元がこのポートにバインドするために使用する短い識別子（例：month、region_sales）。
- 方向 — 入力（呼び出し元がこの値またはテーブルを提供します）または出力（マクロがこれを生成し、呼び出し元が受け取ります）。
- 種類 — データテーブルの場合はテーブル、単一の値（string / int / float / bool / date）の場合はスカラー、階層ディメンションへの参照の場合はディメンション。
- 必須 — このポートをバインドしなくてもマクロを実行できる場合は、チェックを外します。
- メモ — このポートが何を表すかについての短い注記。呼び出し元側のバインディングフォームで作成者に表示されます。
ポートを保存をクリックします。

これでワークフローはマクロになりました。別のワークフローに Macro Run ステップを追加する作成者には、宣言したポートが表示され、名前でバインドできます。

各ポートは、マクロのコントラクトにおける、名前と型を持つ1つのスロットです。呼び出し元は名前でポートにバインドします。入力はコピーして取り込まれ、出力はコピーして書き戻されます。

マクロを呼び出す

呼び出し元のワークフローで次の操作を行います。

マクロ: 実行ステップを追加します。
実行するマクロで、プロジェクトとマクロのワークフローを選択します。
入力ポートのバインド — マクロが宣言した入力ポートごとに、バインドを追加します。
- テーブルポートには、呼び出し元側のソーステーブルを指定します。必要に応じて、列のサブセットを選択し、フィルター（マクロのスカラー入力変数を参照する WHERE 句）を追加すると、必要な部分だけがマクロの実行スキーマに実体化されます。
- スカラー / ディメンションポートには、値（多くの場合、呼び出し元のワークフロー変数）を指定します。テーブルの入力フィルターから参照できるように、テーブルのコピー取り込みより前に設定します。
出力ポートのバインド — マクロが生成する出力ポートごとに、呼び出し元側の宛先テーブルを指定します（存在しない場合は、その場で作成されます）。
ステップを保存します。

親ワークフローが実行され、Macro Run ステップに到達すると、ランナーは次の処理を行います。

このマクロ呼び出し用に、新しい run_id を発行します。
プロジェクトのカタログに、実行ごとのスクラッチスキーマ（macrorun_<run_id>）を作成します。
バインドされた入力テーブルをスクラッチスキーマにコピーします（コピー取り込み時に列の射影とフィルターが適用されるため、フィルターがプッシュダウンされます）。
バインドされたスカラー / ディメンションの入力変数を、マクロの実行スコープの変数オーバーレイに設定します。
マクロのステップをインプロセスで実行します。マクロ内のすべての SQL ステップは、プロジェクトスキーマではなくスクラッチスキーマに対して読み書きします。
宣言された出力テーブルを、呼び出し元の宛先にコピーして書き戻します。
スクラッチスキーマを削除します（マクロ内のステップが失敗した場合でも、常に削除されます）。

呼び出しごとに、新しい run_id と専用のスクラッチスキーマが割り当てられます。ステップはそのスキーマに対してのみ読み書きし、実行が終了すると（成功、エラー、停止のいずれでも）スキーマは削除されます。

呼び出しごとに専用のスクラッチスキーマがあるため、同じマクロへの2つの同時呼び出し（ループ、ファンアウト、独立したワークフローからのもの）が、中間テーブル名で衝突することはありません。

ドライバー行ごとにマクロを実行する

1つの呼び出し元テーブルで、独立した多数のマクロ呼び出しを駆動したい場合は、マクロ: 並行実行を使用します。

マクロ: 並行実行ステップを追加します。
ドライバーで、呼び出し元側のドライバーテーブルを選択し、同時実行数に、同時に実行する子マクロ呼び出しの最大数を設定します。
テーブルデータの選択で、各子呼び出しが必要とするドライバーテーブルの列をマッピングします。
ドライバーフィルターで、必要に応じて、処理するドライバー行を制限します。
マクロで、マクロのワークフローを選択します。
入力バインドで、ドライバー列の値をマクロのスカラー変数またはディメンション変数にバインドし、呼び出し元側のテーブルをマクロのテーブルポートにバインドします。
出力バインドで、マクロの出力ポートを呼び出し元側の宛先テーブルにマッピングします。

選択された各ドライバー行には、個別の run_id とスクラッチスキーマが割り当てられます。親ステップを停止すると、アクティブなすべての子呼び出しが停止し、それらの実行スキーマが削除されます。

ドライバー行ごとに1回の呼び出しが、それぞれ専用のスクラッチスキーマで実行されるため、中間テーブルが衝突することはありません。同時実行数は同時に実行される数を制限し、各行は独自の results_{region} テーブルに書き込みます。

マクロを元に戻す

ワークフローの詳細パネルで高度なワークフローに戻す… をクリックすると、いつでもマクロのフラグを解除できます。ワークフローは通常の高度なワークフローに戻り、そのワークフローを参照している呼び出し元側の Macro Run ステップは、実行時に「マクロではありません」というエラーで失敗します。宣言したポートはレコードに残るため、後で再度変換すると復元されます。

制限事項（v1）

テーブルの読み取りと書き込みは呼び出しのスクラッチスキーマに分離されるため、マクロにはテーブル変換、インポート、エクスポートを含めることができます。ディメンションはプロジェクト全体にわたるグローバルな状態であるため、ディメンションのインポートとディメンションを更新するステップは使用できません。ドキュメント操作やエージェント呼び出しなど、その他のテーブル以外の副作用を持つステップは、v1 ではマクロで安全に使用できません。
マクロは、呼び出し元と同じプロジェクトに存在する必要があります。プロジェクトをまたぐマクロは、まだサポートされていません。
Macro Run ステップは、ワークフローの実行ステップ、Workflow Loop ステップ、または条件付きのワークフローの実行ステップから呼び出すことはできません。これらのステップは分離されずに実行され、実行ごとのスキーマのコントラクトを壊してしまうためです。代わりに、呼び出し元で Macro Run ステップを使用してください。

次のステップ

Macro Run ステップのリファレンス — 呼び出し側ステップのフィールドごとのリファレンスです。
Macro Concurrent ステップのリファレンス — ドライバーテーブルの行ごとに、マクロ呼び出しを1回ずつ実行します。
ワークフローの実行ステップ — 呼び出しごとの分離を必要としないサブワークフロー向けです。