Python UDFsの紹介

Pythonでユーザー定義関数(UDF)のハンドラーを作成できます。このセクションのトピックでは、Pythonハンドラーを設計および記述する方法について説明します。例もあります。

UDF ハンドラーを記述できる言語のリストを含む UDFs の概要については、 ユーザー定義関数の概要 をご参照ください。

ハンドラーを作成した後、 SQL で UDF を作成します。SQL を使用して UDF を作成または呼び出す方法については、 UDF の作成 または UDF の呼び出し をご参照ください。

Snowflakeは現在、次のバージョンのPythonでJava UDFs の記述をサポートしています。

  • 3.8

  • 3.9

  • 3.10

  • 3.11

注釈

Python UDF ハンドラーに関連する制限については、 Python UDF の制限 をご参照ください。

このトピックの内容:

Pythonハンドラーの仕組み

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

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

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

次の例のコードは、ハンドラーメソッド addone_py を使用して addone という名前の UDF を作成します。Python の引数と戻り値の型は、 SQL-Pythonデータ型マッピング で説明されているマッピングに従って、Snowflakeによって SQL との間で変換されます。

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

設計の考慮事項

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

ハンドラーコード

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

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

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

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

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

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

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