作業を再利用する: 変数、マクロ、UDF

約30分 · 変数、マクロ、ユーザー定義トランスフォーム

最初に作成するワークフローでは、通常、すべてがハードコードされています。1つのリージョン、1か月分、1つのテーブル名です。それは1回だけなら機能します。このチュートリアルは、ユーザーからパワーユーザーへの飛躍です。一度きりのパイプラインを、任意のリージョンに向けられ、どこからでも呼び出せ、独自の Python で拡張できる資産に変えます。

この作業を担うのは3つのツールで、積み重ねて使用します。

ツール	取り除くもの	使いどき
ワークフロー変数	ステップのあちこちに散らばったハードコードされた値	同じ値（月、リージョン、しきい値）が複数のステップに登場するとき
マクロ	コピー＆ペーストされたステップのシーケンス	パラメーター化されたシーケンスを、リージョンごと、月ごと、ドライバー行ごとなど何度も実行するとき
User Defined Transform（UDF）	標準のステップでは対応できない部分	必要なことを実現する標準のトランスフォーム（またはその組み合わせ）がなく、Python で記述できるとき

すべてのワークフローで3つとも必要なわけではありません。それぞれが解消する課題が実際に現れたときに、1つずつ追加してください。

ツールは後のものほど、より広い範囲をカバーします。必要になったときに追加してください。先回りして追加する必要はありません。

前提条件

PlaidCloud ワークスペースと、すでに構築したワークフローがあるプロジェクト。できれば、データのロード、変換、公開で作成したものを使用してください。
ワークフローのステップの追加と実行に慣れていること。初めての場合は、まずワークフローガイドから始めてください。

ステップ1: ワークフロー変数でパラメーター化する

変数とは、ステップがリテラルの代わりに読み取る、名前付きの値です。1か所で変更すれば、その変数を参照するすべてのステップに反映されます。PlaidCloud の変数には2つのスコープがあります。プロジェクト変数はプロジェクト内のすべてのワークフローで共有され、ワークフロー変数は1つのワークフローに属し、そのステップ間で情報を受け渡すのに適しています。

ワークフローの階層で、変数アイコンをクリックして変数テーブルを開きます。
変数を追加します。target_region のような分かりやすい名前を付け、現在の値（例: East）を設定します。
その値を現在ハードコードしているステップで、リテラルを入力する代わりに変数を参照します。
ステップを実行します。次に、テーブルで変数の値を変更して再度実行します。ステップ自体を編集しなくても、同じステップが別のスライスを処理します。

変数テーブルでは、現在の値の確認、編集、不要になった変数の削除も行えます。

プロジェクトスコープとワークフロースコープ。 複数のワークフローが同じ設定を必要とする場合はプロジェクトスコープに、1つのワークフローのステップに限定される場合はワークフロースコープに値を置きます。迷ったときは、範囲の狭いワークフロー変数から始め、2つ目のワークフローで必要になった時点でプロジェクトに昇格させてください。

変数がどこに存在し、どのように管理するかの全体像は、ワークフロー変数を管理するを参照してください。

ステップ2: シーケンスをマクロとしてパッケージ化する

変数がパラメーター化するのは1つの値です。マクロは、ステップのシーケンス全体をパラメーター化します。入力と出力の契約が宣言された、再利用可能な高度な（DAG）ワークフローであり、「1つのリージョンの1か月分の売上を処理する」といったものを、月ごと、リージョンごと、またはその両方で、別のワークフローから呼び出します。各呼び出しは独立した専用のスクラッチスキーマで実行されるため、同じマクロを同時に何度実行しても、実行どうしが衝突しません。

マクロは高度なワークフロー専用の機能です。 先にワークフローを高度なワークフローに変換してください。マクロ内のステップはマクロセーフである必要があります。テーブルのトランスフォーム、インポート、エクスポート、実行スコープの変数ステップ、ネストされたマクロ呼び出しは使用できますが、ディメンションのインポートとディメンションを更新するステップは、ディメンションがプロジェクト全体の状態であるため拒否されます。

ワークフローをマクロに変換する

プロジェクトを開き、ワークフロータブで、再利用したいワークフローを選択します。
ワークフローの詳細パネルで、ワークフロータイプが高度であることを確認します。標準の場合は、先に高度なワークフローに変換を使用してください。
マクロセクションで、マクロに変換… ボタンをクリックして確定します。ポートエディターが表示されます。
マクロが受け取る、または生成する入力と出力のそれぞれについて、ポートを追加をクリックします。各ポートに次の項目を設定します。
- 名前 — 呼び出し側がバインドする識別子（例: month、region_sales）。
- 方向 — 入力（呼び出し側が指定する）または出力（マクロが生成する）。
- 種類 — テーブル、スカラー（単一の文字列 / 整数 / 浮動小数点数 / ブール値 / 日付）、またはディメンション。
- 必須 — このポートをバインドしなくてもマクロを実行できる場合は、オフにします。
- メモ — 呼び出し側のバインディングフォームで作成者に表示される短いメモ。
ポートを保存をクリックします。

別のワークフローから呼び出す

呼び出し側のワークフローで、マクロ: 実行ステップを追加します。
実行するマクロで、プロジェクトとマクロのワークフローを選択します。
Input Port Bindings — 各入力ポートをバインドします。スカラーポートとディメンションポートには、呼び出し側のワークフロー変数（ステップ1で作成したもの）を指定できることが多く、テーブルポートには、必要に応じて列の射影とフィルターを指定したソーステーブルを指定します。
Output Port Bindings — 各出力ポートを、呼び出し側の出力先テーブルに向けます。
ステップを保存して、ワークフローを実行します。

ドライバーテーブルの行ごとに1回ずつマクロを実行する場合（たとえば1行につき1リージョン）は、代わりにマクロ: 並行実行ステップを使用し、同時実行数で同時に実行する数の上限を設定します。各行が独自のスクラッチスキーマと出力先を持ちます。

実行の分離のライフサイクルを含む、フィールドごとの詳しい手順は、マクロを作成するを参照してください。

ステップ3: ユーザー定義トランスフォームでカスタムロジックを追加する

標準のトランスフォームはほとんどのケースをカバーしており、パフォーマンスも継続的にチューニングされているため、まずはそちらを使用してください。しかし、必要なことを実現する標準のステップが（単独でも組み合わせても）ない場合は、User Defined Transform（UDF） を使うと、標準の Python に切り替えられ、PlaidCloud API 全体と、Pandas、NumPy、SciPy などのパッケージを利用できます。

UDF の作成方法は2つあります。PlaidCloud で直接記述して管理する方法と、接続された Git リポジトリ内のファイルを指定する方法です（後者では、次回の実行時に変更が自動的に反映され、ブランチとタグでリリースを管理できます）。

関数を作成する

ワークフローを開き、ユーザー定義タブを選択して、Add User Defined Function をクリックします。
UDF に ID を指定し、関数ロジックの編集アイコンをクリックしてエディターを開きます。

ロジックを記述します。最小限の UDF は、接続し、ソースを読み取り、Pandas で変換して、ターゲットを保存します。

from plaidcloud.utilities.connect import PlaidConnection
from plaidcloud.utilities import frame_manager as fm

conn = PlaidConnection()

# Read a table configured as a source on the step
source = conn.udf.source_by_name('sales_clean')
df = conn.get_data(source)

# Custom logic the standard steps don't cover
df['margin_band'] = df['margin'].apply(
    lambda m: 'high' if m > 0.4 else 'low'
)

# Write to a table configured as a target on the step.
# Sources are read by their configured name; fm.save writes to a table PATH (leading slash).
fm.save(df, name='/output/sales_scored', append=False)

ワークフローに追加する

Analyze Steps タブで、標準のトランスフォームと同じように、必要な場所に User Defined Transform ステップを追加します。
ステップの設定で、種類を選択します。UDFの分析（保存された関数）または外部ソースコードリポジトリ（Git。その場合は接続、ブランチ、ファイルパスを選択します）。
UDF が使用するソーステーブルとターゲットテーブルを定義します。コード内でテーブルに直接アクセスすることもできますが、ここで宣言することで依存関係が登録され、conn.udf.source_by_name(...) / target_by_name(...) を通じて利用できるようになります。
必要に応じて、その他の変数にステップ固有の値を追加します。これらは conn.udf.variable_by_name(...) で読み取れます。

テーブルは、コード内だけでなく設定でも宣言してください。 テーブルを直接読み取る UDF も実行はできますが、PlaidCloud はそのテーブルが依存関係であることを把握できないため、リネージと実行順序に反映されません。ステップの設定にソースとターゲットを列挙しておくことで、依存関係グラフを正確に保てます。

ステップ1のプロジェクト変数とワークフロー変数も、conn.analyze.workflow.variable_values(...) と conn.analyze.project.variable_values(...) を通じて UDF の中から参照できます。同じパラメーターで、標準のステップとカスタムコードの両方を動かせます。API の完全な例は、User Defined Transform のリファレンスにあります。

これが、ユーザーからパワーユーザーへの飛躍です。 一度きりのパイプラインを、再利用可能な資産に変えました。変数で向け先を変えられる値、マクロとしてどこからでも呼び出せるシーケンス全体、そして標準のステップでは届かない部分に対応するカスタム Python です。

次のステップ

ワークフロー変数を管理する — プロジェクトスコープとワークフロースコープ、および変数テーブル。
マクロを作成する — ポート、実行の分離、行ごとに1つのマクロを実行する方法。
User Defined Transform のリファレンス — カスタム Python 向けの API 全体。
ワークフローガイド — 条件、ループ、そしてオーケストレーション層が提供するその他すべての機能。
SQL でデータを変換する — 答えがコードではなくクエリである場合のための、姉妹チュートリアル。