Python UDFsの紹介¶

Pythonハンドラーの仕組み¶

ユーザーが UDF を呼び出すと、ユーザーは UDFの名前と引数をSnowflakeに渡します。Snowflakeは、関連付けられたハンドラーコード（存在する場合は引数付き）を呼び出して、 UDF のロジックを実行します。次に、ハンドラーメソッドは出力をSnowflakeに返し、Snowflakeはそれをクライアントに返します。

UDF に渡される行ごとに、 UDF はスカラー（つまり単一）値を返すか、テーブル関数として定義されている場合は行のセットを返します。

Python UDFsには、新しいコードと既存パッケージへの呼び出しの両方を含めることができるため柔軟性があり、コードの再利用も可能です。たとえば、Pythonでデータ分析コードをすでに持っている場合は、大抵Python UDF ハンドラーに組み込むことができます。

create or replace function addone(i int)
returns int
language python
RUNTIME_VERSION = '3.9'
handler = 'addone_py'
as
$$
def addone_py(i):
  return i+1
$$;

設計の考慮事項¶

役に立つハンドラーを設計するには、次の点に注意してください。

• 一般的な考慮事項。 UDFs およびプロシージャに共通する考慮事項については、 関数およびプロシージャの設計ガイドラインおよび制約 をご参照ください。

• SQL-Python型マッピング。 引数と戻り値を UDF と交換する場合、Snowflakeはハンドラー言語と SQL の間で変換します。ハンドラーコードのデータ型の選択に関する詳細については、 データ型の選択 をご参照ください。

• コードのパッケージ化。 CREATE FUNCTION ステートメントを使用してインラインで、またはステージ上でハンドラーコードを使用できるようにすることができます。相違の詳細については、 ハンドラーコードのインラインまたはステージ上での保持 をご参照ください。

• コードの最適化。 行全般で共有される状態をコードが処理する場合など、ハンドラーコードの最適化については、 スカラー UDFs における初期化の最適化とグローバル状態の制御 と スケールとパフォーマンスの最適化 をご参照ください。

• ベストプラクティス。 ベストプラクティスについては、 UDFs とプロシージャのセキュリティプラクティス をご参照ください。

ハンドラーコード¶

基本から詳細な例まで、次のトピックでは、Pythonで UDF ハンドラーを記述する方法について説明します。

• Pythonモジュールの定義。 UDF のロジックをPythonモジュールに記述します。Snowflakeがコードとやり取りする方法の詳細については、 モジュールの設計 をご参照ください。

• エラー処理。 Snowflakeがハンドラーによって生成されたエラーをどのように表示するかについては、 エラーの処理 をご参照ください。

• 表形式の戻り値。 UDF から表形式の値とスカラー（単一）値を返すことができます。表形式の値を返すハンドラーを記述する方法については、 Pythonでの UDTF の記述 をご参照ください。

• ログとイベントトレース。 ハンドラーコードの実行時にログとトレースデータを取得する方法については、 ロギング、トレース、メトリクス をご参照ください。

• 依存関係。 依存関係をステージにアップロードすると、実行時にコードで依存関係を利用できるようになります。詳細については、 コードで依存関係を利用できるようにする方法 をご参照ください。

• コード例 Pythonでのさまざまなハンドラーの例については、 Python UDF ハンドラーの例 をご参照ください。