Java UDFs の設計¶

パラメーターと戻り値型の SQL-Javaデータ型のマッピング¶

次のテーブルは、 SQL とJavaの間の型マッピングを示しています。これらのマッピングは通常、Java UDF に渡される引数と UDF から返される値の両方に適用されます。ただし、脚注に記載されているいくつかの例外があります。

一部の SQL データ型（例: NUMBER）は、複数のJavaデータ型（例: int、long）と互換性があります。このような場合、渡される実際の値を保持するための十分な容量がある、任意のJavaデータ型を使用できます。互換性のないJavaデータ型に SQL 値を渡すと（またはその逆）、Snowflakeはエラーをスローします。

1(1,2)

この形式は、 タイムスタンプ形式 で説明されているインターネット（RFC）タイムスタンプ形式 DY, DD MON YYYY HH24:MI:SS TZHTZM と一致します。タイムゾーンオフセット（TZHTZM コンポーネント）が存在する場合、通常は数字です（例: -0700 は UTC からマイナス7時間であることをを示す）。タイムゾーンオフセットが数字ではなく Z （「Zulu」の頭文字）の場合、それは「+0000」（UTC）と同義です。

2

この形式は、 タイムスタンプ形式 で説明されているインターネット（RFC）タイムスタンプ形式 DY, DD MON YYYY HH24:MI:SS と一致します。文字列の後にスペースと Z （「Zulu」の頭文字）が続く場合、オフセットが「+0000」（UTC）であることを明示的に示します。

3(1,2,3,4,5,6,7,8)

Snowflakeはナノ秒の精度で時間値を保存できますが、java.sql.timeライブラリはミリ秒の精度しか維持できません。SnowflakeとJavaの間でデータ型を変換すると、実効精度がミリ秒に低下する可能性があります。

4(1,2,3,4,5,6)

この型マッピングは、 SQL 引数をJavaに変換する場合はサポートされますが、Javaの戻り型を SQL 型に変換する場合はサポートされません。

5

JavaにはネイティブのGeographyデータ型がありません。ここで参照されている Geography データ型は、Snowparkパッケージのクラスです。詳細については、 Snowparkパッケージからのサポートされている型 をご参照ください。

Snowparkパッケージからのサポートされている型¶

ユーザー定義関数では、Snowflake SnowparkJavaパッケージ に含まれている型の特定のサブセットを使用できます。これらの型はSnowparkコードで使用するように設計されていますが、 UDFs での使用をサポートしてこれらが提供する利便性も提供します。（Snowparkの詳細については、 Snowparkドキュメント をご参照ください。）

次のテーブルのSnowpark型は、 UDF コードでサポートされています。他のSnowpark型はサポートされていないため、 UDF コードでは使用しないでください。

TIMESTAMP_LTZ 値とタイムゾーン¶

Java UDF は多くの場合、呼び出される環境から分離されています。ただし、タイムゾーンは呼び出し元の環境から継承されます。呼び出し元のセッションがJava UDF を呼び出す前にデフォルトのタイムゾーンを設定した場合、Java UDF のデフォルトのタイムゾーンは同じになります。Java UDF は、ネイティブ TIMEZONE Snowflake SQL が使用するのと同じ IANA タイムゾーンデータベース データを使用します（つまり、タイムゾーンデータベースのリリース 2021a からのデータ）。

NULL 値¶

Snowflakeは、 SQL NULL と VARIANT の JSON null という2つの異なる NULL 値をサポートしています。（Snowflake VARIANT NULL については、 NULL 値 を参照。）

Javaは、1つの null 値をサポートします。これは、非プリミティブデータ型専用です。

Java UDF に対する SQL NULL 引数は、 null をサポートするJavaデータ型の場合にのみ、Java null 値に変換されます。

返されたJava null 値は、 SQL NULL に変換されます。

引数の配列および可変の数¶

Java UDFs は、次に挙げるJavaデータ型のいずれかの配列を受け取ることができます。

• String

• boolean

• double

• float

• int

• long

• short

渡される SQL 値のデータ型には、対応するJavaデータ型との互換性が必要です。データ型の互換性の詳細については、 パラメーターと戻り値型の SQL-Javaデータ型のマッピング をご参照ください。

指定されたJavaデータ型のそれぞれに、次の追加ルールが適用されます。

• boolean: Snowflake ARRAY には BOOLEAN 要素のみが含まれている必要があり、 NULL 値は含まれていてはなりません。

• int/short/long: Snowflake ARRAY には、スケールが0の 固定小数点 要素のみが含まれている必要があり、 NULL 値が含まれていてはなりません。

• float/double: Snowflake ARRAY には次のいずれかが含まれている必要があります。

  • FLOAT 要素。

  • 固定小数点 要素（任意のスケール）。

  ARRAY には NULL の値を含めることはできません。

Javaメソッドは、次に挙げる2つの方法のいずれかでこれらの配列を受け取ることができます。

• Javaの配列機能を使用。

• Javaの varargs （引数の数が可変）機能を使用。

どちらの場合も、 SQL コードは ARRAY を渡す必要があります。

メモリ¶

あまり多くのメモリを消費しないようにしてください。

• 大きなデータ値（通常は BINARY、長い VARCHAR、または大きな ARRAY または OBJECT または VARIANT データ型）は、大量のメモリを消費する可能性があります。

• スタックが深すぎると、大量のメモリを消費する可能性があります。Snowflakeでは、ネストされた50レベルの単純な関数呼び出しをエラーなしでテストしました。実際の上限は、スタックに配置される情報の量によって異なります。

UDFs がメモリを消費しすぎると、エラーを返します。特定の制限は変更される場合があります。

時間¶

呼び出しごとに長い時間がかかるアルゴリズムは避けてください。

UDF の完了に時間がかかりすぎると、Snowflakeは SQL ステートメントを強制終了し、ユーザーにエラーを返します。これにより、無限ループなどのエラーの影響およびコストが制限されます。

ライブラリ¶

Javaメソッドは標準のJavaライブラリのクラスとメソッドを使用できますが、Snowflakeのセキュリティ制限により、ファイルへの書き込みなど、一部の機能が無効になります。ライブラリの制限の詳細については、 優れたセキュリティプラクティスに準拠 というタイトルのセクションをご参照ください。

紹介¶

Snowflakeは、スカラー UDFs が独立して処理されることを期待しています。システムは任意の順序で行を処理し、それらの呼び出しを複数の JVMs に分散できるため、呼び出し間で共有される状態に依存すると、予期しない動作が発生する可能性があります。UDFs ハンドラーメソッドの呼び出し全体で共有状態に依存することは避けてください。ただし、 UDF に共有状態を保存する必要がある状況は2つあります。

• 行ごとに繰り返さない高価な初期化ロジックを含むコード。

• キャッシュなど、行間で共有状態を活用するコード。

複数の行で状態を共有する必要があり、その状態が時間の経過とともに変化しない場合は、コンストラクターを使用してインスタンスレベルの変数を設定し、共有状態を作成します。コンストラクターはインスタンスごとに1回だけ実行されますが、ハンドラーは行ごとに1回呼び出されるため、ハンドラーが複数の行を処理する場合は、コンストラクターによる初期化の方が安価です。また、コンストラクターは1回だけ呼び出されるため、スレッドセーフになるようにコンストラクターを作成する必要はありません。

UDF に変更された共有状態が保存されている場合は、その状態への同時アクセスを処理できるようにコードを準備する必要があります。次の2つのセクションでは、並列処理と共有状態について詳しく説明します。

Java UDF 並列化について¶

パフォーマンスを向上させるために、Snowflakeは JVMs の全体および内部で並列化します。

• JVMs 全体:

  Snowflakeは、 ウェアハウス のワーカー間で並列化されます。各ワーカーは1つ（または複数）の JVMs を実行します。これは、グローバル共有状態がないことを意味します。最大で、状態は単一の JVM 内でのみ共有できます。

• JVMs 内部:

  • 各 JVM は、同じインスタンスのハンドラーメソッドを並行して呼び出すことができる複数のスレッドを実行できます。これは、各ハンドラーメソッドがスレッドセーフである必要があることを意味します。

  • UDF が IMMUTABLE で、 SQL ステートメントが同じ行に対して同じ引数を使用して UDF を複数回呼び出す場合、 UDF は、その行の呼び出しごとに同じ値を返します。たとえば、 UDF が IMMUTABLE の場合、以下は各行に対して同じ値を2回返します。

    select
           my_java_udf(42),
           my_java_udf(42)
        from table1;
    

    同じ引数が渡された場合でも複数の呼び出しで独立した値を返すようにし、関数 VOLATILE を宣言しない場合は、複数の個別の UDFs を同じハンドラーメソッドにバインドします。例:

    1. 次のコードを使用して、 @java_udf_stage/rand.jar という名前の JAR ファイルを作成します。

       class MyClass {
       
           private double x;
       
           // Constructor
           public MyClass()  {
               x = Math.random();
           }
       
           // Handler
           public double myHandler() {
               return x;
           }
       }
       

    2. 以下に示すように、Java UDFs を作成します。これらの UDFs の名前は異なりますが、同じ JAR ファイルと、その JAR ファイル内の同じハンドラーを使用します。

       create function my_java_udf_1()
           returns double
           language java
           imports = ('@java_udf_stage/rand.jar')
           handler = 'MyClass.myHandler';
       
       create function my_java_udf_2()
           returns double
           language java
           imports = ('@java_udf_stage/rand.jar')
           handler = 'MyClass.myHandler';
       

    3. 次のコードは、両方の UDFs を呼び出します。UDFs は、同じ JAR ファイルとハンドラーをポイントします。これらの呼び出しは、同じクラスのインスタンスを2つ作成します。各インスタンスは独立した値を返すため、以下の例では、同じ値を2回返すのではなく、2つの独立した値を返します。

       select
               my_java_udf_1(),
               my_java_udf_2()
           from table1;
       

JVM 状態情報の保存¶

動的共有状態に依存しない理由の1つは、行が必ずしも予測可能な順序で処理されるとは限らないことです。Snowflakeは、 SQL ステートメントが実行されるたびに、バッチの数、バッチが処理される順序、およびバッチ内の行の順序を変更できます。1つの行が後続の行の戻り値に影響を与えるようにスカラー UDF が設計されている場合、 UDF は、 UDF が実行されるたびに異なる結果を返す可能性があります。