Java UDFs の設計¶

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

SnowflakeがJavaと SQL データ型の間で変換する方法については、 SQL とハンドラー言語間のデータ型マッピング をご参照ください。

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 を渡す必要があります。

呼び出し全般での状態の共有¶

Snowflakeは、スカラー UDFs が独立して処理されることを期待しています。呼び出しの間で共有される状態に依存すると、予期しない動作が発生する可能性があります。これは、システムが任意の順序で行を処理し、それらの呼び出しを複数の JVMs（JavaまたはScalaで記述されたハンドラーの場合）またはインスタンス（Pythonで記述されたハンドラーの場合）に分散できるためです。

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;
    

    Copy

    同じ引数が渡された場合でも複数の呼び出しで独立した値を返すようにし、関数 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;
           }
       }
       

       Copy

    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';
       

       Copy

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

       select
               my_java_udf_1(),
               my_java_udf_2()
           from table1;
       

       Copy

JVM 状態情報の保存¶

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