notebookutils.udf モジュールには、ノートブック コードとユーザー データ関数 (UDF) 項目を統合するためのユーティリティが用意されています。 同じワークスペース内または異なるワークスペース間で UDF 項目から関数にアクセスし、必要に応じてそれらの関数を呼び出すことができます。 UDF 項目は、コードの再利用性、一元的なメンテナンス、チームコラボレーションを促進します。
UDF ユーティリティを使用して、次の手順を実行します。
- 関数の取得 – UDF 項目から名前で関数にアクセスします。
- ワークスペース間アクセス – 他のワークスペース の UDF 項目の関数を使用します。
- 関数の検出 – 使用可能な関数とそのシグネチャを検査します。
- 柔軟な呼び出し – 言語に適したパラメーターを使用して関数を呼び出します。
注
関数を取得するには、ターゲット ワークスペース内の UDF 項目への読み取りアクセス権が必要です。 UDF 関数からの例外は、呼び出し元のノートブックに反映されます。
次の表に、使用可能な UDF メソッドの一覧を示します。
| メソッド | 署名 | 説明 |
|---|---|---|
getFunctions |
getFunctions(udf: String, workspaceId: String = ""): UDF |
アーティファクト ID または名前を使用して、UDF 項目からすべての関数を取得します。 呼び出し可能な関数属性を持つオブジェクトを返します。 |
返されるオブジェクトは、次のプロパティを公開します。
| 財産 | タイプ | 説明 |
|---|---|---|
functionDetails |
一覧 | 関数メタデータ ディクショナリの一覧。 各ディクショナリには、 Name (関数名)、 Description (関数の説明)、 Parameters (パラメーター定義の一覧)、 FunctionReturnType (戻り値の型)、および DataSourceConnections (使用されるデータ ソース接続) が含まれます。 |
itemDetails |
辞書 | キー ( Id (アーティファクト ID)、 Name (項目名)、 WorkspaceId (ワークスペース ID)、および CapacityId (容量 ID) を含む UDF 項目メタデータのディクショナリ。 |
<functionName> |
Callable | UDF 項目内の各関数は、返されたオブジェクトの呼び出し可能なメソッドになります。
myFunctions.functionName(...)を使用して呼び出します。 |
ヒント
UDF 関数を 1 回取得し、ラッパー オブジェクトをキャッシュします。 ループ内で getFunctions() を繰り返し呼び出すのを避け、代わりに結果をキャッシュしてオーバーヘッドを最小限に抑えます。
UDF から関数を取得する
notebookutils.udf.getFunctions()を使用して、UDF 項目からすべての関数を取得します。 必要に応じて、ワークスペース間アクセスのワークスペース ID を指定できます。
# Get functions from a UDF item in the current workspace
myFunctions = notebookutils.udf.getFunctions('UDFItemName')
# Get functions from a UDF item in another workspace
myFunctions = notebookutils.udf.getFunctions('UDFItemName', 'workspaceId')
関数を呼び出す
UDF 項目から関数を取得した後、名前で呼び出します。 Python では、位置指定パラメーターと名前付きパラメーターがサポートされています。 Scala と R の例では、位置パラメーターを使用します。
# Positional parameters
myFunctions.functionName('value1', 'value2')
# Named parameters (recommended for clarity)
myFunctions.functionName(parameter1='value1', parameter2='value2')
詳細を表示する
UDF 項目のメタデータと関数シグネチャをプログラムで調べることができます。
UDF 項目の詳細を表示する
関数の詳細を表示する
ヒント
新しい UDF 項目を使用する場合は、常に functionDetails を検査します。 これは、呼び出し前に使用可能な関数とその予期されるパラメーター型を確認するのに役立ちます。
エラー処理
UDF 呼び出しを言語に適したエラー処理でラップして、不足している関数または予期しないパラメーター型を適切に管理します。 関数を呼び出す前に、必ず UDF 項目に関数が存在することを確認してください。
import json
try:
validators = notebookutils.udf.getFunctions('DataValidators')
# Check if function exists before calling
functions_info = json.loads(validators.functionDetails)
function_names = [f['Name'] for f in functions_info]
if 'validateSchema' in function_names:
is_valid = validators.validateSchema(
schema='sales_schema',
data_path='Files/data/sales.csv'
)
print(f"Schema validation: {'passed' if is_valid else 'failed'}")
else:
print("validateSchema function not available in this UDF item")
print(f"Available functions: {', '.join(function_names)}")
except AttributeError as e:
print(f"Function not found: {e}")
except TypeError as e:
print(f"Parameter type mismatch: {e}")
except Exception as e:
print(f"Error invoking UDF: {e}")
データ パイプラインで UDF 関数を使用する
UDF 関数を作成して、再利用可能な ETL ステップを作成できます。
etl_functions = notebookutils.udf.getFunctions('ETLUtilities')
df = spark.read.csv('Files/raw/sales.csv', header=True)
cleaned_df = etl_functions.removeOutliers(df, columns=['amount'])
enriched_df = etl_functions.addCalculatedColumns(cleaned_df)
validated_df = etl_functions.validateAndFilter(enriched_df)
validated_df.write.mode('overwrite').parquet('Files/processed/sales.parquet')
print("ETL pipeline completed using UDF functions")
Important
UDF 呼び出しにはオーバーヘッドがあります。 同じパラメーターで同じ関数を繰り返し呼び出す場合は、結果をキャッシュすることを検討してください。 可能な場合は、タイト ループで UDF 関数を呼び出さないようにします。