Pipeline Builder で Python 関数を使用する

Pipeline Builder は、Java と Python の両方のユーザー定義関数（UDF）に対応しています。このページでは Python UDF について説明します。代わりに Java を使用する場合は、Java UDF の詳しくはこちらをご覧ください。

前提条件

このガイドでは、Python 関数をすでに作成し、公開していることを前提としています。チュートリアルについては、Python 関数のはじめにのドキュメントをご覧ください。

アーキテクチャー

Python 関数は、Pipeline Builder パイプライン内でサイドカーコンテナとして実行されます。そのため、関数をデプロイする必要がなく、パイプラインの規模に応じて動的にスケーリングします。埋め込み関数は、Pipeline Builder の他のトランスフォームと同様にプレビューできます。

Python 関数によるデータ処理の仕組み

Pipeline Builder で Python 関数をユーザー定義関数（UDF）として使用すると、関数は行ごとに 1 回実行されます。Pipeline Builder は、テーブル全体、pandas DataFrame、Spark DataFrame を関数に渡すことはありません。代わりに、1 個以上の入力列を関数のパラメーターにマッピングすると、Pipeline Builder が各行のセル値をパラメーターの引数として渡し、行ごとに関数を呼び出します。

関数が返す値は出力テーブルの新しい列となり、行ごとに 1 個の値が生成されます。そのため、Python UDF は DataFrame ではなく、str、int、float、bool、datetime などのスカラー（単一値）データ型を返します。戻り値として使用できる DataFrame データ型はありません。Pipeline Builder が各行の戻り値から組み立てる列が、結果のテーブル形式の出力_そのもの_です。

次の例では、2 個の列を入力として受け取り、行ごとに 1 個の str 値を返します。Pipeline Builder は、この値を新しい列に書き込みます。

Copied!1
2
3
4
5
from functions.api import function

@function
def full_name(first_name: str, last_name: str) -> str:
    return f"{first_name} {last_name}"

トランスフォームを設定する際に、first_name パラメーターと last_name パラメーターを対応する入力列にマッピングします。トランスフォームが実行されると、Pipeline Builder は行ごとに full_name を評価し、返された文字列を新しい出力列に書き込みます。

対応する入力データ型と出力タイプ、およびそれらに相当する Python のデータ型の完全な一覧については、データ型リファレンスをご覧ください。このリファレンスに記載されているオントロジーのデータ型は、Pipeline Builder では利用できません。これらのデータ型を受け取る、または返す関数はインポートできず、利用可能な関数の一覧にも表示されません。

構造体を返す

単一の関数から複数の関連する値を返すには、スカラーではなくカスタム型（構造体）を返します。Pipeline Builder は、カスタム型の各属性に対応するフィールドを持つ単一の構造体列として戻り値を追加します。その後、Get struct field トランスフォームを使用して個々のフィールドを抽出できます。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
from dataclasses import dataclass
from functions.api import function, Double

@dataclass
class Stats:
    total: Double
    average: Double

@function
def compute_stats(a: Double, b: Double) -> Stats:
    total = a + b
    return Stats(total=total, average=total / 2)

Pipeline Builder パイプラインで関数を使用する

以下の手順に従って、パイプラインで Python 関数を準備し、設定します。

Python 関数を使用する Pipeline Builder パイプラインを開きます。

次の 2 つの方法のいずれかで、UDF を Pipeline Builder にインポートします。
- グラフ表示から：
  1. パイプライングラフの上部にある変数・関数を選択し、ユーザー定義関数を選択します。
    
    2. UDF をインポートを選択し、利用可能な関数を検索して、使用する関数を見つけます 3. 関数名の横にある追加を選択します。関数にインポートされましたタグが表示されます。
    
    4. インポートダイアログを閉じ、Pipeline Builder グラフ上で関数を使用する場所のトランスフォームを選択します。 5. トランスフォームの一覧で、左側の **UDF（ユーザー定義関数）**タブを見つけて、インポートした関数を表示します。
- トランスフォームピッカーを使用する：
  1. Pipeline Builder グラフ上でトランスフォームを選択します。
  2. インポートする UDF の名前を入力します。
    
    3. インポートされていない UDF を検索を選択します。 4. 使用する UDF にカーソルを合わせ、インポートを選択します。
入力列とパラメーターを指定してトランスフォームの定義を入力し、適用を選択します。

Pipeline Builder で設定済みの Python 関数トランスフォーム。

Pipeline Builder グラフに Python 関数が表示され、関数の出力をプレビューできるようになります。

Pipeline Builder での外部 API 呼び出し

Pipeline Builder から外部システムへの API 呼び出しを行うには、外部システムへのアクセス権を持つ Python 関数を公開します。これにより、外部システムと通信するロジックを記述し、パイプラインの一部として使用できます。

Pipeline Builder でユーザー定義関数（UDF）として使用するには、関数で使用するすべてのソースを、パイプラインにインポートできるように設定する必要があります。この設定を行うには、Data Connection でソースに移動し、接続設定 > コードインポート設定タブに移動します。

ソースをパイプラインにインポートできるようにする。

ソースでこのオプションを有効にし、Python 関数を公開すると、他の Python 関数と同様にパイプラインで使用できるようになります。

Pipeline Builder でのオントロジーへのアクセス

Pipeline Builder の UDF は、FoundryClient() またはオントロジー SDK（OSDK）を介したオントロジーへの直接アクセスに対応していません。UDF 内で FoundryClient() をインスタンス化し、オントロジーにアクセスすると、EnvironmentNotConfigured エラーが返されます。この制限は、データのマーキングが外れたり、ビルド間でデータが漏えいしたりすることを防ぐためのものです。

Pipeline Builder の UDF からオントロジーのデータにアクセスするには、次の方法を検討してください。

外部ソースを使用する： オントロジーのクエリを実行する Python 関数用の外部ソースを作成し、そのソースを Pipeline Builder の UDF にインポートします。これにより、UDF のコンテキストでオントロジーに直接クエリを実行する場合に生じる認証や権限の問題を回避できます。ソースを設定するには、Data Connection でそのソースに移動し、上記の説明に従って接続設定 > コードインポート設定を有効にします。
オントロジーを利用したデータセットを結合する： ユースケースで許容される場合は、関連するオントロジーを利用したデータを別のデータセットで管理し、パイプラインに結合します。これにより、オントロジー API の呼び出しを回避でき、重複排除や存在確認を行えます。

←

PREVIOUSステージングされた書き込み

NEXTWorkshopでPython関数を使用する

→