Java UDFs の紹介¶

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

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

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

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

11.x
17.x（この機能のプレビューサポートは、すべてのアカウントで利用可能。）

注釈

Java UDF ハンドラーに関連した制限については、 Java UDF の制限事項をご参照ください。

このトピックの内容:

Javaハンドラーの仕組み¶

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

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

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

以下は、データフローの簡略図です。

例¶

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

create or replace function echo_varchar(x varchar)
returns varchar
language java
called on null input
handler='TestFunc.echoVarchar'
target_path='@~/testfunc.jar'
as
'class TestFunc {
  public static String echoVarchar(String x) {
    return x;
  }
}';

Copy

設計の考慮事項¶

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

一般的な考慮事項。 UDFs およびプロシージャに共通する考慮事項については、関数およびプロシージャの設計ガイドラインおよび制約をご参照ください。
SQL-Java型マッピング。 引数と戻り値を UDF と交換する場合、Snowflakeはハンドラー言語と SQL の間で変換します。ハンドラーコードのデータ型の選択に関する詳細については、データ型の選択をご参照ください。
コードのパッケージ化。 CREATE FUNCTION ステートメントを使用してインラインで、または JAR 内のコンパイル済みコードとしてステージ上でハンドラーコードを使用できるようにすることができます。相違の詳細については、ハンドラーコードのインラインまたはステージ上での保持をご参照ください。
コードの最適化。 行全般で共有される状態をコードが処理する場合など、ハンドラーコードの最適化については、スカラー UDFs における初期化の最適化とグローバル状態の制御をご参照ください。
ベストプラクティス。 ベストプラクティスについては、ベストプラクティスに準拠すると UDFs とプロシージャのセキュリティプラクティスをご参照ください。

ハンドラーコード¶

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

Javaクラスの定義。 UDF のロジックをJavaクラスに記述します。Snowflakeがコードとやり取りする方法の詳細については、クラスの設計をご参照ください。
エラー処理。 Snowflakeがハンドラーによって生成されたエラーをどのように表示するかについては、エラーの処理をご参照ください。
表形式の戻り値。 UDF から表形式の値とスカラー（単一）値を返すことができます。表形式の値を返すハンドラーを記述する方法については、表形式のJava UDFs （UDTFs）をご参照ください。
ログとイベントトレース。 ハンドラーコードの実行時にログとトレースデータを取得する方法については、ロギング、トレース、メトリクスをご参照ください。
依存関係。 依存関係をステージにアップロードすると、実行時にコードで依存関係を利用できるようになります。詳細については、コードで依存関係を利用できるようにする方法をご参照ください。
ハンドラーファイルの編成。 コンパイルされたハンドラーコードを JAR ファイルにパッケージ化する場合は、ファイルの整理の提案に従ってコードを編成およびビルドします。
コード例 Javaでのさまざまなハンドラーの例については、 Java UDF ハンドラーの例をご参照ください。