Java UDF ハンドラーの例¶

NULL のインラインJava UDF への引き渡し¶

これは、上記で定義された echo_varchar() UDF を使用します。SQL NULL 値は暗黙的にJava null に変換され、そのJava null が返され、暗黙的に SQL NULL に変換されます。

UDF を呼び出します。

SELECT echo_varchar(NULL);
+--------------------+
| ECHO_VARCHAR(NULL) |
|--------------------|
| NULL               |
+--------------------+

ARRAY 経由の引き渡し¶

Javaパラメーターを配列として宣言します。たとえば、次に挙げるメソッドの3番目のパラメーターは文字列配列です。

static int myMethod(int fixedArgument1, int fixedArgument2, String[] stringArray)

Copy

以下は包括的な例です。

テーブルを作成してロードします。

CREATE TABLE string_array_table(id INTEGER, a ARRAY);
INSERT INTO string_array_table (id, a) SELECT
        1, ARRAY_CONSTRUCT('Hello');
INSERT INTO string_array_table (id, a) SELECT
        2, ARRAY_CONSTRUCT('Hello', 'Jay');
INSERT INTO string_array_table (id, a) SELECT
        3, ARRAY_CONSTRUCT('Hello', 'Jay', 'Smith');

Copy

UDF を作成します。

create or replace function concat_varchar_2(a ARRAY)
returns varchar
language java
handler='TestFunc_2.concatVarchar2'
target_path='@~/TestFunc_2.jar'
as
$$
    class TestFunc_2 {
        public static String concatVarchar2(String[] strings) {
            return String.join(" ", strings);
        }
    }
$$;

Copy

UDF を呼び出します。

SELECT concat_varchar_2(a)
    FROM string_array_table
    ORDER BY id;
+---------------------+
| CONCAT_VARCHAR_2(A) |
|---------------------|
| Hello               |
| Hello Jay           |
| Hello Jay Smith     |
+---------------------+

Copy

Varargs経由の引き渡し¶

Varargsの使用は、配列の使用と非常によく似ています。

Javaコードでは、Javaのvarargs宣言スタイルを使用します。

static int myMethod(int fixedArgument1, int fixedArgument2, String ... stringArray)

Copy

以下は包括的な例です。この例と前の例（配列の場合）の間における唯一の重要な違いは、メソッドへのパラメーター宣言です。

テーブルを作成してロードします。

CREATE TABLE string_array_table(id INTEGER, a ARRAY);
INSERT INTO string_array_table (id, a) SELECT
        1, ARRAY_CONSTRUCT('Hello');
INSERT INTO string_array_table (id, a) SELECT
        2, ARRAY_CONSTRUCT('Hello', 'Jay');
INSERT INTO string_array_table (id, a) SELECT
        3, ARRAY_CONSTRUCT('Hello', 'Jay', 'Smith');

Copy

UDF を作成します。

create or replace function concat_varchar(a ARRAY)
returns varchar
language java
handler='TestFunc.concatVarchar'
target_path='@~/TestFunc.jar'
as
$$
    class TestFunc {
        public static String concatVarchar(String ... stringArray) {
            return String.join(" ", stringArray);
        }
    }
$$;

Copy

UDF を呼び出します。

SELECT concat_varchar(a)
    FROM string_array_table
    ORDER BY id;
+-------------------+
| CONCAT_VARCHAR(A) |
|-------------------|
| Hello             |
| Hello Jay         |
| Hello Jay Smith   |
+-------------------+

Copy

前提条件¶

ファイルをコードで使用できるようにするには、Javaハンドラーコードがステージ上のファイルを読み取る前に、次を実行する必要があります。

1. ハンドラーが使用できるステージを作成する。

   外部ステージまたは内部ステージを使用できます。内部ステージを使用する場合は、ユーザーまたは名前付きステージにする必要があります。Snowflakeは現在、 UDF 依存関係のテーブルステージの使用をサポートしていません。ステージの作成の詳細については、 CREATE STAGE をご参照ください。内部ステージ型の選択の詳細については、 ローカルファイルに対する内部ステージの選択 をご参照ください。

   ステージから読み取る SQL アクションを実行するロールには、ステージに対する適切な権限を割り当てる必要があることに注意してください。詳細については、 Granting Privileges for User-Defined Functions をご参照ください。

2. ステージに、コードで読み取られるファイルをコピーする。

   PUT コマンドを使用して、ファイルをローカルドライブからステージにコピーできます。コマンドリファレンスについては、 PUT をご参照ください。PUT を使用したファイルのステージングについては、 ローカルファイルシステムからのデータファイルのステージング をご参照ください。

IMPORTS で静的に指定されたファイルの読み取り¶

ハンドラーは、ステージングされたパスが CREATE FUNCTION コマンドの IMPORTS 句で指定されているファイルを読み取ることができます。

IMPORTS 句でファイルを指定すると、Snowflakeはそのファイルをステージから UDF の ホームディレクトリ （別称 インポートディレクトリ）にコピーします。UDF は、ホームディレクトリから実際にファイルを読み取ります。

インポートされたファイルは単一のディレクトリにコピーされ、そのディレクトリ内で一意の名前を付ける必要があるため、ファイルが異なるステージまたはステージ内の異なるサブディレクトリで開始された場合でも、 IMPORTS 句の各ファイルに異なる名前を付ける必要があります。

次の例では、ファイルを読み取るJava UDF を作成して呼び出します。

以下のJavaソースコードは、 readFile という名前のJavaメソッドを作成します。この UDF はこのメソッドを使用します。

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.stream.Stream;

class TestReadRelativeFile {
    public static String readFile(String fileName) throws IOException {
        StringBuilder contentBuilder = new StringBuilder();
        String importDirectory = System.getProperty("com.snowflake.import_directory");
        String fPath = importDirectory + fileName;
        Stream<String> stream = Files.lines(Paths.get(fPath), StandardCharsets.UTF_8);
        stream.forEach(s -> contentBuilder.append(s).append("\n"));
        return contentBuilder.toString();
    }
}

次の SQL コードは UDF を作成します。このコードは、Javaソースコードがコンパイルされ、 UDF がインポートする TestReadRelativeFile.jar という名前の JAR ファイルに配置されていることを前提としています。2番目と3番目のインポートされたファイル my_config_file_1.txt と my_config_file_2.txt は、 UDF が読み取ることができる構成ファイルです。

CREATE FUNCTION file_reader(file_name VARCHAR)
RETURNS VARCHAR
LANGUAGE JAVA
IMPORTS = ('@my_stage/my_package/TestReadRelativeFile.jar',
           '@my_stage/my_path/my_config_file_1.txt',
           '@my_stage/my_path/my_config_file_2.txt')
HANDLER = 'my_package.TestReadRelativeFile.readFile';

このコードは UDF を呼び出します。

SELECT file_reader('my_config_file_1.txt') ...;
...
SELECT file_reader('my_config_file_2.txt') ...;

... imports = ('@MyStage/MyData.txt.gz', ...)

SnowflakeFile を使用した動的に指定されたファイルの読み取り¶

SnowflakeFile クラスのメソッドを使用すると、Javaハンドラーコードを使用してステージからファイルを読み取ることができます。 SnowflakeFile クラスは、SnowflakeのJava UDF ハンドラーが使用できるクラスパスに含まれています。

UDF コードをローカルで開発するには、 SnowflakeFile を含んでいるSnowpark JAR をコードのクラスパスに追加します。 snowpark.jar については、 Snowpark Javaの開発環境の設定 をご参照ください。Snowparkクライアントアプリケーションは、このクラスを使用できないことに注意してください。

SnowflakeFile を使用する場合は、 SQL で CREATE FUNCTION ステートメントを使用する場合のように、 UDF の作成時に、ステージングされたファイル、または SnowflakeFile を含んでいる JAR のいずれかを IMPORTS 句で指定する必要はありません。

次の例のコードは、 SnowflakeFile を使用して、指定されたステージの場所からファイルを読み取ります。 getInputStream メソッドの InputStream を使用して、ファイルの内容を String 変数に読み込みます。

CREATE OR REPLACE FUNCTION sum_total_sales(file string)
RETURNS INTEGER
LANGUAGE JAVA
HANDLER = 'SalesSum.sumTotalSales'
TARGET_PATH = '@jar_stage/sales_functions2.jar'
AS
$$
import java.io.InputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import com.snowflake.snowpark_java.types.SnowflakeFile;

public class SalesSum {

  public static int sumTotalSales(String filePath) throws IOException {
    int total = -1;

    // Use a SnowflakeFile instance to read sales data from a stage.
    SnowflakeFile file = SnowflakeFile.newInstance(filePath);
    InputStream stream = file.getInputStream();
    String contents = new String(stream.readAllBytes(), StandardCharsets.UTF_8);

    // Omitted for brevity: code to retrieve sales data from JSON and assign it to the total variable.

    return total;
  }
}
$$;

UDF を呼び出してスコープ URL でファイルの場所を渡し、ファイルインジェクション攻撃の可能性を減らします。

SELECT sum_total_sales(BUILD_SCOPED_FILE_URL('@sales_data_stage', '/car_sales.json'));

String filename = "@my_stage/filename.txt";
String sfFile = SnowflakeFile.newInstance(filename, false);

InputStream を使用した動的に指定されたファイルの読み取り¶

ハンドラー関数の引数を InputStream 変数にすると、ファイルの内容を直接 java.io.InputStream に読み込むことができます。これは、関数の呼び出し元が引数としてファイルパスを渡す場合に役立ちます。

次の例のコードには、 InputStream を受け取り、 int を返すハンドラー関数 sumTotalSales があります。実行時に、Snowflakeは file 変数のパスにあるファイルの内容を stream 引数変数に自動で割り当てます。

CREATE OR REPLACE FUNCTION sum_total_sales(file string)
RETURNS INTEGER
LANGUAGE JAVA
HANDLER = 'SalesSum.sumTotalSales'
TARGET_PATH = '@jar_stage/sales_functions2.jar'
AS
$$
import java.io.InputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;

public class SalesSum {

  public static int sumTotalSales(InputStream stream) throws IOException {
    int total = -1;
    String contents = new String(stream.readAllBytes(), StandardCharsets.UTF_8);

    // Omitted for brevity: code to retrieve sales data from JSON and assign it to the total variable.

    return total;
  }
}
$$;

UDF を呼び出してスコープ URL でファイルの場所を渡し、ファイルインジェクション攻撃の可能性を減らします。

SELECT sum_total_sales(BUILD_SCOPED_FILE_URL('@sales_data_stage', '/car_sales.json'));

Javaハンドラーコードを作成しコンパイルする¶

1. プロジェクトのルートディレクトリ（ここでは my_udf）に、ソース.javaファイルを保持する src サブディレクトリと、生成された.classファイルを保持する classes サブディレクトリを作成します。

   次のようなディレクトリ階層が必要です。

   my_udf/
   |-- classes/
   |-- src/
   

   Copy

2. src ディレクトリに、クラスが mypackage パッケージにある.javaファイルを保持する、 mypackage というディレクトリを作成します。

3. mypackage ディレクトリに、ソースコードを含む MyUDFHandler.java ファイルを作成します。

   package mypackage;
   
   public class MyUDFHandler {
   
     public static int decrementValue(int i)
     {
         return i - 1;
     }
   
     public static void main(String[] argv)
     {
         System.out.println("This main() function won't be called.");
     }
   }
   

   Copy

4. プロジェクトのルートディレクトリ（ここでは my_udf）から、 javac コマンドを使用してソースコードをコンパイルします。

   次の例の javac コマンドは、 MyUDFHandler.java をコンパイルして、 classes ディレクトリに MyUDFHandler.class ファイルを生成します。

   javac -d classes src/mypackage/MyUDFHandler.java
   

   Copy

   この例には、次の引数が含まれています。

   • -d classes --- 生成されたクラスファイルを書き込むディレクトリ。

   • src/mypackage/MyUDFHandler.java --- .javaファイルへの source_directory/package_directory/Java_file_name 形式のパス。

コンパイルされたコードを JAR ファイルにパッケージ化する¶

1. オプションで、プロジェクトのルートディレクトリに、次の属性を含む my_udf.manifest という名前のマニフェストファイルを作成します。

   Manifest-Version: 1.0
   Main-Class: mypackage.MyUDFHandler
   

   Copy

2. プロジェクトのルートディレクトリから、 jar コマンドを実行して、.classファイルとマニフェストを含む JAR ファイルを作成します。

   次の例の jar コマンドは、 mypackage パッケージフォルダーに生成された MyUDFHandler.class ファイルを my_udf.jar という.jarファイルに配置します。 -C ./classes フラグは、.classファイルの場所を指定します。

   jar cmf my_udf.manifest my_udf.jar -C ./classes mypackage/MyUDFHandler.class
   

   Copy

   この例には、次の引数が含まれています。

   • cmf --- コマンド引数: c は JAR ファイルを作成し、 m は指定された.manifestファイルを使用し、 f は JAR ファイルに指定された名前を付けます。

   • my_udf.manifest --- マニフェストファイル。

   • my_udf.jar --- 作成する JAR ファイルの名前。

   • -C ./classes --- 生成された.classファイルを含むディレクトリ。

   • mypackage/MyUDFHandler.class --- JAR に含める.classファイルのパッケージと名前。

コンパイルされたハンドラーを使用して JAR ファイルをステージにアップロードする¶

1. Snowflakeで、 UDF ハンドラーを含む JAR ファイルを保存するために、 jar_stage というステージを作成します。

   ステージの作成の詳細については、 CREATE STAGE をご参照ください。

2. PUT コマンドを使用して、 JAR ファイルをローカルファイルシステムからステージにコピーします。

put
    file:///Users/Me/my_udf/my_udf.jar
    @jar_stage
    auto_compress = false
    overwrite = true
    ;

Copy

PUT コマンドをスクリプトファイルに保存してから、 SnowSQL を介してそのファイルを実行できます。

snowsql コマンドは次のようになります。

snowsql -a <account_identifier> -w <warehouse> -d <database> -s <schema> -u <user> -f put_command.sql

Copy

この例では、ユーザーのパスワードが SNOWSQL_PWD 環境変数で指定されていることを前提としています。

コンパイルされたコードをハンドラーとして UDF を作成する¶

UDF を作成します。

create function decrement_value(i numeric(9, 0))
  returns numeric
  language java
  imports = ('@jar_stage/my_udf.jar')
  handler = 'mypackage.MyUDFHandler.decrementValue'
  ;

UDF を呼び出します。

select decrement_value(-15);
+----------------------+
| DECREMENT_VALUE(-15) |
|----------------------|
|                  -16 |
+----------------------+